Per-user budget caps

StandardBudget tracks tokens / cost / wall clock both globally and per user_id. The global caps catch runaway aggregate usage; the per-user caps stop one tenant from exhausting another’s quota.


from datetime import timedelta
from loomflow import Agent
from loomflow.governance.budget import BudgetConfig, StandardBudget
 
agent = Agent(
    "...",
    budget=StandardBudget(BudgetConfig(
        # Global: applies to all users combined.
        max_tokens=10_000_000,
        max_cost_usd=100.0,
        max_wall_clock=timedelta(hours=1),
        # Per-user: applies to each user_id's bucket independently.
        per_user_max_tokens=100_000,
        per_user_max_cost_usd=2.0,
        per_user_max_wall_clock=timedelta(minutes=10),
        soft_warning_at=0.8,  # warn at 80% of either cap
    )),
)

A run is blocked when either its user’s cap or the global cap is exceeded. Whichever fires first. result.interrupted = True and result.interruption_reason = "budget:per_user_max_tokens" (or the matching global field) on a blocked run.

Inspecting usage

Inspect a single user’s running totals at any time:


usage = agent._budget.usage_for("alice")
# {"tokens_in": 1240, "tokens_out": 880, "tokens_total": 2120,
#  "cost_usd": 0.0042}

Both the agent loop and direct callers pass user_id through to the budget automatically. You don’t need to thread it manually.