Budget Management

from tork_governance import TorkClient

client = TorkClient()

# Create a budget for an agent
budget = client.budgets.create(
    name="Customer Support Agent Budget",
    scope="agent",
    scope_id="agent-123",
    limit_amount=500.00,
    limit_currency="USD",
    period="monthly",
    alert_thresholds=[50, 80, 95],
    action_on_exceed="block"  # or "warn", "alert"
)

print(f"Budget created: {budget.id}")

# Get budget status
status = client.budgets.get_status(budget_id="budget-123")

print(f"Limit: ${status.limit_amount}")
print(f"Used: ${status.used_amount}")
print(f"Remaining: ${status.remaining_amount}")
print(f"Utilization: {status.utilization_percent}%")
print(f"Period ends: {status.period_end}")

# Check if action would exceed budget
check = client.budgets.check(
    agent_id="agent-123",
    estimated_cost=25.00
)

if check.would_exceed:
    print(f"Action would exceed budget by ${check.overage}")

{
  "event": "budget.threshold_reached",
  "budget_id": "budget-123",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "threshold_percent": 80,
    "used_amount": 400.00,
    "limit_amount": 500.00,
    "remaining_amount": 100.00,
    "period": "monthly",
    "period_end": "2024-01-31T23:59:59Z"
  }
}

# Get cost breakdown
breakdown = client.budgets.get_breakdown(
    budget_id="budget-123",
    group_by="model"  # or "agent", "action_type", "day"
)

for item in breakdown.items:
    print(f"{item.group}: ${item.amount} ({item.percent}%)")
# Output:
# gpt-4: $250.00 (62.5%)
# gpt-3.5-turbo: $120.00 (30%)
# claude-3: $30.00 (7.5%)