Token Budget Contracts (tbcontracts)

Priority-weighted, confidence-gated token budget governance for multi-agent LLM systems.

When a multi-agent system (a planner spawning a researcher, a writer, a critic, etc.) is running, every sub-agent burns tokens — and money. Most projects today either hardcode a flat cap per agent or don't budget at all, so an important agent can starve mid-task while a less important one sits on unused budget. tbcontracts fixes that by letting unused budget flow, in real time, from lower-priority or idle agents to whichever agent actually needs it right now — without ever starving the donor below a protected minimum reserve, and without ever letting tokens flow "uphill" from an important agent to a less important one.

It also supports confidence-gated spending: once an agent reports a high-confidence result, further spending on that agent is automatically blocked, so you're not paying for retrieval the model didn't need.

This implements the governance model described in U.S. Provisional Patent Application No. 64/081,925 ("Token Budget Contracts"), filed June 3, 2026, and published research (Zenodo DOI: 10.5281/zenodo.20549509). The patent application is pending; this package's code is released under the MIT license. If you plan to use this commercially at scale, consult your own counsel on licensing terms.

Install

pip install token-budget-contracts

For more accurate token counting (OpenAI/Anthropic-style BPE tokenizer), install the optional extra:

pip install "token-budget-contracts[accurate-tokenizer]"

Without it, the library falls back to a lightweight word-count heuristic and has zero hard dependencies.

Quick start

from tbcontracts import BudgetManager

manager = BudgetManager()

# Higher priority = more important. The researcher will be able to pull
# spare budget from the lower-priority critic agent if it runs low.
manager.register_agent("researcher", priority=3, max_tokens=4000)
manager.register_agent("critic", priority=1, max_tokens=2000)

@manager.govern("researcher")
def call_researcher(prompt: str) -> str:
    return my_llm_call(prompt)  # however you already call your LLM

@manager.govern("critic")
def call_critic(prompt: str) -> str:
    return my_llm_call(prompt)

call_researcher("find the latest figures on X")
call_critic("check the researcher's claims")

print(manager.report())
# {'researcher': {'allocated': 4000, 'consumed': 312, 'remaining': 3688},
#  'critic':     {'allocated': 2000, 'consumed': 88,  'remaining': 1912}}

Confidence-gated spending

manager.register_agent(
    "fact_checker",
    priority=2,
    max_tokens=3000,
    confidence_threshold=0.85,  # block further calls once this confident
)

@manager.govern("fact_checker", confidence_fn=lambda result: result["confidence"])
def check_fact(claim: str) -> dict:
    response = my_llm_call(claim)
    return {"answer": response, "confidence": extract_confidence(response)}

Once check_fact returns a confidence at or above 0.85, the next call to check_fact raises BudgetExceededError — the agent has already done its job well enough, so further spend isn't approved.

What happens when an agent runs out of budget

1. tbcontracts estimates how many tokens the call used (or you can call manager.ledger.record(agent_name, exact_token_count) directly if your LLM provider returns real usage numbers).
2. If the agent doesn't have enough remaining budget, the Reallocator looks for spare capacity in other agents — starting with the lowest-priority, most-idle ones — and pulls just enough to cover the shortfall, never dipping a donor below its own min_reserve.
3. If no combination of donors can cover the shortfall, a BudgetExceededError is raised so you can handle it (retry, degrade gracefully, alert, etc.) instead of silently overspending.

Exact accounting

The built-in token estimate is good enough for budget governance decisions, but when your LLM provider returns real usage numbers, record them exactly with record_usage. Unlike a raw ledger write, this still enforces the contract — it triggers reallocation and raises BudgetExceededError if the agent is over budget:

response = my_llm_call(prompt)
manager.record_usage(
    "researcher",
    response.usage.total_tokens,   # exact count from the provider
    confidence=0.92,               # optional, feeds the confidence gate
)

Framework adapters

TBC is framework-agnostic at its core, but ships thin adapters so you can govern agents in LangGraph and CrewAI without rewriting your code. Neither framework is a hard dependency.

LangGraph

LangGraph nodes are just callables that take state and return a state update, so TBC wraps them directly. If a node knows its real token usage, have it write that number into the returned state and point the adapter at the key:

from tbcontracts.adapters import TBCGraphGovernor

governor = TBCGraphGovernor()
governor.register("researcher", priority=3, max_tokens=4000)
governor.register("critic", priority=1, max_tokens=2000)

graph.add_node(
    "researcher",
    governor.wrap("researcher", researcher_node, usage_key="tokens_used"),
)
graph.add_node(
    "critic",
    governor.wrap("critic", critic_node, usage_key="tokens_used"),
)

# ...run the graph as usual...
print(governor.report())

CrewAI

CrewAI's execution internals move between releases, so the adapter governs at the stable boundary: a callable that runs an agent's work and returns its output. Provide a usage_fn to read exact usage from CrewAI's metrics:

from tbcontracts.adapters import TBCCrewGovernor

governor = TBCCrewGovernor()
governor.register("researcher", priority=3, max_tokens=4000)

run_researcher = governor.wrap(
    "researcher",
    lambda: researcher.execute_task(task),
    usage_fn=lambda out: out.token_usage.total_tokens,
)
output = run_researcher()
print(governor.report())

OpenTelemetry integration

TBC can emit an OpenTelemetry span for every governance decision - agent registration, usage recording, cross-agent reallocation, and confidence-gate blocks - so you can watch budget activity in Grafana, Datadog, Honeycomb, Jaeger, or any OTLP backend alongside your existing agent traces.

It's opt-in and has no hard dependency: if OpenTelemetry isn't installed, enabling telemetry is a silent no-op and the library behaves exactly as before.

from tbcontracts import BudgetManager

manager = BudgetManager()
manager.enable_telemetry()   # uses the global OTel tracer provider
manager.register_agent("researcher", priority=3, max_tokens=4000)

Or inject a specific tracer:

from opentelemetry import trace
manager = BudgetManager(telemetry=trace.get_tracer("my-app"))

Install the extra with:

pip install "token-budget-contracts[otel]"

Spans are named tbc.<event> (e.g. tbc.reallocate, tbc.record_usage, tbc.confidence_gate_block) and carry attributes like the agents involved, tokens moved, and confidence scores. Configure your exporter the usual OTel way; TBC only produces the spans.

Project status

This is an early, actively developed implementation of the Token Budget Contracts protocol. Issues and PRs welcome at the GitHub repository linked in the project metadata.

License

MIT for the code in this package. See LICENSE. The underlying governance method is the subject of a pending U.S. patent application; see the note above.