Budget Enforcement

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:

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}")

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}%`);

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:

@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:

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:

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).

Examples on GitHub: enforcement/basic_enforcement.py | user_budget_tracking.py | cost_tracking.py

Overview

Getting Started

Core Concepts

Harness

Integrations

Guides

Resources

Per-Run Budget

Per-Agent Budget

Budget Pressure Routing

Cost Calculation

Combining with Tool Call Caps

​Per-Run Budget

​Per-Agent Budget

​Budget Pressure Routing

​Cost Calculation

​Combining with Tool Call Caps

Per-Run Budget

Per-Agent Budget

Budget Pressure Routing

Cost Calculation

Combining with Tool Call Caps