Skip to main content
The context object yielded by cascadeflow.run(). Provides access to run metrics, decision traces, and budget state.

​
Methods

​
summary()

Returns aggregate metrics for the run. 
summary = session.summary()
Returns a dict with:
KeyTypeDescription
cost_totalfloatCumulative cost in USD
stepsintNumber of LLM calls
tool_callsintNumber of tool/function calls
latency_total_msfloatTotal wall-clock latency in ms
energy_usedfloatTotal energy units consumed
budget_remainingfloat | NoneUSD remaining (None if no budget set)

​
trace()

Returns the list of decision records for the run. 
records = session.trace()
Each record is a dict with:
KeyTypeDescription
actionstr"allow", "switch_model", "deny_tool", or "stop"
reasonstrHuman-readable explanation
modelstrModel name
stepintStep number (1-indexed)
cost_totalfloatCumulative cost at this step
budget_statestr"ok", "warning", or "exceeded"
appliedboolWhether the action was enforced

​
Usage

import cascadeflow

cascadeflow.init(mode="enforce")

with cascadeflow.run(budget=0.50) as session:
    result = await agent.run("Analyze this dataset")

    # Aggregate metrics
    summary = session.summary()
    print(f"Cost: ${summary['cost_total']:.4f}")
    print(f"Steps: {summary['steps']}")
    print(f"Budget remaining: ${summary['budget_remaining']:.4f}")

    # Decision trace
    for record in session.trace():
        print(f"Step {record['step']}: {record['action']} — {record['reason']}")

​
Import

from cascadeflow import HarnessRunContext