Metadata-Version: 2.4
Name: token-budget-contracts
Version: 0.3.0
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: crewai
Requires-Dist: crewai>=0.1; extra == 'crewai'
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Provides-Extra: langgraph
Requires-Dist: langgraph>=0.1; extra == 'langgraph'
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.20; extra == 'otel'
Requires-Dist: opentelemetry-sdk>=1.20; extra == 'otel'
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 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:

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

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

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

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

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

Install the extra with:

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