TokenFence

Cost circuit breaker for AI agents. Guard your LLM spend with automatic model downgrade and kill switch. Supports OpenAI, Anthropic Claude, Google Gemini, and DeepSeek.

Install

pip install tokenfence[openai]

Quick Start

import openai
from tokenfence import guard

client = guard(
    openai.OpenAI(),
    budget='$0.50',
    fallback='gpt-4o-mini',
    on_limit='stop',
)

# Use exactly like a normal OpenAI client
response = client.chat.completions.create(
    model='gpt-4o',
    messages=[{'role': 'user', 'content': 'Hello'}],
)

# Check spend
print(client.tokenfence.spent)      # 0.0023
print(client.tokenfence.remaining)  # 0.4977
print(client.tokenfence.calls)      # 1

Anthropic Claude

import anthropic
from tokenfence import guard

client = guard(
    anthropic.Anthropic(),
    budget='$1.00',
    fallback='claude-3-haiku-20240307',
    on_limit='stop',
)

# Use exactly like a normal Anthropic client
response = client.messages.create(
    model='claude-3-5-sonnet-20241022',
    max_tokens=1024,
    messages=[{'role': 'user', 'content': 'Hello'}],
)

# Check spend
print(client.tokenfence.spent)      # 0.00105
print(client.tokenfence.remaining)  # 0.99895

Async Support

For async applications (the standard in production agent pipelines), use async_guard:

import openai
from tokenfence import async_guard

client = async_guard(
    openai.AsyncOpenAI(),
    budget='$0.50',
    fallback='gpt-4o-mini',
    on_limit='stop',
)

# Use exactly like a normal async OpenAI client
response = await client.chat.completions.create(
    model='gpt-4o',
    messages=[{'role': 'user', 'content': 'Hello'}],
)

print(client.tokenfence.spent)

Works with anthropic.AsyncAnthropic too:

import anthropic
from tokenfence import async_guard

client = async_guard(
    anthropic.AsyncAnthropic(),
    budget='$1.00',
    fallback='claude-3-haiku-20240307',
    on_limit='raise',
)

response = await client.messages.create(
    model='claude-3-5-sonnet-20241022',
    max_tokens=1024,
    messages=[{'role': 'user', 'content': 'Hello'}],
)

How It Works

1. Track — every chat.completions.create() call records token usage and calculates cost.
2. Downgrade — when cumulative spend hits the threshold (default 80% of budget), the model is transparently swapped to your fallback.
3. Kill switch — when the budget is fully consumed:
   • on_limit='stop' — returns a synthetic response explaining the budget was exceeded.
   • on_limit='warn' — logs a warning but allows the call through.
   • on_limit='raise' — raises BudgetExceeded.

API

guard(client, *, budget, fallback=None, on_limit='stop', threshold=0.8)

async_guard(client, *, budget, fallback=None, on_limit='stop', threshold=0.8)

Same parameters as guard(), but for async clients (openai.AsyncOpenAI, anthropic.AsyncAnthropic).

client.tokenfence

Limits on Free Tier

The free Hobby tier includes 50K tracked requests/month. For production workloads:

→ Upgrade to Pro at tokenfence.dev — 7-day free trial, no credit card required to start.

License

MIT