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

# KPI-Weighted Routing

> Inject business priorities as quality, cost, latency, and energy weights into every model routing decision.

The harness scores each model decision against configurable KPI weights. This lets teams encode business priorities into agent behavior without changing agent code.

## KPI Dimensions

| Dimension | Score Source                  | Range   | What it means                    |
| --------- | ----------------------------- | ------- | -------------------------------- |
| `quality` | Model quality priors          | 0.0-1.0 | Higher = better output quality   |
| `cost`    | Inverse of model cost         | 0.0-1.0 | Higher = cheaper model           |
| `latency` | Model latency priors          | 0.0-1.0 | Higher = faster response         |
| `energy`  | Inverse of energy coefficient | 0.0-1.0 | Higher = lower compute intensity |

## Configuration

```python theme={null}
import cascadeflow

cascadeflow.init(mode="enforce")

with cascadeflow.run(
    kpi_weights={"quality": 0.6, "cost": 0.3, "latency": 0.1},
    kpi_targets={"quality": 0.9}
) as session:
    result = await agent.run("Analyze this legal document")
```

### Weights

Weights are relative — they don't need to sum to 1.0 (they are normalized internally). They control the relative importance of each dimension in the composite score.

```python theme={null}
# Quality-first (premium workload)
kpi_weights = {"quality": 0.8, "cost": 0.1, "latency": 0.1}

# Cost-first (high-volume batch)
kpi_weights = {"quality": 0.2, "cost": 0.7, "latency": 0.1}

# Balanced
kpi_weights = {"quality": 0.4, "cost": 0.3, "latency": 0.2, "energy": 0.1}
```

### Targets

Targets set minimum acceptable values. If a model's score for a dimension falls below the target, it is penalized in the composite score.

```python theme={null}
kpi_targets = {
    "quality": 0.9,   # Require high quality
    "latency": 0.7,   # Require reasonable speed
}
```

## Scoring Formula

The composite score for a model is:

```
score = quality_prior * w_quality + cost_utility * w_cost + latency_prior * w_latency + energy_utility * w_energy
```

Where `w_*` are the normalized weights and utility values are computed from model priors.

## Quality Priors

Built-in quality priors for common models (OpenAI):

| Model         | Quality | Latency |
| ------------- | ------- | ------- |
| o1            | 0.95    | 0.40    |
| gpt-4o        | 0.90    | 0.72    |
| gpt-4-turbo   | 0.88    | 0.66    |
| gpt-4         | 0.87    | 0.52    |
| gpt-5-mini    | 0.86    | 0.84    |
| o1-mini       | 0.82    | 0.60    |
| o3-mini       | 0.80    | 0.78    |
| gpt-4o-mini   | 0.75    | 0.93    |
| gpt-3.5-turbo | 0.65    | 1.00    |

## Per-Agent KPI Weights

Different agents can have different priorities:

```python theme={null}
@cascadeflow.agent(
    budget=0.50,
    kpi_weights={"quality": 0.8, "cost": 0.2}
)
async def quality_agent(query: str):
    return await llm.complete(query)

@cascadeflow.agent(
    budget=0.10,
    kpi_weights={"cost": 0.8, "quality": 0.2}
)
async def budget_agent(query: str):
    return await llm.complete(query)
```

<Tip>
  **Example walkthrough:** [KPI-Weighted Routing](/examples/kpi-weighted-routing) | **GitHub:** [examples/cost\_tracking.py](https://github.com/lemony-ai/cascadeflow/blob/main/examples/cost_tracking.py) | [examples/semantic\_quality\_domain\_detection.py](https://github.com/lemony-ai/cascadeflow/blob/main/examples/semantic_quality_domain_detection.py)
</Tip>