One runtime, one contract for functions and AI. Deterministic functions carry the load; a model runs only on the steps that genuinely need reasoning — bounded, supervised, and metered. Most of your workflow never calls an LLM.
9 step kinds · 2 call a modelBounded loops · token_budgetSupervisor · budget rulesAny model via LiteLLM
tuvl
The cost problem
Traditional AI coding routes everything through the model.
Agent frameworks make the LLM the substrate — it decides control flow, drives loops, and re-reasons work a plain function could do. The token bill is the direct cost of that design.
The model decides the flow.Every branch is a prompt. Routing that a rule could do for free is paid for, every request.
Loops run unbounded.One stuck task retries, re-plans, and re-calls tools until it gives up — a single agent can burn a day's budget.
Deterministic work goes to the LLM.Fetching a record, writing a row, calling an API — dressed up as "reasoning" and billed per token.
Spend scales with usage — and can't be capped.No per-run ceiling, no early kill. Finance can't forecast it and engineering can't bound it.
Usage goes up. The bill goes up faster. And no one can tell you what next month costs.
tuvl
The tuvl model
7 of 9 step kinds never call a model.
A tuvl workflow is mostly deterministic. AI is one opt-in step kind — not the ground you build on. The same YAML composes token-free functions and metered reasoning into one governed flow.
Deterministic · 0 tokens
Functional
Router
APICall
MCP
ModelOp
Response
HumanInTheLoop
Run Python, branch on data, call an API, invoke an MCP tool, do CRUD on Postgres, pause for a human, and respond — real work, no model, no per-token cost.
Reasoning · metered
Agent
AutonomousAgent
A single governed call, or a bounded tool-loop — invoked only on the steps that truly need judgment. This is the only place a token is spent.
7 / 9
step kinds are token-free by design
2 / 9
call a model — and only when you place them
1 contract
functions + reasoning, one YAML flow
You pay for intelligence — never for plumbing.
tuvl
Token economics · the differentiator
Every token is a decision you made on purpose.
tuvl's structure is the cost control. Five mechanisms keep spend bounded, predictable, and auditable — none of them bolted on, all declared in the workflow.
Branch for free.A Router with match: routes on real data — no prompt, no token. Deterministic logic never touches the model.
Do the work at zero tokens.APICall, ModelOp (CRUD), MCP, and Functional fetch, write, and compute without a model — even as an agent's tools.
Cap every loop.max_iterations + optional token_budget bound each autonomous run. A run can't exceed its ceiling — budget_exceeded exits cleanly.
Guard for free, judge only when needed.Supervisor budget_fraction / tool_repeated rules run every turn with no LLM; the judge model is cost-gated by every_n_iterations.
Parse once.Structured output maps straight into typed context — no second prompt to re-read the model's own answer.
~40–70%
est. fewer tokens on a typical mixed workflow vs. an all-LLM design
up to ~90%
est. saved on a stuck run that would otherwise loop to its cap
100%
of routing, CRUD, and rule checks run at zero tokens
Estimates, illustrative — actual savings track how much of your flow is deterministic. The more of the work that's functions, the more you keep.
Predictable, cappable, auditable spend — by construction, not by watching a dashboard.
tuvl
Reasoning · when you do spend
When a step needs judgment, the loop is still bounded.
kind: Agent
A single governed LLM call
Declared model, prompt, and structured output. Deterministic routing on the result. Every model it touches must be allow-listed in spec.context.models — enforced at load, or it fails to start.
kind: AutonomousAgent
A bounded ReAct tool-loop
The model picks declared tools, observes results, and re-decides — until an author-defined outcome or a reserved exit. Tools are other declared steps (APICall / MCP / ModelOp / Functional) — themselves token-free.
LiteLLM native tool-calling — no torch, no langchain
steering + skills
per-agent scoped .md — less prompt, more signal
tuvl
Governance · budget control in flight
A watcher on every run — that can pull the plug on spend.
A per-workflow spec.supervisor runs out-of-band for each AutonomousAgent, evaluating the live event stream and intervening cooperatively — at the turn boundary, never mid-call, so no state is torn and no token is wasted on a doomed loop.
Free rules
Every turn, no LLM
budget_fraction, tool_repeated, iteration_reached — catch a runaway before it burns the budget, at zero token cost.
LLM criteria
Only every N turns
A judge model checks the run against a natural-language policy — cost-gated by every_n_iterations, so it runs only when it earns its keep.
Interventions
pause · steer · abort
Steer a drifting run back, pause it, or abort cleanly. Every action is logged and streamed for audit.
Plus a human escape hatch — /api/agents: observe, pause, resume, steer, or kill any live run. A runaway agent can't run away with your budget.
tuvl
Observability · cost visibility
Every token, tool, and turn — traced by construction.
Cost you can't see is cost you can't govern. tuvl emits the spend as first-class telemetry — into the same APM finance and engineering already watch.
Token usage in every span.LiteLLM emits gen_ai.* semantic-convention spans — model, tokens, latency — exported via TUVL_OTLP_ENDPOINT to Grafana, Datadog, or Honeycomb. Attribute cost per workflow, per run.
Per-iteration agent trace.An autonomous run streams iteration / tool_call / outcome / supervisor frames live — see exactly where the tokens went, not one opaque step.
LLM-as-a-Judge.One strict Scorecard{passed, reason} — grade AI output in CI, live in the Supervisor, or on a replayed run. Catch regressions before they ship, not on the invoice.
Structured logs + PII masking.structlog logfmt/JSON correlated to the trace; fields marked secure: true masked on every stream — REST, SSE, gRPC alike.
The token bill stops being a surprise — it's a metric you already have a graph for.
tuvl
Security · and the bottom line
Cost-controlled, governed, and audited — in one contract.
Biscuit IAM, scoped to the edge.Offline-verifiable capabilities; every route scope-guarded; dedicated agent:observe / agent:control scopes for the operator API. iam:admin is the only bypass.
Closed-set enforcement at load.Touch a model absent from spec.context.models → PermissionError. Unmapped routes raise. No hidden behavior — and no hidden token spend — can slip in.
Right model for the job.Any provider via LiteLLM — route a cheap local model for routine steps, a frontier model only where it pays. Swap models in YAML, not in code.
Passes a security review.A deep audit of 86 findings — all closed. PII masking and sanitized errors on every surface.
Business logic in YAML. An estimated 40–70% fewer tokens on a typical workflow. Governance and cost control, one contract.