token-budget-contracts 0.1.1

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

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 if you want exact dollar accounting, bypass the estimator and record real usage directly:

response = my_llm_call(prompt)
manager.ledger.record("researcher", response.usage.total_tokens)

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.