> ## Documentation Index
> Fetch the complete documentation index at: https://cascadeflow-docs-readme-hermes-callout.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Budget Enforcement

> Configure budget enforcement with per-run caps and automatic stop actions when budget is exceeded.

The harness tracks cumulative cost across all LLM calls in a run and enforces budget caps in `enforce` mode.

## Per-Run Budget

Set a budget cap on a scoped run:

<CodeGroup>
  ```python Python theme={null}
  import cascadeflow

  cascadeflow.init(mode="enforce")

  with cascadeflow.run(budget=0.50) as session:
      # Agent executes multiple LLM calls
      result = await agent.run("Research and summarize this topic")

      summary = session.summary()
      print(f"Total cost: ${summary['cost_total']:.4f}")
      print(f"Budget remaining: ${summary['budget_remaining']:.4f}")
  ```

  ```typescript TypeScript theme={null}
  import { CascadeAgent } from '@cascadeflow/core';

  const agent = new CascadeAgent({
    models: [
      { name: 'gpt-4o-mini', provider: 'openai', cost: 0.000375 },
      { name: 'gpt-4o', provider: 'openai', cost: 0.00625 },
    ],
    quality: { threshold: 0.8 },
  });

  const result = await agent.run('Research and summarize this topic');
  console.log(`Cost: $${result.totalCost}, Saved: ${result.savingsPercentage}%`);
  ```
</CodeGroup>

When cumulative cost exceeds the budget:

* In `observe` mode: the trace records `action: "stop"` with `applied: false`
* In `enforce` mode: the harness stops execution with `action: "stop"` and `applied: true`

## Per-Agent Budget

Attach budget metadata to agent functions:

```python theme={null}
@cascadeflow.agent(budget=0.20)
async def cheap_agent(query: str):
    return await llm.complete(query)

@cascadeflow.agent(budget=2.00)
async def premium_agent(query: str):
    return await llm.complete(query)
```

## Budget Pressure Routing

When budget is partially consumed, the harness can route to cheaper models. This happens automatically when KPI weights include a cost dimension:

```python theme={null}
cascadeflow.init(mode="enforce")

with cascadeflow.run(
    budget=1.00,
    kpi_weights={"quality": 0.5, "cost": 0.5}
) as session:
    # Early calls may use gpt-4o (high quality)
    # As budget pressure increases, routing shifts toward gpt-4o-mini (lower cost)
    for query in queries:
        result = await agent.run(query)
```

## Cost Calculation

Cost is estimated from the built-in pricing table:

```
cost = (input_tokens / 1_000_000) * input_price + (output_tokens / 1_000_000) * output_price
```

The pricing table covers 18 models across OpenAI, Anthropic, and Google. Unknown models are resolved via fuzzy matching.

## Combining with Tool Call Caps

Budget and tool call caps work together:

```python theme={null}
with cascadeflow.run(budget=0.50, max_tool_calls=10) as session:
    # Stops when either limit is hit
    result = await agent.run("Analyze this data")
```

The harness checks all constraints at every step. The first constraint that is violated triggers the corresponding action (`stop` for budget, `deny_tool` for tool calls).

<Tip>
  **Examples on GitHub:** [enforcement/basic\_enforcement.py](https://github.com/lemony-ai/cascadeflow/blob/main/examples/enforcement/basic_enforcement.py) | [user\_budget\_tracking.py](https://github.com/lemony-ai/cascadeflow/blob/main/examples/user_budget_tracking.py) | [cost\_tracking.py](https://github.com/lemony-ai/cascadeflow/blob/main/examples/cost_tracking.py)
</Tip>