Metadata-Version: 2.4
Name: token-limiter
Version: 1.0.0
Summary: Token budget monitoring and kill-switches for autonomous AI agents.
Project-URL: Homepage, https://github.com/nicedoc/token-limiter-py
Project-URL: Repository, https://github.com/nicedoc/token-limiter-py
Project-URL: Blog, https://h3manth.com/scribe/zero-overhead-token-limiter/
Author-email: Hemanth HM <hemanth.hm@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,budget,kill-switch,llm,monitoring,tokens
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# token-limiter

Token budget monitoring and kill-switches for autonomous AI agents. Zero dependencies.

```bash
pip install token-limiter
```

## Quick start

```python
from token_limiter import token_limiter, from_openai

budget = token_limiter(max_tokens=500_000, max_cost=5.00)

response = openai.chat.completions.create(model="gpt-4o", messages=messages)
budget.record(from_openai(response))

if not budget.ok:
    print(budget.reason)
```

`from_openai()` maps the response to `{ input, output, reasoning }`. `record()` tracks it, checks the ceiling, runs the circuit breaker. `ok` tells you if the agent should continue.

## Adapters

One adapter per provider. Each returns `{ input, output, reasoning }`:

```python
from token_limiter import from_openai, from_gemini, from_anthropic, from_ollama, from_raw

budget.record(from_openai(response))             # OpenAI, Groq, Together, Fireworks, LM Studio
budget.record(from_gemini(response))             # Google AI Studio, Vertex
budget.record(from_anthropic(response))          # Claude
budget.record(from_ollama(response))             # Ollama, any local model
budget.record(from_raw(3200, 800, reasoning=5400))  # raw numbers
```

Works with any provider that returns token counts. If yours isn't listed, use `from_raw()`.

## What `token_limiter()` gives you

```python
budget.ok          # should the agent continue?
budget.reason      # why it stopped, or None
budget.usage       # CumulativeUsage(input, output, reasoning, total)
budget.cost        # CostEstimate(input, output, reasoning, total) in USD
budget.turns       # number of turns recorded
budget.history     # full turn history
budget.analyze()   # run anomaly detection
```

## Config

```python
budget = token_limiter(
    max_tokens=500_000,            # token ceiling
    max_cost=5.00,                 # dollar ceiling
    max_duplicate_calls=3,         # identical tool calls before kill
    reasoning_pct_threshold=80,    # reasoning % to flag
    input_rate=0.00125,            # $/1K input tokens
    output_rate=0.01,              # $/1K output tokens
    reasoning_rate=0.0125,         # $/1K reasoning tokens
)
```

## Events

```python
budget.on("warning", lambda e: print(e["message"]))       # 50%, 75%, 90% thresholds
budget.on("tripped", lambda e: print(e["violations"]))     # circuit breaker fired
```

## Individual modules

If you need more control, the internals are exported too:

```python
from token_limiter import TokenTracker, BudgetMonitor, KillSwitch, AnomalyDetector
```

## Demo

```bash
python examples/demo.py
```

Simulates 20 turns across healthy → degrading → rogue phases. Kill-switch trips when cost ceiling breaches.

## Related

- [Feature request on Antigravity SDK](https://github.com/google-antigravity/antigravity-sdk-python/issues/59)
- [Blog: Building Kill-Switches for Autonomous AI Agents](https://h3manth.com/scribe/zero-overhead-token-limiter/)

## License

MIT © [Hemanth.HM](https://h3manth.com)
