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

# HarnessRunContext

> Run context object yielded by cascadeflow.run() with summary(), trace(), and budget tracking methods.

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.

```python theme={null}
summary = session.summary()
```

Returns a dict with:

| Key | Type | Description |
| - | - | - |
| `cost_total` | `float` | Cumulative cost in USD |
| `steps` | `int` | Number of LLM calls |
| `tool_calls` | `int` | Number of tool/function calls |
| `latency_total_ms` | `float` | Total wall-clock latency in ms |
| `energy_used` | `float` | Total energy units consumed |
| `budget_remaining` | `float \| None` | USD remaining (None if no budget set) |

### trace()

Returns the list of decision records for the run.

```python theme={null}
records = session.trace()
```

Each record is a dict with:

| Key | Type | Description |
| - | - | - |
| `action` | `str` | `"allow"`, `"switch_model"`, `"deny_tool"`, or `"stop"` |
| `reason` | `str` | Human-readable explanation |
| `model` | `str` | Model name |
| `step` | `int` | Step number (1-indexed) |
| `cost_total` | `float` | Cumulative cost at this step |
| `budget_state` | `str` | `"ok"`, `"warning"`, or `"exceeded"` |
| `applied` | `bool` | Whether the action was enforced |

## Usage

```python theme={null}
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

```python theme={null}
from cascadeflow import HarnessRunContext
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.