Predictive Budgets

Warn, then downgrade, then block as a scope approaches its cap

Overview

A fixed-window budget enforces a hard cliff: requests pass until the cap, then block at 100%. Soft-landing degrades gracefully as a scope approaches its limit, so spend tapers instead of stopping dead. It is an opt-in addition to the existing budget block; without it the hard-block behavior is unchanged.

Configuration

budget:
  limits:
    - scope: workspace
      max_cost_usd: 10.0
      period: daily
  on_exceed: block
  soft_landing:
    warn_at: 0.8               # past 80%, warn
    downgrade_at: 0.95         # past 95%, downgrade to a cheaper model
    downgrade_to: gpt-4o-mini  # optional; else per-limit or cheapest

Behavior

The check runs after the hard pre-flight clears, on the tightest active window (the larger of the token and cost fractions). Below warn_at nothing changes. Between warn_at and downgrade_at the request is allowed and a warning is logged. Between downgrade_at and the cap the model is rewritten to the soft-landing target. At or above the cap the hard on_exceed action owns the decision, so the two never fight. A soft-landing downgrade is recorded on the usage record and the verifiable ledger, and the live fraction is published to the policy plane as ai.budget.fraction.