Metadata-Version: 2.4
Name: token-budget-contracts
Version: 0.1.1
Summary: Priority-weighted, confidence-gated token budget governance for multi-agent LLM systems.
Project-URL: Homepage, https://github.com/swaranshu-borgaonkar/token-budget-contracts
Project-URL: Repository, https://github.com/swaranshu-borgaonkar/token-budget-contracts
Author: Swaranshu Borgaonkar
License-Expression: MIT
License-File: LICENSE
Keywords: agents,budget,crewai,langgraph,llm,multi-agent,orchestration,tokens
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Provides-Extra: accurate-tokenizer
Requires-Dist: tiktoken>=0.5; extra == 'accurate-tokenizer'
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
pip install token-budget-contracts
```

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

```bash
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

```python
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

```python
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:

```python
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.
