Cost Controls
New in v0.9Budget governance and spend tracking for AI operations. Set limits, track spending, and prevent cost overruns.
Overview
Cost Controls provides comprehensive budget management for AI operations. Track spending across providers, set limits at multiple levels, and receive alerts before you exceed budgets.
Budgets
Daily, weekly, monthly, or total spending limits
Transaction Logging
Track every API call with associated cost
Hard Limits
Optionally block requests when budget exceeded
Reports
Breakdown by provider, model, agent, and time
Create a Budget
Create budgets at different levels - per agent, per team, or organization-wide:
python
from tork import TorkClient, CostControls
client = TorkClient(api_key="your_key")
costs = CostControls(client)
# Create daily budget for a specific agent
agent_budget = costs.create_budget(
name="Agent-1 Daily Budget",
budget_type="daily", # 'daily', 'weekly', 'monthly', 'total'
amount=100.00,
currency="USD",
agent_id="agent-1",
hard_limit=True, # Block when exceeded
alert_threshold=0.8 # Alert at 80%
)
print(f"Created budget: {agent_budget['id']}")
# Create organization-wide monthly budget
org_budget = costs.create_budget(
name="Organization Monthly",
budget_type="monthly",
amount=5000.00,
currency="USD",
hard_limit=False, # Warn only, don't block
alert_threshold=0.7
)Check Before Spending
Check if a proposed spend is within budget before making API calls:
python
# Check if proposed spend is allowed
check = costs.check_budget(
agent_id="agent-1",
proposed_cost=0.05, # Estimated cost of the operation
provider="openai",
model="gpt-4"
)
if check['allowed']:
# Make the API call
response = call_llm_api(messages)
# Record the actual transaction
costs.record_transaction(
agent_id="agent-1",
transaction_type="llm_call",
total_cost=response.usage.total_cost,
provider="openai",
model="gpt-4",
input_tokens=response.usage.prompt_tokens,
output_tokens=response.usage.completion_tokens,
metadata={
"request_id": response.id,
"latency_ms": response.latency
}
)
else:
print(f"Budget exceeded!")
for alert in check['alerts']:
print(f" {alert['budgetName']}: {alert['percentUsed']}% used")
print(f" Remaining: ${alert['remaining']:.2f}")Get Spend Summary
Get a summary of spending for an agent or the entire organization:
python
# Get spending summary for an agent
summary = costs.get_summary(
agent_id="agent-1",
period="monthly" # 'daily', 'weekly', 'monthly', 'all_time'
)
print(f"Total Spend: ${summary['totalCost']:.2f}")
print(f"Transactions: {summary['transactionCount']}")
print(f"Average per transaction: ${summary['averageCost']:.4f}")
print("\nBy Provider:")
for provider in summary['byProvider']:
print(f" {provider['provider']}: ${provider['cost']:.2f} ({provider['percentage']}%)")
print("\nBy Model:")
for model in summary['byModel']:
print(f" {model['model']}: ${model['cost']:.2f}")
print("\nBy Day:")
for day in summary['byDay']:
print(f" {day['date']}: ${day['cost']:.2f}")Alert Thresholds
Alerts are triggered at configurable thresholds:
| Alert Type | Severity | Trigger |
|---|---|---|
| threshold_warning | high | 80% of budget used (configurable) |
| budget_exceeded | critical | 100% of budget used |
| anomaly_detected | medium | Unusual spending pattern detected |
| rate_spike | high | Sudden increase in spend rate |
Webhook Notifications
Configure webhooks to receive real-time notifications when budget alerts are triggered. See the Webhooks documentation.
Budget Types
| Type | Reset | Use Case |
|---|---|---|
| daily | Midnight UTC | Prevent runaway costs within a single day |
| weekly | Sunday midnight UTC | Smooth out daily variations |
| monthly | 1st of month UTC | Align with billing cycles |
| total | Never | Lifetime cap for projects or experiments |
MCP Tools
| Tool | Description |
|---|---|
tork_cost_check_budget | Check if a spend is within budget |
tork_cost_record_transaction | Record a cost transaction |
tork_cost_get_summary | Get spending summary |
tork_cost_list_budgets | List all budgets |
tork_cost_get_alerts | Get active budget alerts |