token-limiter

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

pip install token-limiter

Quick start

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 }:

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

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

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

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:

from token_limiter import TokenTracker, BudgetMonitor, KillSwitch, AnomalyDetector

Demo

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
• Blog: Building Kill-Switches for Autonomous AI Agents

License

MIT © Hemanth.HM