Metadata-Version: 2.4
Name: agentbelt-budget
Version: 0.1.0
Summary: A lightweight, in-process circuit breaker for LLM token and cost budgets. Part of the agentbelt suite.
Author: Saptarshi Bhattacharjee
License-Expression: MIT
Project-URL: Homepage, https://github.com/bsaptarshi/agentbelt
Keywords: llm,agents,circuit-breaker,cost,tokens,observability
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: agentbelt-core>=0.1.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# agentbelt-budget

A lightweight, in-process circuit breaker for LLM token and cost spend.
Part of the [agentbelt](https://github.com/bsaptarshi/agentbelt) suite.

```bash
pip install agentbelt-budget
```

## Quickstart

```python
from agentbelt_budget import Budget, CircuitBreaker, BudgetExceeded

breaker = CircuitBreaker(Budget(max_tokens=100_000, max_cost_usd=5.0, window="24h"))

try:
    breaker.check("session-123")
    response = call_llm(prompt)
    breaker.record_response("session-123", response, model="gpt-4o")
except BudgetExceeded as e:
    print(f"blocked: {e}")
```

## What did this actually catch?

```python
print(breaker.impact_report())
# 5 call(s) blocked across 1 session(s) before exceeding budget (1 distinct trip event(s))
```

Countable events (calls blocked, distinct sessions, trip count) — not a
dollar estimate, since there's no way to know what a blocked call would
have actually cost. `.metrics` on the returned `ImpactReport` gives the
same numbers as a plain dict if you want to log or export them.

See the [suite README](https://github.com/bsaptarshi/agentbelt) for the
full concept and how this fits with `agentbelt-loop` and
`agentbelt-sampler`.

## License

MIT
