Query → Model Call → Tool Call → Model Call → Tool Call → Model Call → Response
  ↑         ↑            ↑           ↑            ↑           ↑
  └── cascadeflow evaluates every decision boundary ──────────┘

import cascadeflow
from cascadeflow.tools import ToolConfig, ToolExecutor

tools = [
    ToolConfig(
        name="search",
        description="Search the web",
        parameters={"query": {"type": "string"}},
        handler=lambda query: f"Results for: {query}",
    ),
    ToolConfig(
        name="calculator",
        description="Evaluate math expressions",
        parameters={"expression": {"type": "string"}},
        handler=lambda expression: str(eval(expression)),
    ),
]

cascadeflow.init(mode="enforce")

with cascadeflow.run(budget=1.00, max_tool_calls=5) as session:
    result = await agent.run(
        "Research this topic and calculate the statistics",
        tools=tools,
        tool_executor=ToolExecutor(tools=tools),
        max_steps=10,
    )

    summary = session.summary()
    print(f"Tool calls used: {summary['tool_calls']}/5")
    print(f"Budget used: ${summary['cost_total']:.4f}/$1.00")

with cascadeflow.run(budget=0.50) as session:
    result = await agent.run("Deep multi-step analysis")

    for record in session.trace():
        print(
            f"Step {record['step']}: "
            f"{record['action']} | "
            f"model={record['model']} | "
            f"spent=${record['cost_total']:.4f} | "
            f"budget={record['budget_state']}"
        )
    # Step 1: allow        | model=gpt-4o-mini | spent=$0.0012 | budget=ok
    # Step 2: allow        | model=gpt-4o-mini | spent=$0.0031 | budget=ok
    # Step 3: switch_model | model=gpt-4o      | spent=$0.0245 | budget=ok
    # Step 4: allow        | model=gpt-4o-mini | spent=$0.0258 | budget=ok
    # ...
    # Step 9: stop         | model=gpt-4o      | spent=$0.5012 | budget=exceeded

researcher = CascadeAgent(models=[
    ModelConfig(name="gpt-4o-mini", provider="openai", cost=0.000375),
    ModelConfig(name="gpt-4o", provider="openai", cost=0.00625),
])

async def research_handler(query: str) -> str:
    """Sub-agent: researches a topic."""
    result = await researcher.run(query)
    return result.content

tools = [
    ToolConfig(
        name="research",
        description="Delegate research to a specialist agent",
        parameters={"query": {"type": "string"}},
        handler=research_handler,
    ),
]

# One budget governs the entire agent tree
with cascadeflow.run(budget=2.00) as session:
    result = await main_agent.run(
        "Analyze and research this topic",
        tools=tools,
    )
    # session.summary() includes costs from main_agent AND researcher
    print(f"Total cost across all agents: ${session.summary()['cost_total']:.4f}")

# Quality-driven: cheaper model handles simple steps, better model handles hard ones
with cascadeflow.run(
    kpi_weights={"quality": 0.7, "cost": 0.3},
    kpi_targets={"quality": 0.85},
) as session:
    result = await agent.run("Complex multi-step reasoning task")

    # Trace shows model decisions per step
    for record in session.trace():
        if record['action'] == 'switch_model':
            print(f"Step {record['step']}: Switched to {record['model']} — {record['reason']}")

import cascadeflow
from cascadeflow import CascadeAgent, ModelConfig
from cascadeflow.tools import ToolConfig, ToolExecutor

agent = CascadeAgent(models=[
    ModelConfig(name="gpt-4o-mini", provider="openai", cost=0.000375),
    ModelConfig(name="gpt-4o", provider="openai", cost=0.00625),
])

tools = [
    ToolConfig(name="search", description="Web search", parameters={"q": {"type": "string"}},
              handler=lambda q: f"Results for {q}"),
    ToolConfig(name="calc", description="Calculator", parameters={"expr": {"type": "string"}},
              handler=lambda expr: str(eval(expr))),
]

cascadeflow.init(mode="enforce")

with cascadeflow.run(
    budget=1.00,
    max_tool_calls=8,
    compliance="gdpr",
    kpi_weights={"quality": 0.6, "cost": 0.3, "latency": 0.1},
) as session:
    result = await agent.run(
        "Research EU market data and calculate growth rates",
        tools=tools,
        tool_executor=ToolExecutor(tools=tools),
        max_steps=15,
    )

    summary = session.summary()
    print(f"Cost: ${summary['cost_total']:.4f} / $1.00")
    print(f"Steps: {summary['steps']}")
    print(f"Tool calls: {summary['tool_calls']} / 8")
    print(f"Budget remaining: ${summary['budget_remaining']:.4f}")