feat(evaluators): add built-in budget evaluator for per-agent cost tracking

[amabito]

Summary

Built-in budget evaluator for per-agent cumulative cost tracking.

Motivation

Retries and recursive tool chains pile up fast -- a 3-layer retry loop is 64 API calls from one user request. Current evaluators are stateless, so there's no way to express "deny after $X total spend" without maintaining a separate counter service outside the control plane.

Current behavior

Controls evaluate step content (regex, list, JSON, SQL) but can't track cumulative state across evaluations. Cost enforcement requires a custom evaluator with external state management.

Expected behavior

A built-in budget evaluator that:

1. Tracks cumulative cost per agent (in-memory, or via PostgreSQL for persistence)
2. Config: max_cost_usd, cost_per_1k_input_tokens, cost_per_1k_output_tokens
3. On post-stage evaluation, reads token counts from step.output or step.context, accumulates
4. Returns matched=True when ceiling is hit
5. Pairs with existing actions -- deny for hard stop, steer with steering_context: {fallback_model: "..."} for degradation

Proposed solution

Should work as a regular evaluator. confidence could just be spent / limit (0-1 utilization ratio).

The stateful part is new -- current evaluators are stateless -- but the SQL evaluator already caches query analysis across calls, so there's precedent for evaluator-level state.

Additional context

LMK if a PR for this makes sense.

[lan17]

Closing this one since it overlaps with #129

[amabito]

This issue is about x402/wallet spend. #130 is about LLM API cost from token usage -- retries, tool chains, etc. Different data model, different evaluator. Closing #130 as a dup doesn't seem right. Happy to pick up the LLM cost tracking side separately.

[lan17]

@amabito That's not the idea i got from your original description. Your original description seems to describe a spend limit based on token usage by agent, not money spent by agent programmatically.

If we are going to be controlling the limits for agent to spend money via its own wallet that would indeed be a different use case and require a different evaluator.

[amabito]

@lan17 To clarify – this is about token-usage cost tracking, not agents spending money through wallets. The config in the description (cost_per_1k_input_tokens etc.) is all LLM API cost. If wallet-based budget control is something worth exploring separately, happy to discuss.

[lan17]

@amabito Agreed, will re-open the issue

[lan17]

@amabito The same comment should still apply here as well: #129 (comment)

Some thoughts on how it should be implemented:

1. This will likely require a new table/database. Evaluator should be decoupled from the data source so different databases or stores could be used for tracking.
2. We probably should not add new tables to core agent control, hence decoupling idea above.
3. Ideally the rules for limits could take into account more context, such as extra context/metadata we pass into evaluate. This way we could have different limits for different channels an agent might be in.
4. This new evaluator should also be executable in Python sdk, which should be easy since we share evaluation engine between server and Python sdk.

[amabito]

To keep scope clear: #130 is about LLM API cost derived from token usage in step data -- not wallet balances or payment transactions. Different accounting source, different evaluator, but the store abstraction could be shared later.

Here's a sketch against each of your four points.

1. Store abstraction

Budget evaluation stays storage-agnostic. Cumulative state lives behind a store interface:

@dataclass(frozen=True)
class BudgetSnapshot:
    spent_usd: float
    limit_usd: float
    utilization: float  # spent / limit, clamped to [0.0, 1.0]
    exceeded: bool

class BudgetStore(Protocol):
    def record_and_check(
        self,
        agent_id: str,
        input_tokens: int,
        output_tokens: int,
        cost_usd: float,
        metadata: dict,
    ) -> BudgetSnapshot: ...

Single atomic call -- records usage and returns current totals in one shot, no read-then-write race.

2. No new core tables

Two implementations, only one in core:

• InMemoryBudgetStore -- dict-based, zero dependencies, default. Resets on restart. Fine for SDK and short-lived runs.
• PostgresBudgetStore -- separate package, lazy import. Own table, outside agent-control's migrations.

from agent_control.evaluators.budget import BudgetEvaluator

# default
evaluator = BudgetEvaluator(limits={"default": 10.0})

# opt-in postgres
from agent_control_budget_pg import PostgresBudgetStore
evaluator = BudgetEvaluator(store=PostgresBudgetStore(dsn), limits={"default": 10.0})

3. Channel-aware limits via metadata

The evaluator reads channel from the metadata dict passed into evaluate(). Per-channel overrides with fallback:

limits = {
    "default": 10.0,
    "slack-bot": 5.0,
    "internal-api": 50.0,
}

Exact match → default → deny.

4. Python SDK

InMemoryBudgetStore has no external deps. Runs wherever the evaluation engine runs. Postgres is opt-in only.

Return semantics

Initial sketch in the issue description suggested confidence = spent / limit, but after looking at how other built-in evaluators use confidence, keeping it at 1.0 for deterministic results and putting utilization in metadata is more consistent.

matched=True when ceiling is hit, pairs with existing actions (deny, steer to fallback model). BudgetSnapshot fields go into result metadata for observability.

If this direction is aligned, happy to draft a small PR with the in-memory implementation and tests.

[lan17]

@amabito how are the budgets defined per time window? Shouldn't we be able to say "limit is $100 per week per Agent X in Channel Y"? Not seeing it reflected in above design.

Also, how could we also create limits per user per channel? i.e. only spend $1 max per user in slack channel per day, or something along those lines. That could be really useful so that one user could not exhaust entire budget.

Also wonder if the limits should be in # tokens/ model, vs USD cost? Counting tokens should be a lot more precise than trying to estimate USD cost.

[amabito]

All three are gaps. Here's the fix:

1. Time windows

Right, the proposal assumed a single rolling counter with no window concept. Fix: the store aggregates by a composite key (scope_key, period_key). The evaluator derives period_key from config -- "2026-W12" for weekly, "2026-03-20" for daily, "2026-03" for monthly. The store stays dumb; it just groups by whatever key string it receives.

2. Per-user per-channel

Generalizing the aggregation dimension covers this. The evaluator builds a scope_key from configurable metadata fields -- e.g. "channel=slack-bot|user_id=alice" -- and the store groups by that string without knowing the semantics. Limits config supports scoped overrides:

limits = [
    {"scope": {"channel": "slack-bot"}, "window": "daily", "limit_usd": 1.0, "group_by": "user_id"},
    {"scope": {"channel": "internal-api"}, "window": "weekly", "limit_usd": 50.0},
    {"scope": {}, "window": "monthly", "limit_usd": 500.0},  # global fallback
]

group_by: "user_id" means each unique user gets their own $1/day budget in that channel. All matching rules are checked -- a request can hit both a per-user daily cap and the global monthly cap.

3. Tokens vs USD

Agreed, token counts are more precise. The store tracks both independently. Config can specify limit_tokens and/or limit_usd -- both checked, either can trigger denial. Token-only limits work without any pricing config and are the better default for single-model setups. USD adds flexibility for mixed-model budgets via an optional pricing table.

Updated protocol:

class BudgetStore(Protocol):
    def record(
        self,
        scope_key: str,
        period_key: str,
        input_tokens: int,
        output_tokens: int,
        cost_usd: float,
    ) -> BudgetSnapshot: ...

@dataclass(frozen=True)
class BudgetSnapshot:
    spent_usd: float
    spent_tokens: int

The store records spend and returns raw counters. Limit comparison is the evaluator's job -- the store never sees limit config. This keeps the store genuinely dumb and the evaluator owns all policy logic.

I can put together a PR with these changes if this direction looks right.

[lan17]

Looks good overall to me! Would love to see your PR and review it whenever you have it.

Let's just make sure to not update any PG tables.

Btw, what do you think of leveraging pyrate-limiter here? Might be a good fit and i believe it can be backed by many different dbs: https://pypi.org/project/pyrate-limiter/

[amabito]

No PG changes -- initial PR is in-memory only. Postgres store makes sense as a separate package later.

Looked at pyrate-limiter. It counts discrete events (N requests per window), but what we need here is accumulating fractional USD and token counts per window. $0.037 per call doesn't fit a rate bucket. The BudgetStore protocol already handles backend pluggability for that reason.

I'll get the PR up.

[lan17]

No PG changes -- initial PR is in-memory only. Postgres store makes sense as a separate package later.

Looked at pyrate-limiter. It counts discrete events (N requests per window), but what we need here is accumulating fractional USD and token counts per window. $0.037 per call doesn't fit a rate bucket. The BudgetStore protocol already handles backend pluggability for that reason.

I'll get the PR up.

We could just change usd to int instead of float, no? i.e. USD in cents as an int.