Installation
pip install aicostguard
Requires Python 3.9+.
Configuration
from aicostguard import CostGuard
guard = CostGuard(
api_key="cg_your_key_here", # Required
project_id="my-project", # Optional
environment="production", # Optional
base_url="https://api.aicostguard.com", # Optional
flush_interval=5.0, # Optional (seconds)
debug=False, # Optional
)
Wrapping Providers
OpenAI
from openai import OpenAI
client = guard.wrap(OpenAI())
response = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "Hello!"}]
)
Anthropic
from anthropic import Anthropic
client = guard.wrap(Anthropic())
message = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello!"}]
)
Async Support
from openai import AsyncOpenAI
async_client = guard.wrap(AsyncOpenAI())
response = await async_client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "Hello!"}]
)
Decorator API
Track any function's LLM calls with the decorator:
@guard.track(feature="summarization", user_id="user_123")
def summarize(text: str) -> str:
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": f"Summarize: {text}"}]
)
return response.choices[0].message.content
Custom Metadata
response = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "Hello"}],
extra_headers={
"X-CostGuard-User": "user_123",
"X-CostGuard-Feature": "customer-support",
}
)
Budget Alerts
guard.budgets.create(
name="Production Daily Cap",
amount=100,
period="daily",
alert_thresholds=[50, 80, 100],
auto_stop=True,
notify_channels=["slack", "email"],
)
Cost Querying
costs = guard.costs.query(
from_date="2026-03-01",
to_date="2026-03-15",
group_by=["model", "feature"],
)
for entry in costs:
print(f"{entry.model}: ${entry.total_cost:.2f} ({entry.requests} requests)")
Context Manager
with guard.session(feature="batch-processing") as session:
for doc in documents:
response = client.chat.completions.create(...)
print(f"Session cost: ${session.total_cost:.4f}")