How tuvl-io/tuvl works
tuvl is a YAML-declared workflow platform: users define contracts and agents, validate them, then serve and operate durable runs through APIs or the CLI. Insight adds a development UI and spec-driven authoring, review, and task workflows. The graph combines documented product stages with source-index-supported internal links; several capabilities are documented but their implementation files were not sampled, so those relationships are not asserted.
Main entry points: host.py Runtime Host · app.py Application Host · schema.py Workflow Documents · engines.py Engine Dispatch
Components 22
Authoring and Insight
- Specs and Tasks
insight/src/tuvl_insight/spec/tasks.py - Code Review
insight/src/tuvl_insight/cli/commands/review.py - Insight UI
ui/src/App.tsx - Insight Dev API
insight/src/tuvl_insight/api/dev_core_router.py - Audit Ledger
insight/src/tuvl_insight/audit/live.py
Contracts and Configuration
- Workflow Documents
src/tuvl/contract/schema.py - Contract Registry
src/tuvl/contract/registry.py - Project Configuration
src/tuvl/core/config.py - Config Loader
src/tuvl/core/config_loader.py - Workflow Validation
insight/src/tuvl_insight/validate/workflow/engines.py
Workflow Execution
- Runtime Host
src/tuvl/runtime/host.py - Engine Dispatch
src/tuvl/runtime/engines.py - Run Journal
src/tuvl/runtime/journal.py - Blob Storage
src/tuvl/storage/store.py
API and Operations
- Application Host
src/tuvl/core/app.py - REST and SSE
src/tuvl/api/runs.py - MCP Export
src/tuvl/api/mcp_export.py
Security and State
- Database Sources
src/tuvl/core/datasources/postgres.py - Identity and Access
src/tuvl/core/auth/router.py
Other components
- Developer
- Workflow Caller
- Model Provider
Connections 23
- Developer → Specs and Tasks: authors specs
README.md - Developer → Insight UI: uses dev UI
README.md - Specs and Tasks → Audit Ledger: records activity
insight/src/tuvl_insight/spec/tasks.py - Developer → Workflow Documents: declares workflow
README.md - Workflow Documents → Contract Registry: registers contracts
src/tuvl/contract/registry.py - Config Loader → Contract Registry: registers documents
src/tuvl/core/config_loader.py - Config Loader → Project Configuration: reads settings
src/tuvl/core/config_loader.py - Workflow Documents → Workflow Validation: checked by
README.md - Developer → Code Review: requests review
README.md - Insight UI → Insight Dev API: calls dev API
- Application Host → Config Loader: loads configuration
src/tuvl/core/app.py - Application Host → Runtime Host: starts runtime
src/tuvl/core/app.py - Application Host → REST and SSE: mounts routes
src/tuvl/core/app.py - Application Host → Identity and Access: mounts auth
src/tuvl/core/app.py - Workflow Caller → REST and SSE: submits run
README.md - REST and SSE → Runtime Host: dispatches run
README.md - Runtime Host → Engine Dispatch: dispatches agents
src/tuvl/runtime/engines.py - Engine Dispatch → Model Provider: requests inference
README.md - Runtime Host → Run Journal: journals steps
README.md - Runtime Host → Database Sources: uses transactions
- Engine Dispatch → Blob Storage: uses declared tools
- Workflow Documents → MCP Export: exports enabled triggers
README.md - Identity and Access → Database Sources: persists IAM state
src/tuvl/core/auth/router.py