Budgets and enforcement

Budget checks run before the provider call, so a blocking budget prevents spend rather than reporting it. Enforcement is on by default.

capsera.init(api_key=os.environ["CAPSERA_API_KEY"])
# enable_budget_enforcement=True is the default

Latency cost

Enforcement performs one round trip to the backend before each provider call. If that is unacceptable and you do not need hard blocking, disable it:

capsera.init(api_key=..., enable_budget_enforcement=False)

When no budget matches a call, the result is "allowed" and the call proceeds, so the cost is the round trip rather than a decision.

Scope

Budgets are defined in the dashboard and matched by scope:

A budget can only act on a boundary the events carry, so attribution has to be correct first. Spend attributed to unknown cannot be governed by an agent budget.

Actions

block raises BudgetExceededError before the provider call. No tokens are spent, because the call never leaves your process.

Margin downgrade rewrites the model to a cheaper one as the budget approaches its limit, so work continues more cheaply. Task types in critical_task_types are exempt.

throttle is not enforced at runtime. The decision is recorded and visible, but the call is not delayed. Use a gateway rate limit or a semaphore in your own code if you need calls slowed. block and margin downgrade both work as documented.

Handling a block

BudgetExceededError is the only exception the SDK raises deliberately. Everything else fails open.

from capsera import BudgetExceededError

try:
    answer = expensive_agent(question)
except BudgetExceededError as exc:
    logger.warning("budget stopped the call: %s", exc)
    answer = cached_or_degraded_answer(question)

Decide what a blocked call means for your product. Three reasonable responses:

Degrade, by serving a cached answer, a template, or a smaller model called directly.

Queue, by deferring the work until the budget period rolls over.

Fail, which for internal batch work is often correct.

Do not catch it and retry immediately. The budget will still be exceeded.

Failing open

If the pre-call check does not complete within budget_check_timeout (1 second by default), the call is allowed.

Failing closed would mean a network problem between your service and Capsera could halt production traffic. Brief overspending is recoverable; an outage caused by the cost tool is not.

Enforcement is therefore best-effort under degraded network conditions. If a hard cap is a compliance requirement rather than a cost preference, enforce it at a gateway in the request path.

Staleness window

The check reads budget state computed from delivered events. Events are delivered in batches every 500 ms, so a burst of concurrent calls can each pass a check taken before any of them was recorded.

A budget can therefore be exceeded by roughly one batch interval's worth of in-flight spend. Set a budget slightly below a figure you cannot exceed.

Embeddings are not enforced

Embedding calls bypass budget enforcement, so a blocking budget will not stop an indexing run. Guard those in your own code.

Verifying enforcement

Set a small budget on a test agent and confirm the exception:

@capsera.agent("budget-test")
def probe():
    return client.messages.create(...)

try:
    probe()
except BudgetExceededError:
    print("enforcement is live")

This is worth doing after any change to enable_budget_enforcement, so a setting changed during a latency investigation is not left disabled.