Skip to content

Switchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.

Rust

refactor: rename cascade router to stage-router (#20)

sabhatinasa8024bd0d848
diff --git a/.agents/skills/switchyard-coding-agent-launchers/SKILL.md b/.agents/skills/switchyard-coding-agent-launchers/SKILL.md
index 0e346a105..05cfa99c0 100644
--- a/.agents/skills/switchyard-coding-agent-launchers/SKILL.md
+++ b/.agents/skills/switchyard-coding-agent-launchers/SKILL.md
@@ -85,7 +85,7 @@ Route YAML and launchers share this model-dispatch path:
- `type: passthrough` registers the YAML key and discovered direct models.
- `type: random_routing` registers the YAML key as the routing profile plus
direct strong/weak passthrough entries.
-- `type: deterministic` and `type: cascade` register the route key plus direct
+- `type: deterministic` and `type: stage_router` register the route key plus direct
strong/weak passthrough entries.
- `type: plan_execute` registers the route key plus the executor as a direct
passthrough; the planner is internal routing logic.
diff --git a/.agents/skills/switchyard-lib-core/SKILL.md b/.agents/skills/switchyard-lib-core/SKILL.md
index 44fa602c1..7a9933a23 100644
--- a/.agents/skills/switchyard-lib-core/SKILL.md
+++ b/.agents/skills/switchyard-lib-core/SKILL.md
@@ -61,7 +61,7 @@ Profile-owned construction keeps the full behavior in one reviewable module:
existing Python endpoint contract.
Random routing, deterministic routing, plan-execute, passthrough, no-op,
-cascade, latency-service, RouteLLM, and OSS-router profiles are the reference
+stage-router, latency-service, RouteLLM, and OSS-router profiles are the reference
set under `switchyard/lib/profiles/`.
## Anti-Patterns
diff --git a/.agents/skills/switchyard-pr-reviewer/SKILL.md b/.agents/skills/switchyard-pr-reviewer/SKILL.md
index 3494fa156..e0c8e05dc 100644
--- a/.agents/skills/switchyard-pr-reviewer/SKILL.md
+++ b/.agents/skills/switchyard-pr-reviewer/SKILL.md
@@ -59,7 +59,7 @@ Mixed Python + Rust: run Python modes here, dispatch `crates/*` hunks to
Use the word labels consistently. Correctness outranks cleanup/altitude when a cap forces a
cut. Tag the finding TYPE in parens, e.g. `Blocking (vacuous — the "clip" test never clips)`,
-`Blocking (project rule)`, `Important (reuse — duplicates CascadeFactory.validate)`.
+`Blocking (project rule)`, `Important (reuse — duplicates StageRouterFactory.validate)`.
| Label | Meaning | Examples from past PRs |
|---|---|---|
@@ -130,7 +130,7 @@ Rust mode reports **P0 / P1 / P2**; map P0→Blocking, P1→Important, P2→Mino
### Phase 4 — Design-coherence vs the ticket / stated intent
**Goal:** does the implementation match what the PR/ticket CLAIMS, at the right altitude?
**How:**
-- Compare impl to the ticket's scope and "Done when". Divergence is often *improvement* — say so — but isolate the one real gap (e.g. ticket promised "all multi-target routes" but impl is cascade-only).
+- Compare impl to the ticket's scope and "Done when". Divergence is often *improvement* — say so — but isolate the one real gap (e.g. ticket promised "all multi-target routes" but impl is stage-router-only).
- Altitude: special cases on shared infra, wire-format parsing leaking into the policy layer, tuning-data-masquerading-as-config → recommend generalizing.
- Defend **intentional** asymmetries instead of manufacturing a finding.
- Scope creep / mixed concerns / gratuitous churn → call out per commit-discipline.
diff --git a/.secrets.baseline b/.secrets.baseline
index 8c106c9c6..8c63cb159 100644
--- a/.secrets.baseline
+++ b/.secrets.baseline
@@ -98,6 +98,10 @@
"path": "detect_secrets.filters.common.is_baseline_file",
"filename": ".secrets.baseline"
},
+ {
+ "path": "detect_secrets.filters.common.is_ignored_due_to_verification_policies",
+ "min_level": 2
+ },
{
"path": "detect_secrets.filters.heuristic.is_indirect_reference"
},
@@ -136,24 +140,6 @@
"line_number": 96
}
],
- ".agents/skills/switchyard-latency-router-e2e/SKILL.md": [
- {
- "type": "NVIDIA API Key",
- "filename": ".agents/skills/switchyard-latency-router-e2e/SKILL.md",
- "hashed_secret": "ca19e614b4b099e0cfb439394cba84ccab67f3fa",
- "is_verified": false,
- "line_number": 57
- }
- ],
- ".agents/skills/switchyard-latency-router-e2e/scripts/live_check.py": [
- {
- "type": "Secret Keyword",
- "filename": ".agents/skills/switchyard-latency-router-e2e/scripts/live_check.py",
- "hashed_secret": "71f8e7976e4cbc4561c9d62fb283e7f788202acb",
- "is_verified": false,
- "line_number": 58
- }
- ],
".agents/skills/switchyard-testing-ci/SKILL.md": [
{
"type": "NVIDIA API Key",
@@ -282,22 +268,22 @@
"line_number": 165
}
],
- "crates/switchyard-components-v2/src/profiles/cascade.rs": [
+ "crates/switchyard-components-v2/src/profiles/stage_router.rs": [
{
"type": "Secret Keyword",
- "filename": "crates/switchyard-components-v2/src/profiles/cascade.rs",
+ "filename": "crates/switchyard-components-v2/src/profiles/stage_router.rs",
"hashed_secret": "3acfb2c2b433c0ea7ff107e33df91b18e52f960f",
"is_verified": false,
- "line_number": 1332
+ "line_number": 1341
}
],
- "crates/switchyard-components-v2/tests/cascade_profile.rs": [
+ "crates/switchyard-components-v2/tests/stage_router_profile.rs": [
{
"type": "Secret Keyword",
- "filename": "crates/switchyard-components-v2/tests/cascade_profile.rs",
+ "filename": "crates/switchyard-components-v2/tests/stage_router_profile.rs",
"hashed_secret": "3acfb2c2b433c0ea7ff107e33df91b18e52f960f",
"is_verified": false,
- "line_number": 265
+ "line_number": 273
}
],
"crates/switchyard-components/tests/adversarial_random_routing.rs": [
@@ -444,7 +430,7 @@
"filename": "tests/e2e/test_evict_reroute_e2e.py",
"hashed_secret": "d5017482ed9020c9d63a7f5f5f386f11f8f22286",
"is_verified": false,
- "line_number": 144
+ "line_number": 148
}
],
"tests/e2e/test_llm_classifier_e2e.py": [
@@ -535,54 +521,6 @@
"line_number": 168
}
],
- "tests/test_cascade_pickers.py": [
- {
- "type": "Secret Keyword",
- "filename": "tests/test_cascade_pickers.py",
- "hashed_secret": "58801e3391955d7ee7d51ba293351c3176f5b682",
- "is_verified": false,
- "line_number": 76
- }
- ],
- "tests/test_cascade_profile.py": [
- {
- "type": "Secret Keyword",
- "filename": "tests/test_cascade_profile.py",
- "hashed_secret": "766a6e8998aefe2117d62c2d48411e43161ffa11",
- "is_verified": false,
- "line_number": 53
- },
- {
- "type": "Secret Keyword",
- "filename": "tests/test_cascade_profile.py",
- "hashed_secret": "175a7e6aa66e82464d6b763d71df9ae96d1f8f41",
- "is_verified": false,
- "line_number": 87
- },
- {
- "type": "Secret Keyword",
- "filename": "tests/test_cascade_profile.py",
- "hashed_secret": "0120d11ff7768fae12cd00ae5d7f101bcc733a3e",
- "is_verified": false,
- "line_number": 93
- },
- {
- "type": "Secret Keyword",
- "filename": "tests/test_cascade_profile.py",
- "hashed_secret": "78427fc6cb8c9b8e955831b74962993f5decad22",
- "is_verified": false,
- "line_number": 98
- }
- ],
- "tests/test_cascade_request_processor.py": [
- {
- "type": "Secret Keyword",
- "filename": "tests/test_cascade_request_processor.py",
- "hashed_secret": "e9a5f12a8ecbb3eb46eca5096b5c52aa5e7c9fdd",
- "is_verified": false,
- "line_number": 27
- }
- ],
"tests/test_classifier_planner_chain.py": [
{
"type": "Secret Keyword",
@@ -1075,6 +1013,54 @@
"line_number": 235
}
],
+ "tests/test_stage_router_pickers.py": [
+ {
+ "type": "Secret Keyword",
+ "filename": "tests/test_stage_router_pickers.py",
+ "hashed_secret": "58801e3391955d7ee7d51ba293351c3176f5b682",
+ "is_verified": false,
+ "line_number": 76
+ }
+ ],
+ "tests/test_stage_router_profile.py": [
+ {
+ "type": "Secret Keyword",
+ "filename": "tests/test_stage_router_profile.py",
+ "hashed_secret": "766a6e8998aefe2117d62c2d48411e43161ffa11",
+ "is_verified": false,
+ "line_number": 53
+ },
+ {
+ "type": "Secret Keyword",
+ "filename": "tests/test_stage_router_profile.py",
+ "hashed_secret": "764a55c03be338b684fc85b2336605342d3f4d6a",
+ "is_verified": false,
+ "line_number": 87
+ },
+ {
+ "type": "Secret Keyword",
+ "filename": "tests/test_stage_router_profile.py",
+ "hashed_secret": "94aea60ba48c4e1711743f774291c8e653e0aceb",
+ "is_verified": false,
+ "line_number": 93
+ },
+ {
+ "type": "Secret Keyword",
+ "filename": "tests/test_stage_router_profile.py",
+ "hashed_secret": "78427fc6cb8c9b8e955831b74962993f5decad22",
+ "is_verified": false,
+ "line_number": 98
+ }
+ ],
+ "tests/test_stage_router_request_processor.py": [
+ {
+ "type": "Secret Keyword",
+ "filename": "tests/test_stage_router_request_processor.py",
+ "hashed_secret": "e9a5f12a8ecbb3eb46eca5096b5c52aa5e7c9fdd",
+ "is_verified": false,
+ "line_number": 27
+ }
+ ],
"tests/test_stream_leak_repro.py": [
{
"type": "Secret Keyword",
@@ -1207,5 +1193,5 @@
}
]
},
- "generated_at": "2026-07-06T19:13:06Z"
+ "generated_at": "2026-07-06T23:24:20Z"
}
diff --git a/AGENTS.md b/AGENTS.md
index f6a22fb00..4d474a4f5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -248,7 +248,7 @@ and their transitives never appear in downstream vulnerability scans.
export OPENAI_API_KEY="sk-..." # or NVIDIA_API_KEY / ANTHROPIC_API_KEY where supported
export OPENROUTER_API_KEY="sk-or-..." # pass with --api-key or save via configure
-# Serve a profile config (passthrough, random-routing, llm-routing, cascade).
+# Serve a profile config (passthrough, random-routing, llm-routing, stage_router).
# Endpoints, targets, and profiles live in the YAML; see docs/routing_algorithms/overview.md.
switchyard serve --config profiles.yaml --port 4000
switchyard serve --config profiles.yaml --inbound anthropic --port 4000
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 93459edde..07187269d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,10 +19,10 @@ traffic that sits between client applications and LLM backends.
native API regardless of the upstream backend.
- **YAML route bundles** (`switchyard serve --routing-profiles`) — one bundle,
many named routes, each its own chain. Supported route `type`s: `model`,
- `passthrough`, `random_routing`, `cascade`, `deterministic`
+ `passthrough`, `random_routing`, `stage_router`, `deterministic`
(LLM-as-classifier), `latency_service`, and `noop`.
-- **Routing strategies** — weighted random split, signal-driven **cascade**
- escalation (see [Cascade Routing](docs/cascade_routing.md)),
+- **Routing strategies** — weighted random split, signal-driven **stage-router**
+ escalation (see [Stage-Router Routing](docs/stage_router_routing.md)),
LLM-as-classifier strong/weak routing, and latency-aware multi-endpoint
failover.
- **One-command launchers** — `switchyard launch claude`, `launch codex`, and
@@ -35,7 +35,7 @@ traffic that sits between client applications and LLM backends.
(`/v1/routing/stats` alias), and per-request cost/token/latency stats. See
[Metrics Reference](docs/METRICS_REFERENCE.md).
- **Python library** — `SwitchyardRecipes` (`passthrough_recipe`,
- `random_routing_recipe`, `cascade_recipe`, `deterministic_routing_recipe`,
+ `random_routing_recipe`, `stage_router_recipe`, `deterministic_routing_recipe`,
…) and typed `ChatRequest` / `ChatResponse` containers for in-process use.
- **Rust core** (PyO3) — chain execution, the latency-aware router, and the
tool-result signal collector are implemented in Rust and re-exported to
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7ec479770..82087834b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -58,7 +58,7 @@ Commit messages must follow
This is enforced locally by the `commit-msg` hook and in GitHub Actions.
- ✓ `fix: handle async context cleanup in ProxyContext`
-- ✓ `feat: add cascade routing backend`
+- ✓ `feat: add stage-router routing backend`
- ✗ `Fixed stuff` / `Updated code`
Use one of:
diff --git a/README.md b/README.md
index 32f1c9218..2b8984016 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@ open-source model. Switchyard translates between the OpenAI Chat, Anthropic
Messages, and OpenAI Responses formats, so the agent keeps speaking its native
API while the request is served by vLLM, NVIDIA NIM, Ollama, or any
OpenAI-compatible endpoint. The same proxy can spread traffic across several
-models for A/B benchmarking, signal-driven cascade escalation, or a router you
+models for A/B benchmarking, signal-driven stage-router escalation, or a router you
write yourself.
**Launcher routing is explicit.** By default, launchers use the built-in
@@ -26,7 +26,7 @@ remains only for launcher-owned legacy bundles.
## Features
- **Protocol Translation**: convert between OpenAI Chat, Anthropic Messages, and OpenAI Responses formats
-- **Multi-Backend Routing**: random routing, LLM-as-classifier routing, signal-driven cascade, or custom routers
+- **Multi-Backend Routing**: random routing, LLM-as-classifier routing, signal-driven stage-router, or custom routers
- **Strong Types**: typed request/response containers for OpenAI, Anthropic, and Responses APIs
- **Profile-Owned Routing**: typed profiles own routing, backend calls, stats, and translation wiring
- **One-Command Launchers**: `switchyard launch claude`, `switchyard launch codex`, and `switchyard launch openclaw` spin up a local proxy and drop you into the target CLI
@@ -149,7 +149,7 @@ strategy-specific page:
- [Random Routing](docs/routing_algorithms/random_routing.md)
- [LLM Classifier Routing](docs/routing_algorithms/llm_classifier_routing.md)
-- [Cascade Routing](docs/routing_algorithms/cascade_routing.md)
+- [Stage-Router Routing](docs/routing_algorithms/stage_router_routing.md)
For multi-turn classifier sessions, see
[Session Affinity (Sticky Routing)](docs/routing_algorithms/sticky_routing.md).
@@ -223,7 +223,7 @@ See [Installation](INSTALLATION.md) for a full breakdown of what each extra adds
- **[Agent Launchers](docs/guides/agent_launchers.md)**: Claude Code, Codex, and OpenClaw launcher behavior
- **[Cli Reference](docs/cli_reference.md)**: canonical reference for every `switchyard` subcommand and flag
- **[Architecture](docs/architecture.md)**: system context and end-to-end request flow
-- **[Routing Algorithms](docs/routing_algorithms/)**: signal-driven weak/strong cascade routing: picker layers, signal dimensions, and calibration data.
+- **[Routing Algorithms](docs/routing_algorithms/)**: signal-driven weak/strong stage-router routing: picker layers, signal dimensions, and calibration data.
- **[Contributing](CONTRIBUTING.md)**: dev setup, testing, CI gates, PR process
- **[Development](DEVELOPMENT.md)**: project structure, benchmarks, conventions
- **[Agents](AGENTS.md)**: full design philosophy and architectural patterns
diff --git a/benchmark/calibration/cascade/calibrate.py b/benchmark/calibration/stage_router/calibrate.py
similarity index 87%
rename from benchmark/calibration/cascade/calibrate.py
rename to benchmark/calibration/stage_router/calibrate.py
index 6d5b6033c..7b8a97d67 100644
--- a/benchmark/calibration/cascade/calibrate.py
+++ b/benchmark/calibration/stage_router/calibrate.py
@@ -1,11 +1,11 @@
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
-"""Calibrate cascade confidence threshold from Harbor run outputs.
+"""Calibrate stage_router confidence threshold from Harbor run outputs.
-Pass the Harbor run output directories for the pure-strong and pure-weak arms:
+Pass the Harbor run output directories for the pure-capable and pure-efficient arms:
- python calibrate.py --strong-run-dir /tmp/runs/strong --weak-run-dir /tmp/runs/weak
+ python calibrate.py --capable-run-dir /tmp/runs/capable --efficient-run-dir /tmp/runs/efficient
python sweep.py
"""
from __future__ import annotations
@@ -25,19 +25,19 @@ _RANK = {"pass": 2, "fail": 1, "err": 0}
def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
parser = argparse.ArgumentParser(
- description="Calibrate cascade confidence threshold from Harbor run outputs."
+ description="Calibrate stage_router confidence threshold from Harbor run outputs."
)
parser.add_argument(
- "--strong-run-dir",
+ "--capable-run-dir",
type=Path,
required=True,
- help="Harbor output directory for the pure-strong run.",
+ help="Harbor output directory for the pure-capable run.",
)
parser.add_argument(
- "--weak-run-dir",
+ "--efficient-run-dir",
type=Path,
required=True,
- help="Harbor output directory for the pure-weak probe run.",
+ help="Harbor output directory for the pure-efficient probe run.",
)
return parser.parse_args(argv)
@@ -92,8 +92,8 @@ def read_arm(arm_dir: Path):
def main(argv: list[str] | None = None):
args = parse_args(argv)
arms = {
- "strong": args.strong_run_dir,
- "weak": args.weak_run_dir,
+ "capable": args.capable_run_dir,
+ "efficient": args.efficient_run_dir,
}
all_outcomes: dict[str, dict] = {}
all_feats: dict[str, dict] = {}
diff --git a/benchmark/calibration/cascade/signal_extractor.py b/benchmark/calibration/stage_router/signal_extractor.py
similarity index 99%
rename from benchmark/calibration/cascade/signal_extractor.py
rename to benchmark/calibration/stage_router/signal_extractor.py
index eb868c3fc..007d13112 100644
--- a/benchmark/calibration/cascade/signal_extractor.py
+++ b/benchmark/calibration/stage_router/signal_extractor.py
@@ -4,7 +4,7 @@
"""Python port of crates/switchyard-components/src/dimension_collector/tool_signals.rs.
Reads a claude-code session JSONL trajectory and reconstructs the per-turn
-ToolResultSignal that the cascade picker would have seen. Output is one record
+ToolResultSignal that the stage_router picker would have seen. Output is one record
per assistant turn.
"""
from __future__ import annotations
diff --git a/benchmark/calibration/cascade/sweep.py b/benchmark/calibration/stage_router/sweep.py
similarity index 94%
rename from benchmark/calibration/cascade/sweep.py
rename to benchmark/calibration/stage_router/sweep.py
index 148568f11..11950c217 100644
--- a/benchmark/calibration/cascade/sweep.py
+++ b/benchmark/calibration/stage_router/sweep.py
@@ -34,12 +34,12 @@ def load():
return by, outcomes
-def score(by, outcomes, picker_fn, strong="strong", weak="weak"):
+def score(by, outcomes, picker_fn, capable="capable", efficient="efficient"):
P = F = E = esc = 0
for task, arms in outcomes.items():
- turns = by.get((task, strong), [])
+ turns = by.get((task, capable), [])
escalate = picker_fn(turns) if turns else False
- o = arms.get(weak if escalate else strong, "err")
+ o = arms.get(efficient if escalate else capable, "err")
if escalate:
esc += 1
if o == "pass":
diff --git a/benchmark/dimension_calibration/corpus_manifest.yaml b/benchmark/dimension_calibration/corpus_manifest.yaml
index 72024bf7e..a49ce7b50 100644
--- a/benchmark/dimension_calibration/corpus_manifest.yaml
+++ b/benchmark/dimension_calibration/corpus_manifest.yaml
@@ -33,17 +33,17 @@ runs:
# The runner skips entries whose path does not exist, so unused stubs are
# harmless.
- - id: cascade-strong-default-deepseek
+ - id: stage_router-strong-default-deepseek
extractor: harbor
- source: cascade-strong-default-deepseek
- path: "benchmark/tb_runs/tb-lite-cascade-strong-default-deepseek/jobs/tb-lite-cascade-strong-default-deepseek"
- label: "Cascade — cascade_strong_default picker, Opus + DeepSeek"
+ source: stage_router-strong-default-deepseek
+ path: "benchmark/tb_runs/tb-lite-stage_router-strong-default-deepseek/jobs/tb-lite-stage_router-strong-default-deepseek"
+ label: "StageRouter — capable_first picker, Opus + DeepSeek"
- - id: cascade-strong-default-nemotron
+ - id: stage_router-strong-default-nemotron
extractor: harbor
- source: cascade-strong-default-nemotron
- path: "benchmark/tb_runs/tb-lite-cascade-strong-default-nemotron/jobs/tb-lite-cascade-strong-default-nemotron"
- label: "Cascade — cascade_strong_default picker, Opus + Nemotron"
+ source: stage_router-strong-default-nemotron
+ path: "benchmark/tb_runs/tb-lite-stage_router-strong-default-nemotron/jobs/tb-lite-stage_router-strong-default-nemotron"
+ label: "StageRouter — capable_first picker, Opus + Nemotron"
- id: all-opus
extractor: harbor
diff --git a/benchmark/dimension_calibration/extractors/__init__.py b/benchmark/dimension_calibration/extractors/__init__.py
index 6dc4162ea..dc0417c9b 100644
--- a/benchmark/dimension_calibration/extractors/__init__.py
+++ b/benchmark/dimension_calibration/extractors/__init__.py
@@ -28,7 +28,7 @@ class ScoredPrompt:
"""
run_id: str
- source: str # label from the manifest entry (e.g. "cascade-settle-aware")
+ source: str # label from the manifest entry (e.g. "stage_router-settle-aware")
task: str # task id (e.g. "book-portfolio-analysis")
turn_idx: int # 0-based turn within the trajectory
full: str # full prompt blob (system + history + latest user)
diff --git a/benchmark/dimension_calibration/extractors/harbor.py b/benchmark/dimension_calibration/extractors/harbor.py
index 81c378e7b..828d6e6a0 100644
--- a/benchmark/dimension_calibration/extractors/harbor.py
+++ b/benchmark/dimension_calibration/extractors/harbor.py
@@ -18,7 +18,7 @@ directory to point the manifest at.
The ``source`` field on emitted records comes from the manifest entry's
``source:`` key (defaults to ``"harbor"``). Use distinct source labels on
-different runs (e.g. ``cascade-settle-aware``, ``all-opus``) so the by-source slice in
+different runs (e.g. ``stage_router-settle-aware``, ``all-opus``) so the by-source slice in
the report compares like-with-like.
"""
diff --git a/crates/switchyard-components-v2/DESIGN.md b/crates/switchyard-components-v2/DESIGN.md
index ea4aac92c..3da7e4511 100644
--- a/crates/switchyard-components-v2/DESIGN.md
+++ b/crates/switchyard-components-v2/DESIGN.md
@@ -21,7 +21,7 @@ Profile
```
A profile owns the behavior for one addressable Switchyard mode. That can be passthrough,
-random routing, latency-aware routing, a classifier cascade, observability-only middleware, or a
+random routing, latency-aware routing, a classifier stage-router, observability-only middleware, or a
future agent-facing policy. The profile decides how a request is prepared, which backend is called,
what response cleanup is needed, and where observability is recorded.
@@ -384,13 +384,14 @@ endpoints:
api_key: ${NVIDIA_API_KEY}
timeout_secs: 120.0
+# Targets are named by the model id they serve.
targets:
- strong:
+ nvidia/frontier-model:
endpoint: nvidia
model: nvidia/frontier-model
format: openai
- weak:
+ nvidia/fast-model:
endpoint: nvidia
model: nvidia/fast-model
format: openai
@@ -398,14 +399,14 @@ targets:
profiles:
direct:
type: passthrough
- target: weak
-
- smart-cascade:
- type: cascade
- strong: strong
- weak: weak
- fallback_target_on_evict: strong
- picker: cascade_strong_default
+ target: nvidia/fast-model
+
+ smart-stage-router:
+ type: stage_router
+ capable: nvidia/frontier-model
+ efficient: nvidia/fast-model
+ fallback_target_on_evict: nvidia/frontier-model
+ picker: capable_first
confidence_threshold: 0.7
```
@@ -425,7 +426,7 @@ Box<dyn Profile>
```
`ProfileConfigDocument` is the parsed file shape. It is allowed to contain config-facing
-references, such as `target: weak` or `endpoint: nvidia`. It is not runtime-ready.
+references, such as `target: nvidia/fast-model` or `endpoint: nvidia`. It is not runtime-ready.
`ProfileConfigPlan` is the resolved plan. It has concrete `LlmTarget` values and typed profile
configs. The design deliberately does not rebuild the old graph/table/factory system. The plan is
diff --git a/crates/switchyard-components-v2/src/lib.rs b/crates/switchyard-components-v2/src/lib.rs
index f5d0aa613..201b04a5f 100644
--- a/crates/switchyard-components-v2/src/lib.rs
+++ b/crates/switchyard-components-v2/src/lib.rs
@@ -22,13 +22,13 @@ pub use profile::{
Profile, ProfileHooks, ProfileInput, ProfileResponse, RequestMetadata, RoutingMetadata,
};
pub use profiles::{
- CascadeClassifierConfig, CascadeDecision, CascadeDecisionSource, CascadePickerMode,
- CascadeProcessedRequest, CascadeProfile, CascadeProfileConfig, CascadeTier, EndpointHealth,
- EndpointHealthStatus, LatencyServiceProcessedRequest, LatencyServiceProfile,
+ EndpointHealth, EndpointHealthStatus, LatencyServiceProcessedRequest, LatencyServiceProfile,
LatencyServiceProfileConfig, LlmRoutingDecision, LlmRoutingProcessedRequest, LlmRoutingProfile,
LlmRoutingProfileConfig, LlmRoutingTierMapping, NoopProfile, NoopProfileConfig,
PassthroughProfile, PassthroughProfileConfig, RandomRoutingProcessedRequest,
- RandomRoutingProfile, RandomRoutingProfileConfig, SelectedTarget,
+ RandomRoutingProfile, RandomRoutingProfileConfig, SelectedTarget, StageRouterClassifierConfig,
+ StageRouterDecision, StageRouterDecisionSource, StageRouterPickerMode,
+ StageRouterProcessedRequest, StageRouterProfile, StageRouterProfileConfig, StageRouterTier,
};
pub use stats::profile_stats_accumulator;
pub use switchyard_components_v2_macros::profile_config;
diff --git a/crates/switchyard-components-v2/src/profiles/cascade/prompts/classifier.md b/crates/switchyard-components-v2/src/profiles/cascade/prompts/classifier.md
deleted file mode 100644
index c20c15d13..000000000
--- a/crates/switchyard-components-v2/src/profiles/cascade/prompts/classifier.md
+++ /dev/null
@@ -1,5 +0,0 @@
-You are a routing classifier inside an agentic coding cascade. Given a compact summary of the agent's recent tool activity, decide whether the next model call should go to the STRONG tier (capable, expensive) or the WEAK tier (cheap, less capable).
-
-Respond with strict JSON: {"tier": "strong"} or {"tier": "weak"}.
-
-Pick WEAK when the agent shows concrete, low-friction progress (writes landing, tests passing, edits without errors). Pick STRONG when the agent is stalled, hitting errors, or facing a task likely to require careful reasoning.
diff --git a/crates/switchyard-components-v2/src/profiles/mod.rs b/crates/switchyard-components-v2/src/profiles/mod.rs
index d89a6d18e..91ca996b2 100644
--- a/crates/switchyard-components-v2/src/profiles/mod.rs
+++ b/crates/switchyard-components-v2/src/profiles/mod.rs
@@ -3,7 +3,6 @@
//! Profile implementations in the flatter components-v2 design.
-mod cascade;
mod latency_service;
mod llm_routing;
mod macros;
@@ -11,11 +10,8 @@ mod noop;
mod passthrough;
mod profile_types;
mod random_routing;
+mod stage_router;
-pub use cascade::{
- CascadeClassifierConfig, CascadeDecision, CascadeDecisionSource, CascadePickerMode,
- CascadeProcessedRequest, CascadeProfile, CascadeProfileConfig, CascadeTier,
-};
pub use latency_service::{
EndpointHealth, EndpointHealthStatus, LatencyServiceProcessedRequest, LatencyServiceProfile,
LatencyServiceProfileConfig, SelectedTarget,
@@ -30,3 +26,8 @@ pub(crate) use profile_types::{parse_profile_config, ProfileConfigEntry};
pub use random_routing::{
RandomRoutingProcessedRequest, RandomRoutingProfile, RandomRoutingProfileConfig,
};
+pub use stage_router::{
+ StageRouterClassifierConfig, StageRouterDecision, StageRouterDecisionSource,
+ StageRouterPickerMode, StageRouterProcessedRequest, StageRouterProfile,
+ StageRouterProfileConfig, StageRouterTier,
+};
diff --git a/crates/switchyard-components-v2/src/profiles/profile_types.rs b/crates/switchyard-components-v2/src/profiles/profile_types.rs
index 1be227612..3126a8154 100644
--- a/crates/switchyard-components-v2/src/profiles/profile_types.rs
+++ b/crates/switchyard-components-v2/src/profiles/profile_types.rs
@@ -5,12 +5,12 @@
use super::macros::profile_types;
use super::{
- CascadeProfileConfig, LatencyServiceProfileConfig, LlmRoutingProfileConfig, NoopProfileConfig,
- PassthroughProfileConfig, RandomRoutingProfileConfig,
+ LatencyServiceProfileConfig, LlmRoutingProfileConfig, NoopProfileConfig,
+ PassthroughProfileConfig, RandomRoutingProfileConfig, StageRouterProfileConfig,
};
profile_types! {
- CascadeProfileConfig,
+ StageRouterProfileConfig,
PassthroughProfileConfig,
RandomRoutingProfileConfig,
LatencyServiceProfileConfig,
diff --git a/crates/switchyard-components-v2/src/profiles/cascade.rs b/crates/switchyard-components-v2/src/profiles/stage_router.rs
similarity index 79%
rename from crates/switchyard-components-v2/src/profiles/cascade.rs
rename to crates/switchyard-components-v2/src/profiles/stage_router.rs
index 83e41f6d0..9a864308e 100644
--- a/crates/switchyard-components-v2/src/profiles/cascade.rs
+++ b/crates/switchyard-components-v2/src/profiles/stage_router.rs
@@ -1,7 +1,7 @@
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0
-//! Signal cascade profile implemented as a profile-owned Rust runtime.
+//! Signal stage_router profile implemented as a profile-owned Rust runtime.
use std::time::{Duration, Instant};
@@ -27,14 +27,14 @@ const DEFAULT_CLASSIFIER_TIMEOUT_SECS: f64 = 30.0;
const DEFAULT_CLASSIFIER_RECENT_TURN_WINDOW: usize = 3;
const CLASSIFIER_MAX_TOKENS: u32 = 4096;
const DEFAULT_OPENAI_BASE_URL: &str = "https://api.openai.com/v1";
-const CASCADE_PROFILE_TYPE: &str = "cascade";
+const STAGE_ROUTER_PROFILE_TYPE: &str = "stage_router";
const SEVERITY_CRITICAL: f32 = 1.0;
const CLEAN_TESTS_MIN_TURN_DEPTH: u32 = 10;
const CLEAN_TESTS_MAX_WRITES: u32 = 1;
const PURE_BASH_NORM: f64 = 8.0;
-const CLASSIFIER_SYSTEM_PROMPT: &str = include_str!("cascade/prompts/classifier.md");
+const CLASSIFIER_SYSTEM_PROMPT: &str = include_str!("stage_router/prompts/classifier.md");
const DEFAULT_WEIGHTS: &[(&str, f64)] = &[
("severity", 0.80),
@@ -52,18 +52,18 @@ const DEFAULT_WEIGHTS: &[(&str, f64)] = &[
/// Default picker mode names the tier used when the scorer is ambiguous.
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
-pub enum CascadePickerMode {
- /// Default to strong unless the scorer/classifier confidently picks weak.
- CascadeStrongDefault,
- /// Default to weak unless the scorer/classifier confidently picks strong.
- CascadeWeakDefault,
+pub enum StageRouterPickerMode {
+ /// Default to capable unless the scorer/classifier confidently picks efficient.
+ CapableFirst,
+ /// Default to efficient unless the scorer/classifier confidently picks capable.
+ EfficientFirst,
}
-impl CascadePickerMode {
- fn default_tier(self) -> CascadeTier {
+impl StageRouterPickerMode {
+ fn default_tier(self) -> StageRouterTier {
match self {
- Self::CascadeStrongDefault => CascadeTier::Strong,
- Self::CascadeWeakDefault => CascadeTier::Weak,
+ Self::CapableFirst => StageRouterTier::Capable,
+ Self::EfficientFirst => StageRouterTier::Efficient,
}
}
}
@@ -71,7 +71,7 @@ impl CascadePickerMode {
/// Optional LLM classifier invoked for low-confidence scorer outputs.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
-pub struct CascadeClassifierConfig {
+pub struct StageRouterClassifierConfig {
/// OpenAI-compatible classifier model.
pub model: String,
/// API key used for the classifier call.
@@ -93,20 +93,20 @@ pub struct CascadeClassifierConfig {
pub system_prompt: Option<String>,
}
-/// Config for a strong/weak signal cascade profile.
-#[profile_config("cascade")]
-pub struct CascadeProfileConfig {
- /// Strong target served by this profile.
+/// Config for a capable/efficient signal stage_router profile.
+#[profile_config("stage_router")]
+pub struct StageRouterProfileConfig {
+ /// Capable target served by this profile.
#[profile_target]
- pub strong: LlmTarget,
- /// Weak target served by this profile.
+ pub capable: LlmTarget,
+ /// Efficient target served by this profile.
#[profile_target]
- pub weak: LlmTarget,
+ pub efficient: LlmTarget,
/// Target used for one retry after context-window overflow.
pub fallback_target_on_evict: LlmTargetId,
/// Picker mode controlling the low-confidence default tier.
#[serde(default = "default_picker")]
- pub picker: CascadePickerMode,
+ pub picker: StageRouterPickerMode,
/// Scorer confidence threshold in `[0.0, 1.0]`.
#[serde(default = "default_confidence_threshold")]
pub confidence_threshold: f64,
@@ -115,21 +115,21 @@ pub struct CascadeProfileConfig {
pub signal_recent_window: usize,
/// Optional LLM classifier for ambiguous scorer outputs.
#[serde(default)]
- pub classifier: Option<CascadeClassifierConfig>,
+ pub classifier: Option<StageRouterClassifierConfig>,
/// Whether to emit stats for this profile.
#[serde(default = "default_enable_stats")]
pub enable_stats: bool,
}
-impl ProfileConfig for CascadeProfileConfig {
- type Runtime = CascadeProfile;
+impl ProfileConfig for StageRouterProfileConfig {
+ type Runtime = StageRouterProfile;
/// Builds the runtime profile using native target backends.
fn build(&self) -> Result<Self::Runtime> {
self.validate()?;
- Ok(CascadeProfile {
- strong_backend: native_target_backend(self.strong.clone())?,
- weak_backend: native_target_backend(self.weak.clone())?,
+ Ok(StageRouterProfile {
+ capable_backend: native_target_backend(self.capable.clone())?,
+ efficient_backend: native_target_backend(self.efficient.clone())?,
fallback_target_on_evict: self.fallback_target_on_evict.clone(),
picker: self.picker,
confidence_threshold: self.confidence_threshold,
@@ -137,7 +137,7 @@ impl ProfileConfig for CascadeProfileConfig {
classifier: self
.classifier
.as_ref()
- .map(CascadeTierClassifier::new)
+ .map(StageRouterTierClassifier::new)
.transpose()?,
stats: profile_stats_accumulator(),
enable_stats: self.enable_stats,
@@ -145,11 +145,12 @@ impl ProfileConfig for CascadeProfileConfig {
}
}
-impl CascadeProfileConfig {
+impl StageRouterProfileConfig {
fn validate(&self) -> Result<()> {
- if self.strong.id == self.weak.id {
+ if self.capable.id == self.efficient.id {
return Err(SwitchyardError::InvalidConfig(
- "cascade strong and weak targets must have distinct target ids".to_string(),
+ "stage_router capable and efficient targets must have distinct target ids"
+ .to_string(),
));
}
if !self.confidence_threshold.is_finite()
@@ -165,12 +166,12 @@ impl CascadeProfileConfig {
"signal_recent_window must be at least 1".to_string(),
));
}
- if self.fallback_target_on_evict != self.strong.id
- && self.fallback_target_on_evict != self.weak.id
+ if self.fallback_target_on_evict != self.capable.id
+ && self.fallback_target_on_evict != self.efficient.id
{
return Err(SwitchyardError::InvalidConfig(format!(
"fallback_target_on_evict={} must match one of [{}, {}]",
- self.fallback_target_on_evict, self.weak.id, self.strong.id
+ self.fallback_target_on_evict, self.efficient.id, self.capable.id
)));
}
if let Some(classifier) = &self.classifier {
@@ -180,7 +181,7 @@ impl CascadeProfileConfig {
}
}
-impl CascadeClassifierConfig {
+impl StageRouterClassifierConfig {
fn validate(&self) -> Result<()> {
if self.model.trim().is_empty() {
return Err(SwitchyardError::InvalidConfig(
@@ -209,51 +210,51 @@ impl CascadeClassifierConfig {
}
}
-/// Strong/weak cascade profile runtime.
-pub struct CascadeProfile {
- strong_backend: TargetBackend,
- weak_backend: TargetBackend,
+/// Capable/efficient stage_router profile runtime.
+pub struct StageRouterProfile {
+ capable_backend: TargetBackend,
+ efficient_backend: TargetBackend,
fallback_target_on_evict: LlmTargetId,
- picker: CascadePickerMode,
+ picker: StageRouterPickerMode,
confidence_threshold: f64,
signal_recent_window: usize,
- classifier: Option<CascadeTierClassifier>,
+ classifier: Option<StageRouterTierClassifier>,
stats: StatsAccumulator,
enable_stats: bool,
}
-/// Processed cascade request with profile-owned decision state.
-pub struct CascadeProcessedRequest {
+/// Processed stage_router request with profile-owned decision state.
+pub struct StageRouterProcessedRequest {
/// Routed input prepared for the selected backend.
pub profile_input: ProfileInput,
/// Selected routing decision for this request.
- pub decision: CascadeDecision,
+ pub decision: StageRouterDecision,
}
-/// Named side of a cascade decision.
+/// Named side of a stage_router decision.
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
-pub enum CascadeTier {
- /// Strong tier.
- Strong,
- /// Weak tier.
- Weak,
+pub enum StageRouterTier {
+ /// Capable tier.
+ Capable,
+ /// Efficient tier.
+ Efficient,
}
-impl CascadeTier {
+impl StageRouterTier {
/// Stable lowercase label used by stats.
pub fn as_str(self) -> &'static str {
match self {
- Self::Strong => "strong",
- Self::Weak => "weak",
+ Self::Capable => "capable",
+ Self::Efficient => "efficient",
}
}
}
-/// Source that produced a cascade decision.
+/// Source that produced a stage_router decision.
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
-pub enum CascadeDecisionSource {
+pub enum StageRouterDecisionSource {
/// Hard override fired.
Override,
/// Dimension scorer crossed `confidence_threshold`.
@@ -267,7 +268,7 @@ pub enum CascadeDecisionSource {
ContextOverflowFallback,
}
-impl CascadeDecisionSource {
+impl StageRouterDecisionSource {
/// Stable lowercase label used in stats JSON.
pub fn as_str(self) -> &'static str {
match self {
@@ -280,11 +281,11 @@ impl CascadeDecisionSource {
}
}
-/// Cascade routing decision with the selected target and scorer metadata.
+/// StageRouter routing decision with the selected target and scorer metadata.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
-pub struct CascadeDecision {
- /// Selected strong/weak side.
- pub tier: CascadeTier,
+pub struct StageRouterDecision {
+ /// Selected capable/efficient side.
+ pub tier: StageRouterTier,
/// Selected target id.
pub selected_target: LlmTargetId,
/// Selected upstream model.
@@ -292,28 +293,28 @@ pub struct CascadeDecision {
/// Client-provided model before routing.
pub original_model: Option<String>,
/// Decision source for observability.
- pub source: CascadeDecisionSource,
+ pub source: StageRouterDecisionSource,
/// Linear scorer value in `[-1.0, 1.0]`.
pub score: f64,
/// Router confidence when the decision source produced one.
pub confidence: Option<f64>,
}
-impl CascadeProfile {
- async fn route_request(&self, mut input: ProfileInput) -> Result<CascadeProcessedRequest> {
+impl StageRouterProfile {
+ async fn route_request(&self, mut input: ProfileInput) -> Result<StageRouterProcessedRequest> {
let signal = extract_tool_signals_with_window(&input.request, self.signal_recent_window);
let original_model = input.request.model().map(std::borrow::ToOwned::to_owned);
let decision = self.pick(&input.request, &signal, original_model).await?;
input.request.set_model(decision.selected_model.as_str());
self.record_decision_source(decision.source)?;
- Ok(CascadeProcessedRequest {
+ Ok(StageRouterProcessedRequest {
profile_input: input,
decision,
})
}
// Routing decision flow:
- // 1. Hard overrides choose strong for critical failures or weak for clean tests.
+ // 1. Hard overrides choose capable for critical failures or efficient for clean tests.
// 2. Dimensions scoring chooses by score sign when confidence clears the threshold.
// 3. Low-confidence requests use the optional LLM classifier when configured.
// 4. Missing or failed classifier output falls open to the picker default tier.
@@ -322,12 +323,12 @@ impl CascadeProfile {
request: &ChatRequest,
signal: &ToolResultSignal,
original_model: Option<String>,
- ) -> Result<CascadeDecision> {
+ ) -> Result<StageRouterDecision> {
if let Some(tier) = apply_overrides(signal) {
return self.decision_for_tier(
tier,
original_model,
- CascadeDecisionSource::Override,
+ StageRouterDecisionSource::Override,
0.0,
Some(1.0),
);
@@ -336,14 +337,14 @@ impl CascadeProfile {
let score = score_signal(signal);
if score.confidence >= self.confidence_threshold {
let tier = if score.score > 0.0 {
- CascadeTier::Strong
+ StageRouterTier::Capable
} else {
- CascadeTier::Weak
+ StageRouterTier::Efficient
};
return self.decision_for_tier(
tier,
original_model,
- CascadeDecisionSource::Dimensions,
+ StageRouterDecisionSource::Dimensions,
score.score,
Some(score.confidence),
);
@@ -357,7 +358,7 @@ impl CascadeProfile {
return self.decision_for_tier(
tier,
original_model,
- CascadeDecisionSource::LlmClassifier,
+ StageRouterDecisionSource::LlmClassifier,
score.score,
None,
);
@@ -367,7 +368,7 @@ impl CascadeProfile {
self.decision_for_tier(
self.picker.default_tier(),
original_model,
- CascadeDecisionSource::FallOpen,
+ StageRouterDecisionSource::FallOpen,
score.score,
Some(score.confidence),
)
@@ -375,15 +376,15 @@ impl CascadeProfile {
fn decision_for_tier(
&self,
- tier: CascadeTier,
+ tier: StageRouterTier,
original_model: Option<String>,
- source: CascadeDecisionSource,
+ source: StageRouterDecisionSource,
score: f64,
confidence: Option<f64>,
- ) -> Result<CascadeDecision> {
+ ) -> Result<StageRouterDecision> {
let backend = self.backend_for_tier(tier);
let target = backend.target();
- Ok(CascadeDecision {
+ Ok(StageRouterDecision {
tier,
selected_target: target.id.clone(),
selected_model: target.model.clone(),
@@ -394,15 +395,15 @@ impl CascadeProfile {
})
}
- fn fallback_decision(&self, decision: &CascadeDecision) -> Result<CascadeDecision> {
+ fn fallback_decision(&self, decision: &StageRouterDecision) -> Result<StageRouterDecision> {
let backend = self.backend_for_target(&self.fallback_target_on_evict)?;
let target = backend.target();
- Ok(CascadeDecision {
+ Ok(StageRouterDecision {
tier: self.tier_for_target(&target.id)?,
selected_target: target.id.clone(),
selected_model: target.model.clone(),
original_model: decision.original_model.clone(),
- source: CascadeDecisionSource::ContextOverflowFallback,
+ source: StageRouterDecisionSource::ContextOverflowFallback,
score: decision.score,
confidence: decision.confidence,
})
@@ -410,53 +411,53 @@ impl CascadeProfile {
fn retry_processed_request(
&self,
- processed: &CascadeProcessedRequest,
- ) -> Result<CascadeProcessedRequest> {
+ processed: &StageRouterProcessedRequest,
+ ) -> Result<StageRouterProcessedRequest> {
let decision = self.fallback_decision(&processed.decision)?;
let mut profile_input = processed.profile_input.clone();
profile_input
.request
.set_model(decision.selected_model.as_str());
- Ok(CascadeProcessedRequest {
+ Ok(StageRouterProcessedRequest {
profile_input,
decision,
})
}
- fn backend_for_tier(&self, tier: CascadeTier) -> &TargetBackend {
+ fn backend_for_tier(&self, tier: StageRouterTier) -> &TargetBackend {
match tier {
- CascadeTier::Strong => &self.strong_backend,
- CascadeTier::Weak => &self.weak_backend,
+ StageRouterTier::Capable => &self.capable_backend,
+ StageRouterTier::Efficient => &self.efficient_backend,
}
}
fn backend_for_target(&self, target_id: &LlmTargetId) -> Result<&TargetBackend> {
- if *target_id == self.strong_backend.target().id {
- Ok(&self.strong_backend)
- } else if *target_id == self.weak_backend.target().id {
- Ok(&self.weak_backend)
+ if *target_id == self.capable_backend.target().id {
+ Ok(&self.capable_backend)
+ } else if *target_id == self.efficient_backend.target().id {
+ Ok(&self.efficient_backend)
} else {
Err(SwitchyardError::InvalidConfig(format!(
- "cascade selected target {target_id} that is not configured for this profile"
+ "stage_router selected target {target_id} that is not configured for this profile"
)))
}
}
- fn tier_for_target(&self, target_id: &LlmTargetId) -> Result<CascadeTier> {
- if *target_id == self.strong_backend.target().id {
- Ok(CascadeTier::Strong)
- } else if *target_id == self.weak_backend.target().id {
- Ok(CascadeTier::Weak)
+ fn tier_for_target(&self, target_id: &LlmTargetId) -> Result<StageRouterTier> {
+ if *target_id == self.capable_backend.target().id {
+ Ok(StageRouterTier::Capable)
+ } else if *target_id == self.efficient_backend.target().id {
+ Ok(StageRouterTier::Efficient)
} else {
Err(SwitchyardError::InvalidConfig(format!(
- "cascade target {target_id} is not configured for this profile"
+ "stage_router target {target_id} is not configured for this profile"
)))
}
}
async fn call_selected(
&self,
- processed: &CascadeProcessedRequest,
+ processed: &StageRouterProcessedRequest,
) -> (Result<ChatResponse>, f64) {
let started_at = Instant::now();
let backend = match self.backend_for_target(&processed.decision.selected_target) {
@@ -472,16 +473,16 @@ impl CascadeProfile {
self.enable_stats.then_some(&self.stats)
}
- fn record_decision_source(&self, source: CascadeDecisionSource) -> Result<()> {
+ fn record_decision_source(&self, source: StageRouterDecisionSource) -> Result<()> {
if let Some(stats) = self.stats_handle() {
- stats.record_routing_decision(CASCADE_PROFILE_TYPE, source.as_str())?;
+ stats.record_routing_decision(STAGE_ROUTER_PROFILE_TYPE, source.as_str())?;
}
Ok(())
}
fn record_success(
&self,
- decision: &CascadeDecision,
+ decision: &StageRouterDecision,
response: &ChatResponse,
total_latency_ms: f64,
backend_latency_ms: f64,
@@ -505,7 +506,7 @@ impl CascadeProfile {
Ok(())
}
- fn record_error(&self, decision: &CascadeDecision) -> Result<()> {
+ fn record_error(&self, decision: &StageRouterDecision) -> Result<()> {
if let Some(stats) = self.stats_handle() {
stats.record_error(
decision.selected_model.as_str(),
@@ -515,15 +516,15 @@ impl CascadeProfile {
Ok(())
}
- fn routing_metadata(&self, decision: &CascadeDecision) -> RoutingMetadata {
+ fn routing_metadata(&self, decision: &StageRouterDecision) -> RoutingMetadata {
RoutingMetadata {
selected_model: Some(decision.selected_model.to_string()),
selected_tier: Some(decision.tier.as_str().to_string()),
confidence: decision.confidence,
- router_version: Some("cascade:v1".to_string()),
+ router_version: Some("stage_router:v1".to_string()),
tolerance: Some(self.confidence_threshold),
rationale: Some(format!(
- "cascade source={}; score={}; selected {}",
+ "stage_router source={}; score={}; selected {}",
decision.source.as_str(),
decision.score,
decision.tier.as_str()
@@ -533,15 +534,15 @@ impl CascadeProfile {
}
#[async_trait]
-impl ProfileHooks for CascadeProfile {
- type ProcessedRequest = CascadeProcessedRequest;
+impl ProfileHooks for StageRouterProfile {
+ type ProcessedRequest = StageRouterProcessedRequest;
/// Extracts signals, picks a tier, and rewrites the request model.
async fn process(&self, input: ProfileInput) -> Result<Self::ProcessedRequest> {
self.route_request(input).await
}
- /// Leaves the backend response unchanged after cascade routing completes.
+ /// Leaves the backend response unchanged after stage_router routing completes.
async fn rprocess(
&self,
_processed: &Self::ProcessedRequest,
@@ -552,8 +553,8 @@ impl ProfileHooks for CascadeProfile {
}
#[async_trait]
-impl Profile for CascadeProfile {
- /// Executes cascade routing with one context-window fallback retry.
+impl Profile for StageRouterProfile {
+ /// Executes stage_router routing with one context-window fallback retry.
async fn run(&self, input: ProfileInput) -> Result<ProfileResponse> {
let profile_started_at = Instant::now();
let processed = self.process(input).await?;
@@ -691,15 +692,15 @@ fn dimensions_from_signal(signal: &ToolResultSignal) -> CodingAgentDimensions {
}
}
-fn apply_overrides(signal: &ToolResultSignal) -> Option<CascadeTier> {
+fn apply_overrides(signal: &ToolResultSignal) -> Option<StageRouterTier> {
if signal.severity >= SEVERITY_CRITICAL {
- return Some(CascadeTier::Strong);
+ return Some(StageRouterTier::Capable);
}
if signal.tests_passed
&& signal.turn_depth >= CLEAN_TESTS_MIN_TURN_DEPTH
&& signal.write_count <= CLEAN_TESTS_MAX_WRITES
{
- return Some(CascadeTier::Weak);
+ return Some(StageRouterTier::Efficient);
}
None
}
@@ -720,21 +721,21 @@ fn ratio(numerator: u32, denominator: u32) -> f64 {
}
}
-struct CascadeTierClassifier {
- config: CascadeClassifierConfig,
+struct StageRouterTierClassifier {
+ config: StageRouterClassifierConfig,
client: reqwest::Client,
disable_reasoning: bool,
}
-impl CascadeTierClassifier {
- fn new(config: &CascadeClassifierConfig) -> Result<Self> {
+impl StageRouterTierClassifier {
+ fn new(config: &StageRouterClassifierConfig) -> Result<Self> {
config.validate()?;
let client = reqwest::Client::builder()
.timeout(Duration::from_secs_f64(config.timeout_secs))
.build()
.map_err(|error| {
SwitchyardError::InvalidConfig(format!(
- "failed to build cascade classifier HTTP client: {error}"
+ "failed to build stage_router classifier HTTP client: {error}"
))
})?;
Ok(Self {
@@ -749,7 +750,7 @@ impl CascadeTierClassifier {
request: &ChatRequest,
signal: &ToolResultSignal,
stats: Option<&StatsAccumulator>,
- ) -> Option<CascadeTier> {
+ ) -> Option<StageRouterTier> {
let started_at = Instant::now();
let response = match self
.client
@@ -761,7 +762,7 @@ impl CascadeTierClassifier {
{
Ok(response) => response,
Err(error) => {
- tracing::warn!(error = %error, "cascade classifier call failed; falling open");
+ tracing::warn!(error = %error, "stage_router classifier call failed; falling open");
record_classifier_error(stats, self.config.model.as_str());
return None;
}
@@ -770,7 +771,7 @@ impl CascadeTierClassifier {
if !response.status().is_success() {
tracing::warn!(
status = %response.status(),
- "cascade classifier returned error status; falling open"
+ "stage_router classifier returned error status; falling open"
);
record_classifier_error(stats, self.config.model.as_str());
return None;
@@ -779,7 +780,7 @@ impl CascadeTierClassifier {
let body = match response.json::<Value>().await {
Ok(body) => body,
Err(error) => {
- tracing::warn!(error = %error, "cascade classifier returned invalid JSON; falling open");
+ tracing::warn!(error = %error, "stage_router classifier returned invalid JSON; falling open");
record_classifier_error(stats, self.config.model.as_str());
return None;
}
@@ -828,7 +829,7 @@ fn record_classifier_usage(
) {
if let Some(stats) = stats {
if let Err(error) = stats.record_classifier_usage(model, usage, Some(latency_ms)) {
- tracing::debug!(error = %error, "failed to record cascade classifier usage");
+ tracing::debug!(error = %error, "failed to record stage_router classifier usage");
}
}
}
@@ -836,12 +837,12 @@ fn record_classifier_usage(
fn record_classifier_error(stats: Option<&StatsAccumulator>, model: &str) {
if let Some(stats) = stats {
if let Err(error) = stats.record_classifier_error(model) {
- tracing::debug!(error = %error, "failed to record cascade classifier error");
+ tracing::debug!(error = %error, "failed to record stage_router classifier error");
}
}
}
-fn parse_classifier_tier(body: &Value) -> Option<CascadeTier> {
+fn parse_classifier_tier(body: &Value) -> Option<StageRouterTier> {
let content = body
.get("choices")?
.as_array()?
@@ -851,8 +852,8 @@ fn parse_classifier_tier(body: &Value) -> Option<CascadeTier> {
.as_str()?;
let payload = serde_json::from_str::<Value>(content).ok()?;
match payload.get("tier").and_then(Value::as_str) {
- Some("strong") => Some(CascadeTier::Strong),
- Some("weak") => Some(CascadeTier::Weak),
+ Some("capable") => Some(StageRouterTier::Capable),
+ Some("efficient") => Some(StageRouterTier::Efficient),
_ => None,
}
}
@@ -879,11 +880,11 @@ fn summarise_signal(
);
let recent_messages = recent_messages(request, recent_window);
if recent_messages.is_empty() {
- return format!("Decide STRONG or WEAK for the next call. {state_line}");
+ return format!("Decide CAPABLE or EFFICIENT for the next call. {state_line}");
}
let mut lines = vec![
- "Decide STRONG or WEAK for the next call.".to_string(),
+ "Decide CAPABLE or EFFICIENT for the next call.".to_string(),
state_line,
"Recent turns (most recent last):".to_string(),
];
@@ -983,8 +984,8 @@ fn model_accepts_reasoning_hint(model: &str) -> bool {
.any(|tag| lowered.contains(tag))
}
-fn default_picker() -> CascadePickerMode {
- CascadePickerMode::CascadeStrongDefault
+fn default_picker() -> StageRouterPickerMode {
+ StageRouterPickerMode::CapableFirst
}
fn default_confidence_threshold() -> f64 {
@@ -1117,23 +1118,28 @@ mod tests {
}
fn profile(
- strong: LlmTarget,
- weak: LlmTarget,
- picker: CascadePickerMode,
+ capable: LlmTarget,
+ efficient: LlmTarget,
+ picker: StageRouterPickerMode,
confidence_threshold: f64,
- weak_actions: Vec<BackendAction>,
- strong_actions: Vec<BackendAction>,
- ) -> Result<(CascadeProfile, Arc<Mutex<Vec<ObservedCall>>>)> {
+ efficient_actions: Vec<BackendAction>,
+ capable_actions: Vec<BackendAction>,
+ ) -> Result<(StageRouterProfile, Arc<Mutex<Vec<ObservedCall>>>)> {
let calls = Arc::new(Mutex::new(Vec::new()));
- let profile = CascadeProfile {
- strong_backend: target_backend(
- &strong,
- "strong-backend",
+ let profile = StageRouterProfile {
+ capable_backend: target_backend(
+ &capable,
+ "capable-backend",
calls.clone(),
- strong_actions,
+ capable_actions,
),
- weak_backend: target_backend(&weak, "weak-backend", calls.clone(), weak_actions),
- fallback_target_on_evict: strong.id.clone(),
+ efficient_backend: target_backend(
+ &efficient,
+ "efficient-backend",
+ calls.clone(),
+ efficient_actions,
+ ),
+ fallback_target_on_evict: capable.id.clone(),
picker,
confidence_threshold,
signal_recent_window: DEFAULT_RECENT_WINDOW,
@@ -1145,11 +1151,11 @@ mod tests {
}
#[tokio::test]
- async fn cascade_routes_critical_tool_errors_to_strong() -> Result<()> {
+ async fn stage_router_routes_critical_tool_errors_to_capable() -> Result<()> {
let (profile, calls) = profile(
- target("strong", "frontier/model")?,
- target("weak", "cheap/model")?,
- CascadePickerMode::CascadeWeakDefault,
+ target("capable", "frontier/model")?,
+ target("efficient", "cheap/model")?,
+ StageRouterPickerMode::EfficientFirst,
0.7,
vec![BackendAction::Ok],
vec![BackendAction::Ok],
@@ -1157,7 +1163,7 @@ mod tests {
let response = profile
.run(profile_input(ChatRequest::openai_chat(json!({
- "model": "smart-cascade",
+ "model": "smart-stage-router",
"messages": [
{"role": "assistant", "tool_calls": [{
"type": "function",
@@ -1176,21 +1182,21 @@ mod tests {
routing_metadata.selected_model.as_deref(),
Some("frontier/model")
);
- assert_eq!(routing_metadata.selected_tier.as_deref(), Some("strong"));
+ assert_eq!(routing_metadata.selected_tier.as_deref(), Some("capable"));
assert_eq!(routing_metadata.confidence, Some(1.0));
assert_eq!(
routing_metadata.router_version.as_deref(),
- Some("cascade:v1")
+ Some("stage_router:v1")
);
let response = response.response;
let calls = observed(&calls)?;
assert_eq!(calls.len(), 1);
- assert_eq!(calls[0].backend, "strong-backend");
+ assert_eq!(calls[0].backend, "capable-backend");
assert_eq!(calls[0].body["model"], "frontier/model");
match response {
ChatResponse::OpenAiCompletion(body) => {
- assert_eq!(body.body()["served_by"], "strong-backend");
+ assert_eq!(body.body()["served_by"], "capable-backend");
}
_ => return Err(SwitchyardError::Other("unexpected response shape".into())),
}
@@ -1199,7 +1205,7 @@ mod tests {
assert_eq!(
snapshot
.routing_decisions
- .get("cascade")
+ .get("stage_router")
.and_then(|sources| sources.get("override")),
Some(&1)
);
@@ -1208,17 +1214,17 @@ mod tests {
.models
.get("frontier/model")
.and_then(|model| model.tier.as_deref()),
- Some("strong")
+ Some("capable")
);
Ok(())
}
#[tokio::test]
- async fn cascade_threshold_zero_accepts_neutral_scorer_as_weak() -> Result<()> {
+ async fn stage_router_threshold_zero_accepts_neutral_scorer_as_efficient() -> Result<()> {
let (profile, calls) = profile(
- target("strong", "frontier/model")?,
- target("weak", "cheap/model")?,
- CascadePickerMode::CascadeStrongDefault,
+ target("capable", "frontier/model")?,
+ target("efficient", "cheap/model")?,
+ StageRouterPickerMode::CapableFirst,
0.0,
vec![BackendAction::Ok],
vec![BackendAction::Ok],
@@ -1226,24 +1232,27 @@ mod tests {
let processed = profile
.process(profile_input(ChatRequest::openai_chat(json!({
- "model": "smart-cascade",
+ "model": "smart-stage-router",
"messages": [{"role": "user", "content": "continue"}],
}))))
.await?;
- assert_eq!(processed.decision.tier, CascadeTier::Weak);
- assert_eq!(processed.decision.source, CascadeDecisionSource::Dimensions);
+ assert_eq!(processed.decision.tier, StageRouterTier::Efficient);
+ assert_eq!(
+ processed.decision.source,
+ StageRouterDecisionSource::Dimensions
+ );
assert_eq!(processed.profile_input.request.model(), Some("cheap/model"));
assert!(observed(&calls)?.is_empty());
Ok(())
}
#[tokio::test]
- async fn cascade_retries_configured_fallback_after_context_overflow() -> Result<()> {
+ async fn stage_router_retries_configured_fallback_after_context_overflow() -> Result<()> {
let (profile, calls) = profile(
- target("strong", "frontier/model")?,
- target("weak", "cheap/model")?,
- CascadePickerMode::CascadeWeakDefault,
+ target("capable", "frontier/model")?,
+ target("efficient", "cheap/model")?,
+ StageRouterPickerMode::EfficientFirst,
0.7,
vec![BackendAction::ContextOverflow],
vec![BackendAction::Ok],
@@ -1251,7 +1260,7 @@ mod tests {
let response = profile
.run(profile_input(ChatRequest::openai_chat(json!({
- "model": "smart-cascade",
+ "model": "smart-stage-router",
"messages": [{"role": "user", "content": "continue"}],
}))))
.await?;
@@ -1264,7 +1273,7 @@ mod tests {
routing_metadata.selected_model.as_deref(),
Some("frontier/model")
);
- assert_eq!(routing_metadata.selected_tier.as_deref(), Some("strong"));
+ assert_eq!(routing_metadata.selected_tier.as_deref(), Some("capable"));
assert!(routing_metadata
.rationale
.as_deref()
@@ -1273,13 +1282,13 @@ mod tests {
let calls = observed(&calls)?;
assert_eq!(calls.len(), 2);
- assert_eq!(calls[0].backend, "weak-backend");
+ assert_eq!(calls[0].backend, "efficient-backend");
assert_eq!(calls[0].body["model"], "cheap/model");
- assert_eq!(calls[1].backend, "strong-backend");
+ assert_eq!(calls[1].backend, "capable-backend");
assert_eq!(calls[1].body["model"], "frontier/model");
match response {
ChatResponse::OpenAiCompletion(body) => {
- assert_eq!(body.body()["served_by"], "strong-backend");
+ assert_eq!(body.body()["served_by"], "capable-backend");
}
_ => return Err(SwitchyardError::Other("unexpected response shape".into())),
}
@@ -1291,12 +1300,12 @@ mod tests {
.models
.get("frontier/model")
.and_then(|model| model.tier.as_deref()),
- Some("strong")
+ Some("capable")
);
assert_eq!(
snapshot
.routing_decisions
- .get("cascade")
+ .get("stage_router")
.and_then(|sources| sources.get("fall_open")),
Some(&1)
);
@@ -1304,12 +1313,12 @@ mod tests {
}
#[test]
- fn cascade_config_rejects_unknown_fallback_target() -> Result<()> {
- let config = CascadeProfileConfig {
- strong: target("strong", "frontier/model")?,
- weak: target("weak", "cheap/model")?,
+ fn stage_router_config_rejects_unknown_fallback_target() -> Result<()> {
+ let config = StageRouterProfileConfig {
+ capable: target("capable", "frontier/model")?,
+ efficient: target("efficient", "cheap/model")?,
fallback_target_on_evict: LlmTargetId::new("ghost")?,
- picker: CascadePickerMode::CascadeStrongDefault,
+ picker: StageRouterPickerMode::CapableFirst,
confidence_threshold: 0.7,
signal_recent_window: DEFAULT_RECENT_WINDOW,
classifier: None,
@@ -1327,7 +1336,7 @@ mod tests {
#[test]
fn classifier_request_uses_reasoning_hint_for_vllm_models() -> Result<()> {
- let classifier = CascadeTierClassifier::new(&CascadeClassifierConfig {
+ let classifier = StageRouterTierClassifier::new(&StageRouterClassifierConfig {
model: "nvidia/deepseek-ai/deepseek-v4-flash".to_string(),
api_key: "test-key".to_string(),
base_url: None,
@@ -1339,7 +1348,7 @@ mod tests {
let body = classifier.request_body(
&ChatRequest::openai_chat(json!({
- "model": "smart-cascade",
+ "model": "smart-stage-router",
"messages": [{"role": "user", "content": "hi"}],
})),
&ToolResultSignal::default(),
diff --git a/crates/switchyard-components-v2/src/profiles/stage_router/prompts/classifier.md b/crates/switchyard-components-v2/src/profiles/stage_router/prompts/classifier.md
new file mode 100644
index 000000000..25f570fcf
--- /dev/null
+++ b/crates/switchyard-components-v2/src/profiles/stage_router/prompts/classifier.md
@@ -0,0 +1,5 @@
+You are a routing classifier inside an agentic coding stage-router. Given a compact summary of the agent's recent tool activity, decide whether the next model call should go to the CAPABLE tier (frontier, expensive) or the EFFICIENT tier (cheap, less powerful).
+
+Respond with strict JSON: {"tier": "capable"} or {"tier": "efficient"}.
+
+Pick EFFICIENT when the agent shows concrete, low-friction progress (writes landing, tests passing, edits without errors). Pick CAPABLE when the agent is stalled, hitting errors, or facing a task likely to require careful reasoning.
diff --git a/crates/switchyard-components-v2/tests/config.rs b/crates/switchyard-components-v2/tests/config.rs
index b91875a23..9b1b4c11c 100644
--- a/crates/switchyard-components-v2/tests/config.rs
+++ b/crates/switchyard-components-v2/tests/config.rs
@@ -39,12 +39,12 @@ profiles:
direct:
type: passthrough
target: direct-weak
- smart-cascade:
- type: cascade
- strong: strong
- weak: weak
+ smart-stage-router:
+ type: stage_router
+ capable: strong
+ efficient: weak
fallback_target_on_evict: strong
- picker: cascade_strong_default
+ picker: capable_first
confidence_threshold: 0.7
health-aware:
type: latency-service
@@ -56,12 +56,12 @@ profiles:
weak: weak
classifier: classifier
profile_name: coding_agent
- cascade:
- type: cascade
- strong: strong
- weak: weak
+ stage_router:
+ type: stage_router
+ capable: strong
+ efficient: weak
fallback_target_on_evict: strong
- picker: cascade_strong_default
+ picker: capable_first
classifier:
model: nvidia/nvidia/nemotron-nano-9b-v2
api_key: ${NVIDIA_API_KEY}
@@ -110,8 +110,8 @@ fn yaml_config_resolves_endpoints_targets_and_profile_owned_configs() -> Result<
Some("passthrough")
);
assert_eq!(
- plan.profile_type(&ProfileId::new("smart-cascade")?),
- Some("cascade")
+ plan.profile_type(&ProfileId::new("smart-stage-router")?),
+ Some("stage_router")
);
assert_eq!(
plan.profile_type(&ProfileId::new("health-aware")?),
@@ -122,8 +122,8 @@ fn yaml_config_resolves_endpoints_targets_and_profile_owned_configs() -> Result<
Some("llm-routing")
);
assert_eq!(
- plan.profile_type(&ProfileId::new("cascade")?),
- Some("cascade")
+ plan.profile_type(&ProfileId::new("stage_router")?),
+ Some("stage_router")
);
let profiles = plan.build_profiles()?;
@@ -483,18 +483,18 @@ fn profile_config_plan_builds_runtime_profiles() -> Result<()> {
drop(direct);
assert_eq!(profiles.len(), 6);
assert!(profiles.contains_key(&ProfileId::new("direct")?));
- assert!(profiles.contains_key(&ProfileId::new("smart-cascade")?));
+ assert!(profiles.contains_key(&ProfileId::new("smart-stage-router")?));
assert!(profiles.contains_key(&ProfileId::new("health-aware")?));
assert!(profiles.contains_key(&ProfileId::new("llm")?));
- assert!(profiles.contains_key(&ProfileId::new("cascade")?));
+ assert!(profiles.contains_key(&ProfileId::new("stage_router")?));
assert!(profiles.contains_key(&ProfileId::new("bench")?));
Ok(())
}
-// Components-v2 cascade config should reject route-era/top-level classifier
+// Components-v2 stage_router config should reject route-era/top-level classifier
// knobs instead of carrying compatibility behavior forward.
#[test]
-fn cascade_rejects_top_level_classifier_knobs() -> Result<()> {
+fn stage_router_rejects_top_level_classifier_knobs() -> Result<()> {
let input = r#"
targets:
strong:
@@ -505,9 +505,9 @@ targets:
format: openai
profiles:
stale:
- type: cascade
- strong: strong
- weak: weak
+ type: stage_router
+ capable: strong
+ efficient: weak
fallback_target_on_evict: strong
classifier_max_tokens: 64
"#;
@@ -522,9 +522,9 @@ profiles:
Ok(())
}
-// Invalid cascade picker names fail during profile config resolution.
+// Invalid stage_router picker names fail during profile config resolution.
#[test]
-fn cascade_resolve_rejects_unknown_picker() -> Result<()> {
+fn stage_router_resolve_rejects_unknown_picker() -> Result<()> {
let input = r#"
targets:
strong:
@@ -535,9 +535,9 @@ targets:
format: openai
profiles:
bad:
- type: cascade
- strong: strong
- weak: weak
+ type: stage_router
+ capable: strong
+ efficient: weak
fallback_target_on_evict: strong
picker: not-a-picker
"#;
diff --git a/crates/switchyard-components-v2/tests/cascade_profile.rs b/crates/switchyard-components-v2/tests/stage_router_profile.rs
similarity index 87%
rename from crates/switchyard-components-v2/tests/cascade_profile.rs
rename to crates/switchyard-components-v2/tests/stage_router_profile.rs
index b3ab30b42..7f57d34fb 100644
--- a/crates/switchyard-components-v2/tests/cascade_profile.rs
+++ b/crates/switchyard-components-v2/tests/stage_router_profile.rs
@@ -1,7 +1,7 @@
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0
-//! Public API tests for the components-v2 cascade profile config.
+//! Public API tests for the components-v2 stage_router profile config.
use std::io::{Read, Write};
use std::net::{SocketAddr, TcpListener, TcpStream};
@@ -12,9 +12,9 @@ use std::time::Duration;
use serde_json::{json, Value};
use switchyard_components_v2::{
- profile_stats_accumulator, CascadeClassifierConfig, CascadeDecisionSource, CascadePickerMode,
- CascadeProfileConfig, CascadeTier, Profile, ProfileConfig, ProfileHooks, ProfileInput,
- RequestMetadata,
+ profile_stats_accumulator, Profile, ProfileConfig, ProfileHooks, ProfileInput, RequestMetadata,
+ StageRouterClassifierConfig, StageRouterDecisionSource, StageRouterPickerMode,
+ StageRouterProfileConfig, StageRouterTier,
};
use switchyard_core::{
BackendFormat, ChatRequest, LlmTarget, LlmTargetId, ModelId, Result, SwitchyardError,
@@ -181,7 +181,7 @@ fn response_for(
return MockResponse::Json(
200,
json!({
- "id": "chatcmpl-cascade-classifier",
+ "id": "chatcmpl-stage_router-classifier",
"object": "chat.completion",
"model": request.body["model"],
"choices": [{
@@ -206,7 +206,7 @@ fn response_for(
MockResponse::Json(
200,
json!({
- "id": "chatcmpl-cascade-backend",
+ "id": "chatcmpl-stage_router-backend",
"object": "chat.completion",
"model": request.body["model"],
"choices": [{"message": {"role": "assistant", "content": "ok"}}],
@@ -252,15 +252,23 @@ fn target(id: &str, model: &str, base_url: &str) -> Result<LlmTarget> {
Ok(target)
}
-fn config(base_url: &str) -> Result<CascadeProfileConfig> {
- Ok(CascadeProfileConfig {
- strong: target("strong", "frontier/model", &format!("{base_url}/strong/v1"))?,
- weak: target("weak", "cheap/model", &format!("{base_url}/weak/v1"))?,
- fallback_target_on_evict: LlmTargetId::new("strong")?,
- picker: CascadePickerMode::CascadeStrongDefault,
+fn config(base_url: &str) -> Result<StageRouterProfileConfig> {
+ Ok(StageRouterProfileConfig {
+ capable: target(
+ "capable",
+ "frontier/model",
+ &format!("{base_url}/capable/v1"),
+ )?,
+ efficient: target(
+ "efficient",
+ "cheap/model",
+ &format!("{base_url}/efficient/v1"),
+ )?,
+ fallback_target_on_evict: LlmTargetId::new("capable")?,
+ picker: StageRouterPickerMode::CapableFirst,
confidence_threshold: 0.7,
signal_recent_window: 3,
- classifier: Some(CascadeClassifierConfig {
+ classifier: Some(StageRouterClassifierConfig {
model: "classifier/model".to_string(),
api_key: "test-key".to_string(),
base_url: Some(format!("{base_url}/classifier/v1")),
@@ -282,14 +290,14 @@ fn profile_input(request: ChatRequest) -> ProfileInput {
fn request() -> ProfileInput {
profile_input(ChatRequest::openai_chat(json!({
- "model": "client/cascade",
+ "model": "client/stage_router",
"messages": [{"role": "user", "content": "hello"}],
})))
}
fn request_with_tool_result(tool_name: &str, content: &str) -> ProfileInput {
profile_input(ChatRequest::openai_chat(json!({
- "model": "client/cascade",
+ "model": "client/stage_router",
"messages": [
{"role": "user", "content": "work on this"},
{"role": "assistant", "tool_calls": [{"function": {"name": tool_name}}]},
@@ -308,7 +316,7 @@ fn stats_test_lock() -> &'static AsyncMutex<()> {
}
#[tokio::test]
-async fn critical_severity_overrides_to_strong_without_classifier() -> Result<()> {
+async fn critical_severity_overrides_to_capable_without_classifier() -> Result<()> {
let server = MockOpenAiServer::spawn(None, 200)?;
let mut config = config(&server.base_url())?;
config.classifier = None;
@@ -322,14 +330,17 @@ async fn critical_severity_overrides_to_strong_without_classifier() -> Result<()
processed.profile_input.request.model(),
Some("frontier/model")
);
- assert_eq!(processed.decision.tier, CascadeTier::Strong);
- assert_eq!(processed.decision.source, CascadeDecisionSource::Override);
+ assert_eq!(processed.decision.tier, StageRouterTier::Capable);
+ assert_eq!(
+ processed.decision.source,
+ StageRouterDecisionSource::Override
+ );
assert!(server.requests()?.is_empty());
Ok(())
}
#[tokio::test]
-async fn negative_score_routes_to_weak_without_classifier() -> Result<()> {
+async fn negative_score_routes_to_efficient_without_classifier() -> Result<()> {
let server = MockOpenAiServer::spawn(None, 200)?;
let mut config = config(&server.base_url())?;
config.classifier = None;
@@ -341,8 +352,11 @@ async fn negative_score_routes_to_weak_without_classifier() -> Result<()> {
.await?;
assert_eq!(processed.profile_input.request.model(), Some("cheap/model"));
- assert_eq!(processed.decision.tier, CascadeTier::Weak);
- assert_eq!(processed.decision.source, CascadeDecisionSource::Dimensions);
+ assert_eq!(processed.decision.tier, StageRouterTier::Efficient);
+ assert_eq!(
+ processed.decision.source,
+ StageRouterDecisionSource::Dimensions
+ );
Ok(())
}
@@ -350,16 +364,16 @@ async fn negative_score_routes_to_weak_without_classifier() -> Result<()> {
async fn low_confidence_uses_classifier_when_configured() -> Result<()> {
let _guard = stats_test_lock().lock().await;
profile_stats_accumulator().reset()?;
- let server = MockOpenAiServer::spawn(Some(tier_content("weak")), 200)?;
+ let server = MockOpenAiServer::spawn(Some(tier_content("efficient")), 200)?;
let profile = config(&server.base_url())?.build()?;
let processed = profile.process(request()).await?;
assert_eq!(processed.profile_input.request.model(), Some("cheap/model"));
- assert_eq!(processed.decision.tier, CascadeTier::Weak);
+ assert_eq!(processed.decision.tier, StageRouterTier::Efficient);
assert_eq!(
processed.decision.source,
- CascadeDecisionSource::LlmClassifier
+ StageRouterDecisionSource::LlmClassifier
);
let requests = server.requests()?;
assert_eq!(requests.len(), 1);
@@ -368,7 +382,7 @@ async fn low_confidence_uses_classifier_when_configured() -> Result<()> {
assert!(classifier_body["messages"][0]["content"]
.as_str()
.is_some_and(
- |content| content.contains("routing classifier inside an agentic coding cascade")
+ |content| content.contains("routing classifier inside an agentic coding stage-router")
));
assert_eq!(classifier_body["response_format"]["type"], "json_object");
Ok(())
@@ -378,14 +392,14 @@ async fn low_confidence_uses_classifier_when_configured() -> Result<()> {
async fn yaml_overrides_classifier_prompt_and_max_tokens() -> Result<()> {
let _guard = stats_test_lock().lock().await;
profile_stats_accumulator().reset()?;
- let server = MockOpenAiServer::spawn(Some(tier_content("weak")), 200)?;
+ let server = MockOpenAiServer::spawn(Some(tier_content("efficient")), 200)?;
let mut config = config(&server.base_url())?;
let classifier = config
.classifier
.as_mut()
.ok_or_else(|| SwitchyardError::Other("classifier config missing".to_string()))?;
classifier.max_tokens = 64;
- classifier.system_prompt = Some("Pick a cascade tier.".to_string());
+ classifier.system_prompt = Some("Pick a stage_router tier.".to_string());
let profile = config.build()?;
let processed = profile.process(request()).await?;
@@ -396,7 +410,7 @@ async fn yaml_overrides_classifier_prompt_and_max_tokens() -> Result<()> {
assert_eq!(classifier_body["max_tokens"], 64);
assert_eq!(
classifier_body["messages"][0]["content"],
- "Pick a cascade tier."
+ "Pick a stage_router tier."
);
Ok(())
}
@@ -442,7 +456,10 @@ async fn malformed_classifier_falls_open_to_default() -> Result<()> {
processed.profile_input.request.model(),
Some("frontier/model")
);
- assert_eq!(processed.decision.source, CascadeDecisionSource::FallOpen);
+ assert_eq!(
+ processed.decision.source,
+ StageRouterDecisionSource::FallOpen
+ );
let stats = profile_stats_accumulator().snapshot()?;
assert_eq!(stats.classifier.total_errors, 1);
Ok(())
@@ -461,7 +478,10 @@ async fn non_json_classifier_falls_open_and_records_error() -> Result<()> {
processed.profile_input.request.model(),
Some("frontier/model")
);
- assert_eq!(processed.decision.source, CascadeDecisionSource::FallOpen);
+ assert_eq!(
+ processed.decision.source,
+ StageRouterDecisionSource::FallOpen
+ );
let stats = profile_stats_accumulator().snapshot()?;
assert_eq!(stats.classifier.total_errors, 1);
Ok(())
@@ -471,7 +491,7 @@ async fn non_json_classifier_falls_open_and_records_error() -> Result<()> {
async fn run_records_backend_and_classifier_stats() -> Result<()> {
let _guard = stats_test_lock().lock().await;
profile_stats_accumulator().reset()?;
- let server = MockOpenAiServer::spawn(Some(tier_content("strong")), 200)?;
+ let server = MockOpenAiServer::spawn(Some(tier_content("capable")), 200)?;
let profile = config(&server.base_url())?.build()?;
let response = profile.run(request()).await?;
@@ -484,7 +504,7 @@ async fn run_records_backend_and_classifier_stats() -> Result<()> {
routing_metadata.selected_model.as_deref(),
Some("frontier/model")
);
- assert_eq!(routing_metadata.selected_tier.as_deref(), Some("strong"));
+ assert_eq!(routing_metadata.selected_tier.as_deref(), Some("capable"));
assert_eq!(routing_metadata.confidence, None);
assert!(routing_metadata
.rationale
@@ -497,11 +517,11 @@ async fn run_records_backend_and_classifier_stats() -> Result<()> {
let requests = server.requests()?;
assert_eq!(requests.len(), 2);
assert_eq!(requests[0].path, "/classifier/v1/chat/completions");
- assert_eq!(requests[1].path, "/strong/v1/chat/completions");
+ assert_eq!(requests[1].path, "/capable/v1/chat/completions");
let stats = profile_stats_accumulator().snapshot()?;
assert_eq!(stats.classifier.total_requests, 1);
assert!(stats.models.contains_key("frontier/model"));
- assert!(stats.tiers.contains_key("strong"));
+ assert!(stats.tiers.contains_key("capable"));
Ok(())
}
@@ -509,7 +529,7 @@ async fn run_records_backend_and_classifier_stats() -> Result<()> {
async fn run_records_selected_backend_failure() -> Result<()> {
let _guard = stats_test_lock().lock().await;
profile_stats_accumulator().reset()?;
- let server = MockOpenAiServer::spawn(Some(tier_content("strong")), 503)?;
+ let server = MockOpenAiServer::spawn(Some(tier_content("capable")), 503)?;
let profile = config(&server.base_url())?.build()?;
let error =
diff --git a/crates/switchyard-components/src/dimension_collector/response/mod.rs b/crates/switchyard-components/src/dimension_collector/response/mod.rs
index 70c274de2..756a3323e 100644
--- a/crates/switchyard-components/src/dimension_collector/response/mod.rs
+++ b/crates/switchyard-components/src/dimension_collector/response/mod.rs
@@ -22,7 +22,7 @@ use switchyard_core::ChatResponse;
///
/// Stamped into `ProxyContext.extensions` by the
/// `ResponseSignalCollector` adapter. Empty `flags` means all checks
-/// passed — the response is considered acceptable from the cascade
+/// passed — the response is considered acceptable from the stage-router
/// router's reactive-escalation viewpoint.
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct ResponseSignals {
@@ -32,7 +32,7 @@ pub struct ResponseSignals {
impl ResponseSignals {
/// Returns `true` when at least one check flagged the response.
///
- /// Cascade routers consume this as the per-attempt acceptability
+ /// StageRouter routers consume this as the per-attempt acceptability
/// gate; a `true` here triggers escalation to the next tier.
pub fn has_failures(&self) -> bool {
!self.flags.is_empty()
diff --git a/crates/switchyard-components/src/dimension_collector/tool_signals.rs b/crates/switchyard-components/src/dimension_collector/tool_signals.rs
index 6828cb3db..7fbbf7f23 100644
--- a/crates/switchyard-components/src/dimension_collector/tool_signals.rs
+++ b/crates/switchyard-components/src/dimension_collector/tool_signals.rs
@@ -7,7 +7,7 @@
//! alongside the 15 prompt-text scorers: it walks the `messages[]` /
//! `input[]` array of the incoming request, finds tool-execution results,
//! pattern-matches their text against a curated error table, and aggregates
-//! conversation-history metrics that the cascade pickers need.
+//! conversation-history metrics that the stage_router pickers need.
//!
//! All logic is pure and deterministic — no I/O, no shared state.
@@ -133,7 +133,7 @@ static BASH_READ_PATTERNS: &[&str] = &[
static READ_TOOL_NAMES: &[&str] = &["read", "view"];
// Planning / scratchpad tool calls. Used by Opus as a struggle indicator
-// in the strong-default picker direction.
+// in the capable-first picker direction.
// `update_plan` is codex's equivalent of `todowrite`.
static PLAN_TOOL_NAMES: &[&str] = &["todowrite", "todo_write", "todo", "update_plan"];
@@ -142,7 +142,7 @@ static PLAN_TOOL_NAMES: &[&str] = &["todowrite", "todo_write", "todo", "update_p
// are seen on some OpenAI-derived harnesses.
static BASH_TOOL_NAMES: &[&str] = &["bash", "shell_command", "shell", "local_shell_call"];
-// Prefer false negatives: tests_passed routes the picker to WEAK, so a false
+// Prefer false negatives: tests_passed routes the picker to EFFICIENT, so a false
// positive would drop tier on an unfinished task.
static TEST_PASS_PHRASES: &[&str] = &[
" passed",
@@ -178,7 +178,7 @@ pub const DEFAULT_RECENT_WINDOW: usize = 3;
// ─── output type ─────────────────────────────────────────────────────────────
-/// Tool-execution signals stamped on `ProxyContext`. Read by cascade pickers
+/// Tool-execution signals stamped on `ProxyContext`. Read by stage_router pickers
/// via [`crate::get_tool_result_signal`].
#[derive(Clone, Debug, Default)]
pub struct ToolResultSignal {
@@ -193,7 +193,7 @@ pub struct ToolResultSignal {
/// Read-type calls (Read tool + read-like Bash). Used by the build-pit gate.
pub read_count: u32,
/// TodoWrite tool calls. Strong fail predictor for Opus; used by the
- /// `cascade_strong_default` drop-to-weak gate.
+ /// `capable_first` drop-to-weak gate.
pub todowrite_count: u32,
/// Edit-type calls within the last [`RECENT_WINDOW`] tool calls.
pub recent_edit_count: u32,
diff --git a/crates/switchyard-components/src/response_processors/response_signals.rs b/crates/switchyard-components/src/response_processors/response_signals.rs
index b210bc3b0..d6e3002cb 100644
--- a/crates/switchyard-components/src/response_processors/response_signals.rs
+++ b/crates/switchyard-components/src/response_processors/response_signals.rs
@@ -6,7 +6,7 @@
//! Thin adapter around
//! [`crate::dimension_collector::response::extract_response_signals`]. Stamps
//! the resulting [`ResponseSignals`] into `ProxyContext` so downstream
-//! cascade / escalation logic can read structured response-quality
+//! stage_router / escalation logic can read structured response-quality
//! flags without re-parsing the wire body.
use switchyard_core::{ChatResponse, ProxyContext, Result};
diff --git a/crates/switchyard-components/src/stats/accumulator.rs b/crates/switchyard-components/src/stats/accumulator.rs
index 1f1301d7d..ee2f72602 100644
--- a/crates/switchyard-components/src/stats/accumulator.rs
+++ b/crates/switchyard-components/src/stats/accumulator.rs
@@ -228,7 +228,7 @@ impl StatsAccumulator {
///
/// The classifier's per-request call is not part of the routed-backend
/// chain and must stay out of `by_model` — otherwise the default TB-lite
- /// config (classifier model == weak-tier model) double-counts the spend.
+ /// config (classifier model == efficient-tier model) double-counts the spend.
/// `record_classifier_usage` writes to a dedicated bucket; the snapshot
/// exposes it under `classifier.models` with its own `cost_estimate`.
pub fn record_classifier_usage(
@@ -277,8 +277,8 @@ impl StatsAccumulator {
/// Records one routing decision source for a profile family.
///
- /// This is intentionally separate from model/tier accounting: a cascade can
- /// choose `weak` because of an override, a dimensions score, an LLM-classifier
+ /// This is intentionally separate from model/tier accounting: a stage-router can
+ /// choose `efficient` because of an override, a dimensions score, an LLM-classifier
/// verdict, or a fail-open default, and those explanations are useful even
/// when they all land on the same backend model.
pub fn record_routing_decision(
diff --git a/crates/switchyard-components/src/stats/context.rs b/crates/switchyard-components/src/stats/context.rs
index 569c36b5c..1a8e7008d 100644
--- a/crates/switchyard-components/src/stats/context.rs
+++ b/crates/switchyard-components/src/stats/context.rs
@@ -65,7 +65,7 @@ pub fn selected_stats_tier(ctx: &ProxyContext) -> Option<String> {
if let Some(decision) = ctx.get::<RandomRoutingDecision>() {
return Some(decision.tier.as_str().to_string());
}
- // Fallback: Python-based pickers (e.g. cascade) stamp selected_target but
+ // Fallback: Python-based pickers (e.g. stage_router) stamp selected_target but
// don't write a typed marker — use it as the tier label so /v1/routing/stats
// populates the `tiers` field for those routes too.
ctx.selected_target().map(|t| t.as_str().to_string())
diff --git a/crates/switchyard-components/tests/stats_accumulator.rs b/crates/switchyard-components/tests/stats_accumulator.rs
index 078deebeb..9b005386d 100644
--- a/crates/switchyard-components/tests/stats_accumulator.rs
+++ b/crates/switchyard-components/tests/stats_accumulator.rs
@@ -710,23 +710,23 @@ fn reset_clears_classifier_bucket() -> Result<()> {
#[test]
fn routing_decision_counts_are_grouped_by_profile_type() -> Result<()> {
let accumulator = StatsAccumulator::new();
- accumulator.record_routing_decision("cascade", "dimensions")?;
- accumulator.record_routing_decision("cascade", "dimensions")?;
- accumulator.record_routing_decision("cascade", "llm-classifier")?;
+ accumulator.record_routing_decision("stage_router", "dimensions")?;
+ accumulator.record_routing_decision("stage_router", "dimensions")?;
+ accumulator.record_routing_decision("stage_router", "llm-classifier")?;
accumulator.record_routing_decision("latency-service", "health")?;
let snapshot = accumulator.snapshot()?;
assert_eq!(
snapshot
.routing_decisions
- .get("cascade")
+ .get("stage_router")
.and_then(|sources| sources.get("dimensions")),
Some(&2)
);
assert_eq!(
snapshot
.routing_decisions
- .get("cascade")
+ .get("stage_router")
.and_then(|sources| sources.get("llm-classifier")),
Some(&1)
);
diff --git a/crates/switchyard-py/src/component_bindings/dimension_collector.rs b/crates/switchyard-py/src/component_bindings/dimension_collector.rs
index 3d064e0f0..026d193c1 100644
--- a/crates/switchyard-py/src/component_bindings/dimension_collector.rs
+++ b/crates/switchyard-py/src/component_bindings/dimension_collector.rs
@@ -316,7 +316,7 @@ impl PyResponseSignals {
Ok(PyList::new(py, items)?.unbind())
}
- /// True when at least one check failed; cascade routers use this as
+ /// True when at least one check failed; stage_router routers use this as
/// the per-attempt acceptability gate.
fn has_failures(&self) -> bool {
self.inner.has_failures()
@@ -403,7 +403,7 @@ fn get_response_signals(ctx: PyRef<'_, PyProxyContext>) -> PyResult<Option<PyRes
/// Runs the response-side checks against an inline response body dict.
///
-/// Intended for the cascade router, which needs to evaluate
+/// Intended for the stage-router, which needs to evaluate
/// `ResponseSignals` between attempts without going through a full
/// response-side pass. Accepts the response's `.body` Python
/// dict directly; works for any wire shape because the checks are
diff --git a/crates/switchyard-server/tests/profile_migration.rs b/crates/switchyard-server/tests/profile_migration.rs
index cc973d2ee..abcb5cd35 100644
--- a/crates/switchyard-server/tests/profile_migration.rs
+++ b/crates/switchyard-server/tests/profile_migration.rs
@@ -212,7 +212,7 @@ profiles:
}
#[tokio::test]
-async fn cascade_profile_threshold_zero_uses_dimensions_signal_path() -> TestResult {
+async fn stage_router_profile_threshold_zero_uses_dimensions_signal_path() -> TestResult {
let _stats_guard = STATS_TEST_LOCK.lock().await;
reset_stats()?;
let Some(stub) = HttpStub::start(vec![StubResponse::ok()])? else {
@@ -231,12 +231,12 @@ targets:
format: openai
base_url: {base_url}
profiles:
- smart-cascade:
- type: cascade
- strong: strong
- weak: weak
+ smart-stage_router:
+ type: stage_router
+ capable: strong
+ efficient: weak
fallback_target_on_evict: strong
- picker: cascade_strong_default
+ picker: capable_first
confidence_threshold: 0.0
"#,
base_url = stub.base_url
@@ -247,7 +247,7 @@ profiles:
.oneshot(request(
"POST",
"/v1/chat/completions",
- Some(chat_body("smart-cascade")),
+ Some(chat_body("smart-stage_router")),
)?)
.await?;
assert_eq!(response.status(), StatusCode::OK);
@@ -258,17 +258,20 @@ profiles:
let stats = app.oneshot(request("GET", "/v1/stats", None)?).await?;
let stats = json_body(stats).await?;
- assert_eq!(stats["routing_decisions"]["cascade"]["dimensions"], 1);
+ assert_eq!(stats["routing_decisions"]["stage_router"]["dimensions"], 1);
assert_eq!(stats["classifier"]["total_requests"], 0);
- assert_eq!(stats["models"]["provider/weak"]["tier"], "weak");
+ assert_eq!(stats["models"]["provider/weak"]["tier"], "efficient");
Ok(())
}
#[tokio::test]
-async fn cascade_profile_threshold_one_uses_llm_classifier_path() -> TestResult {
+async fn stage_router_profile_threshold_one_uses_llm_classifier_path() -> TestResult {
let _stats_guard = STATS_TEST_LOCK.lock().await;
reset_stats()?;
- let Some(stub) = HttpStub::start(vec![StubResponse::classifier("strong"), StubResponse::ok()])?
+ let Some(stub) = HttpStub::start(vec![
+ StubResponse::classifier("capable"),
+ StubResponse::ok(),
+ ])?
else {
log_loopback_bind_skip();
return Ok(());
@@ -285,12 +288,12 @@ targets:
format: openai
base_url: {base_url}
profiles:
- smart-cascade:
- type: cascade
- strong: strong
- weak: weak
+ smart-stage_router:
+ type: stage_router
+ capable: strong
+ efficient: weak
fallback_target_on_evict: strong
- picker: cascade_strong_default
+ picker: capable_first
confidence_threshold: 1.0
classifier:
model: classifier/model
@@ -306,7 +309,7 @@ profiles:
.oneshot(request(
"POST",
"/v1/chat/completions",
- Some(chat_body("smart-cascade")),
+ Some(chat_body("smart-stage_router")),
)?)
.await?;
assert_eq!(response.status(), StatusCode::OK);
@@ -318,14 +321,17 @@ profiles:
let stats = app.oneshot(request("GET", "/v1/stats", None)?).await?;
let stats = json_body(stats).await?;
- assert_eq!(stats["routing_decisions"]["cascade"]["llm-classifier"], 1);
+ assert_eq!(
+ stats["routing_decisions"]["stage_router"]["llm-classifier"],
+ 1
+ );
assert_eq!(stats["classifier"]["total_requests"], 1);
- assert_eq!(stats["models"]["provider/strong"]["tier"], "strong");
+ assert_eq!(stats["models"]["provider/strong"]["tier"], "capable");
Ok(())
}
#[tokio::test]
-async fn cascade_profile_retries_fallback_after_context_overflow() -> TestResult {
+async fn stage_router_profile_retries_fallback_after_context_overflow() -> TestResult {
let _stats_guard = STATS_TEST_LOCK.lock().await;
reset_stats()?;
let Some(stub) = HttpStub::start(vec![StubResponse::context_overflow(), StubResponse::ok()])?
@@ -345,12 +351,12 @@ targets:
format: openai
base_url: {base_url}
profiles:
- smart-cascade:
- type: cascade
- strong: strong
- weak: weak
+ smart-stage_router:
+ type: stage_router
+ capable: strong
+ efficient: weak
fallback_target_on_evict: strong
- picker: cascade_weak_default
+ picker: efficient_first
confidence_threshold: 0.7
"#,
base_url = stub.base_url
@@ -361,7 +367,7 @@ profiles:
.oneshot(request(
"POST",
"/v1/chat/completions",
- Some(chat_body("smart-cascade")),
+ Some(chat_body("smart-stage_router")),
)?)
.await?;
assert_eq!(response.status(), StatusCode::OK);
@@ -373,8 +379,8 @@ profiles:
let stats = app.oneshot(request("GET", "/v1/stats", None)?).await?;
let stats = json_body(stats).await?;
- assert_eq!(stats["routing_decisions"]["cascade"]["fall_open"], 1);
- assert_eq!(stats["models"]["provider/strong"]["tier"], "strong");
+ assert_eq!(stats["routing_decisions"]["stage_router"]["fall_open"], 1);
+ assert_eq!(stats["models"]["provider/strong"]["tier"], "capable");
Ok(())
}
diff --git a/docs/cli_reference.md b/docs/cli_reference.md
index d12d56da2..61137b3f5 100644
--- a/docs/cli_reference.md
+++ b/docs/cli_reference.md
@@ -68,7 +68,7 @@ launchers:
| Flag | Purpose |
|---|---|
| `--model ID` | Single-model passthrough. Every request is rewritten to `model=ID` and forwarded to `--base-url`. |
-| `--routing-profiles PATH` | Deprecated path to a routing-profile YAML bundle. Each entry under `routes:` builds its own chain. Public route types are `model`, `passthrough`, `random_routing`, `cascade`, and `deterministic`. Falls back to the path persisted by `switchyard --routing-profiles PATH -- configure` when omitted. |
+| `--routing-profiles PATH` | Deprecated path to a routing-profile YAML bundle. Each entry under `routes:` builds its own chain. Public route types are `model`, `passthrough`, `random_routing`, `stage_router`, and `deterministic`. Falls back to the path persisted by `switchyard --routing-profiles PATH -- configure` when omitted. |
On the launchers, the two flags are mutually exclusive: pass one or the other, not both.
@@ -240,7 +240,7 @@ switchyard serve --config examples/profiles.yaml --port 4000
# select a profile by id (the `model` field):
curl localhost:4000/v1/chat/completions \
-H 'Content-Type: application/json' \
- -d '{"model": "smart-cascade", "messages": [{"role": "user", "content": "hi"}]}'
+ -d '{"model": "smart-stage-router", "messages": [{"role": "user", "content": "hi"}]}'
# mixed Rust/Python profile config on the same request APIs
switchyard serve --config examples/python_profile.yaml --port 4000
diff --git a/docs/core_concepts.md b/docs/core_concepts.md
index b8cbbbd53..4c6e768ac 100644
--- a/docs/core_concepts.md
+++ b/docs/core_concepts.md
@@ -63,7 +63,7 @@ another.
A profile's `type` sets the strategy. `passthrough` sends everything to one
target with no routing. `random-routing` splits traffic on a fixed probability.
-`llm-routing` asks a classifier model to pick a tier for each turn. `cascade`
+`llm-routing` asks a classifier model to pick a tier for each turn. `stage_router`
escalates from weak to strong when request signals call for it. The
[Routing Overview](routing_algorithms/overview.md) covers when to use each and
how to tune it.
@@ -77,7 +77,7 @@ how to tune it.
Session affinity, or sticky routing, pins a conversation to one tier so later
turns reuse it instead of being classified again. It belongs to `llm-routing`
-and is not a strategy of its own; random and cascade routing decide every
+and is not a strategy of its own; random and stage-router routing decide every
request on its own merits. [Sticky Routing](routing_algorithms/sticky_routing.md)
covers it in full.
diff --git a/docs/getting_started.md b/docs/getting_started.md
index f4296aef7..94665a07c 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -129,7 +129,7 @@ another route type when the routing decision needs different inputs:
|---|---|---|
| [Random Routing](routing_algorithms/random_routing.md) | You need a fixed strong/weak split for A/B tests or baselines. | `random_routing` |
| [LLM Classifier Routing](routing_algorithms/llm_classifier_routing.md) | Request content should decide whether to use `weak` or `strong`. | `deterministic` |
-| [Cascade Routing](routing_algorithms/cascade_routing.md) | Tool-result and progress signals should route most turns without an extra classifier call. | `cascade` |
+| [Stage-Router Routing](routing_algorithms/stage_router_routing.md) | Tool-result and progress signals should route most turns without an extra classifier call. | `stage_router` |
LLM classifier routes can also enable
[Session Affinity (Sticky Routing)](routing_algorithms/sticky_routing.md) to pin
@@ -232,5 +232,5 @@ uv run mypy switchyard
- [Routing Overview](routing_algorithms/overview.md): choose the right routing strategy
- [Random Routing](routing_algorithms/random_routing.md): fixed strong/weak split routing
- [LLM Classifier Routing](routing_algorithms/llm_classifier_routing.md): classifier-driven strong/weak routing
-- [Cascade Routing](routing_algorithms/cascade_routing.md): picker layers, signal dimensions, calibration
+- [Stage-Router Routing](routing_algorithms/stage_router_routing.md): picker layers, signal dimensions, calibration
- [Sticky Routing](routing_algorithms/sticky_routing.md): conversation-level route affinity
diff --git a/docs/guides/agent_launchers.md b/docs/guides/agent_launchers.md
index 0a4a139e8..50e860199 100644
--- a/docs/guides/agent_launchers.md
+++ b/docs/guides/agent_launchers.md
@@ -149,7 +149,7 @@ want the route ids to match exactly what appears in `/model`:
```yaml
routes:
claude-opus-ds:
- type: cascade
+ type: stage_router
...
claude-opus-direct:
type: model
diff --git a/docs/index.md b/docs/index.md
index 5067d45bf..c15f5a4ed 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -15,7 +15,7 @@ split across model tiers, or selected by routing policy.
| Client ingress | OpenAI Chat Completions, Anthropic Messages, and OpenAI Responses compatible endpoints. |
| Agent launchers | One-command local proxies for Claude Code, Codex, and OpenClaw. |
| Format translation | Request and response translation between supported wire formats. |
-| Routing policies | Random splits, LLM classifier routing with optional session affinity, signal-driven cascade routing, and YAML route bundles. |
+| Routing policies | Random splits, LLM classifier routing with optional session affinity, signal-driven stage-router routing, and YAML route bundles. |
| Operations | Request/token statistics and context-window fallback behavior. |
| Deployment options | Local coding-agent proxy, shared HTTP service, or embedded Python runtime. |
@@ -52,7 +52,7 @@ For source installs, non-interactive configuration, and a curl sanity check, use
- **Configure routing**
- Pick between fixed splits, classifier routing, and cascade routing, with
+ Pick between fixed splits, classifier routing, and stage-router routing, with
optional session affinity for classifier-driven conversations.
[Routing Overview](routing_algorithms/overview.md)
@@ -132,7 +132,7 @@ covered in [Routing Overview](routing_algorithms/overview.md).
|---|---|
| Fixed strong/weak traffic split for baselines or A/B tests | [Random Routing](routing_algorithms/random_routing.md) |
| Per-request strong/weak decisions from a classifier model | [LLM Classifier Routing](routing_algorithms/llm_classifier_routing.md) |
-| Signal-driven weak/strong escalation with optional classifier fallback | [Cascade Routing](routing_algorithms/cascade_routing.md) |
+| Signal-driven weak/strong escalation with optional classifier fallback | [Stage-Router Routing](routing_algorithms/stage_router_routing.md) |
| Conversation-level affinity for cache reuse | [Sticky Routing](routing_algorithms/sticky_routing.md) |
## Operations and Reference
diff --git a/docs/operations/context_window.md b/docs/operations/context_window.md
index b85f40c16..1b9e50c57 100644
--- a/docs/operations/context_window.md
+++ b/docs/operations/context_window.md
@@ -6,7 +6,7 @@ reroutes to the configured fallback target, and retries once. If the fallback
also overflows, the request fails with a 400 in the client's inbound wire
format.
-Any multi-target route (cascade, random_routing, or deterministic) supports
+Any multi-target route (stage-router, random_routing, or deterministic) supports
this. Set `fallback_target_on_evict` on the route. Single-target routes
(`type: passthrough`, `type: model`) have no alternative target, so the original
overflow propagates unchanged.
@@ -18,9 +18,9 @@ match one of the route's declared target ids:
```yaml
routes:
- my-cascade:
- type: cascade
- picker: cascade_strong_default
+ my-stage-router:
+ type: stage_router
+ picker: capable_first
fallback_target_on_evict: strong # must match strong.id or weak.id
strong:
id: strong
diff --git a/docs/routing_algorithms/cascade_routing.md b/docs/routing_algorithms/cascade_routing.md
deleted file mode 100644
index aa88ec7d8..000000000
--- a/docs/routing_algorithms/cascade_routing.md
+++ /dev/null
@@ -1,318 +0,0 @@
-# Cascade Routing
-
-Cascade routing picks one of two tiers (`weak` / `strong`) per request based on
-tool-result history stamped onto the conversation. The strong tier handles
-exploration and error recovery; the weak tier handles the mechanical
-implementation phase.
-
-The picker composes three layers in order:
-
-1. **Hard overrides**: high-confidence signal-derived shortcuts that bypass
- the scorer (critical severity, clean tests passed).
-2. **Weighted scorer**: a linear combination of normalised
- `ToolResultSignal` dimensions; produces a score in `[-1, +1]` (positive ⇒
- STRONG, negative ⇒ WEAK) and a confidence `= |score|`. Returned as the
- dimensions verdict when `confidence ≥ confidence_threshold`.
-3. **Optional LLM classifier**: consulted only when the scorer is
- ambiguous (`confidence < confidence_threshold`). Fails open to the
- picker's default tier on any error.
-
-The YAML exposes one knob (`confidence_threshold`) plus an optional
-classifier sub-block. Scorer weights and hard-override thresholds live in
-code as calibrated defaults. Research engineers override them by passing
-`weights=...` to `score()` directly.
-
----
-
-## How it fits the profile path
-
-```
-CascadeProfile
- -> extract ToolResultSignal from the request
- -> pick weak or strong
- -> rewrite request.model to the selected target model
- -> call the selected native target backend
-```
-
-`CascadeProfile` uses the Rust `ToolResultSignal` extractor for severity,
-write/edit/read counts, recent-window slices, pure-bash streak, tests-passed,
-and turn depth. The profile keeps the routing decision as typed per-call state,
-records the decision source in
-`/v1/stats.routing_decisions.cascade`, and buckets model/tier usage through the
-standard stats accumulator.
-
-If the selected backend returns a context-window overflow, the profile retries
-once against `fallback_target_on_evict`. A second overflow returns
-`ContextPoolExhausted`.
-
----
-
-## Pickers
-
-Names describe **the default tier**: the verdict returned when the scorer
-is ambiguous and no classifier verdict is available.
-
-- **`cascade_strong_default`**: STRONG is the default. WEAK only when the
- scorer is confidently negative or the classifier says WEAK. Quality-first.
-- **`cascade_weak_default`**: WEAK is the default. STRONG only when the
- scorer is confidently positive or the classifier says STRONG. Cost-first.
-
-Both share the same override path and scorer math; only the default tier
-differs.
-
-### Hard overrides
-
-Applied *before* the scorer, in this order. Any match short-circuits.
-
-| Override | Condition | Verdict |
-|---|---|---|
-| Critical severity | `signal.severity ≥ SEVERITY_CRITICAL` (1.0) | STRONG |
-| Clean completion | `signal.tests_passed AND signal.turn_depth ≥ CLEAN_TESTS_MIN_TURN_DEPTH (10) AND signal.write_count ≤ CLEAN_TESTS_MAX_WRITES (1)` | WEAK |
-
-Thresholds are module-level constants in the Rust cascade profile; retune in
-one place.
-
-### Scorer
-
-Weighted linear sum over `CodingAgentDimensions` (a normalised view of
-`ToolResultSignal`). Weights are calibrated defaults in
-`switchyard/lib/processors/cascade/scorer.py::DEFAULT_WEIGHTS`; override
-via `weights=...` for research. The raw sum is clipped to `[-1, +1]` and
-confidence is `abs(clipped)`. Magnitudes are sized so a single high-impact
-axis at maximum value (`stuck_exploring = 1.0`, `tests_passed = 1.0`, ...)
-clears the recommended threshold of `0.5` on its own.
-
-### Classifier (optional)
-
-When `confidence < confidence_threshold` and the YAML includes a
-`classifier:` sub-block, the picker calls the configured model with a
-short JSON-output prompt and asks for `{"tier": "strong" | "weak"}`. On
-timeout, malformed JSON, network failure, or any other classifier error,
-the picker falls back to its default tier (recorded as `fall_open`).
-
----
-
-## Tuning `confidence_threshold`
-
-The threshold is the **only** dial users touch. Its effect is monotone:
-raising it shifts work from the dimensions scorer to the classifier
-(or, if no classifier is configured, to the picker's default tier).
-
-!!! note "Set `0.5` explicitly"
- `0.5` is the recommended starting point and is set in the public example
- below. The implementation default still differs by configuration path:
-
- | Configuration path | Default when omitted |
- |---|---|
- | Profile config (`switchyard serve --config`) using the Rust `cascade` profile | **`0.7`** |
- | Deprecated route bundle (`--routing-profiles`) using the Python cascade profile | **`0.5`** |
-
- Set `confidence_threshold: 0.5` explicitly rather than relying on either
- schema default.
-
-| `confidence_threshold` | Include `classifier:` block? | Typical use |
-|---|---|---|
-| `0.0` | no | Cost/latency-sensitive. Every scorer verdict is accepted; no per-turn LLM call. The hard-override path still catches critical errors. |
-| `0.5` | no | Recommended starting point. A single high-impact axis clears the threshold deterministically; derived from SWE-Bench Pro calibration. |
-| `0.7` - `0.9` | yes | Classifier-assisted. Low-confidence scorer outputs go to the LLM classifier before falling back to the default tier. The Rust schema uses `0.7` when the field is omitted. |
-| `1.0` | yes (required) | Classifier-driven. Equivalent to the legacy `coding_agent` profile. |
-
-The dimensions-vs-llm-classifier split is dataset-dependent. Measure it in
-production via `routing_decisions.cascade` on `/v1/stats` rather than relying on
-priors from this doc.
-
-### Calibrating the threshold from run data
-
-The recommended `0.5` starting point was derived from SWE-Bench Pro Python-75
-calibration. To tune for a different task set or model pair, follow this
-minimum-data path.
-
-**What you need**
-
-| Run | Coverage | Purpose |
-|---|---|---|
-| Pure-strong | ~40–75 representative tasks | Baseline outcomes + signal features |
-| Pure-weak | ~20 tasks (sampled from strong results) | Counterfactual outcomes |
-
-Neither run needs to cover the full task set. A few dozen strong tasks gives
-enough outcome diversity; the weak probe only needs to cover the interesting
-quadrant candidates identified from those strong results.
-
-**How to sample the weak probe set**
-
-Stratify the pure-strong results across four quadrant candidates before running weak:
-
-| Category | Criterion | Count | Value |
-|---|---|---|---|
-| Easy + clean | Strong passes, small diff, clear spec | ~5 | Establishes SAFE floor |
-| Easy + tricky | Strong passes, subtle logic | ~5 | Catches LOSS false-positives |
-| Hard + structural | Strong fails, large multi-file diff | ~5 | HARD noise baseline |
-| Hard + localized | Strong fails, small targeted fix | ~5 | Best RESCUE signal |
-
-Sample across repos and diff sizes. Don't over-represent one project.
-
-**Building RESCUE / LOSS quadrants**
-
-From the overlap tasks (those with both strong and weak results):
-
-- `RESCUE` = strong-fail ∩ weak-pass → escalation is beneficial here
-- `LOSS` = strong-pass ∩ weak-fail → do NOT escalate here
-- `SAFE` = both pass
-- `HARD` = both fail
-
-**Running the sweep**
-
-Three scripts in `benchmark/calibration/cascade/` form the pipeline:
-
-| Script | Input | Output | What it does |
-|---|---|---|---|
-| `signal_extractor.py` | Harbor task dir (JSONL trajectory) | `ToolResultSignal` per turn | Replays a claude-code session, emitting the same signal the cascade picker would have seen at each turn (write/edit/read counts, severity, tests passed, etc.) |
-| `calibrate.py` | Harbor run dirs (one per arm) | `per_task.jsonl`, `per_turn.jsonl` | Reads `result.json` + trajectory JSONL for each task in each arm. Calls `signal_extractor` to build per-turn signals, then writes one record per task (outcome + features) and one record per turn (signal snapshot). Also prints RESCUE/LOSS/SAFE/HARD quadrant counts. |
-| `sweep.py` | `per_task.jsonl`, `per_turn.jsonl` | Console table | Replays the per-turn signals through a set of escalation policies and scores each: pass%, escalation rate. The best-scoring policy that keeps escalation rate reasonable is your calibrated threshold. |
-
-```bash
-cd benchmark/calibration/cascade
-python calibrate.py \
- --strong-run-dir /tmp/runs/your_strong_run \
- --weak-run-dir /tmp/runs/your_weak_probe
-python sweep.py
-```
-
-`calibrate.py` writes `per_task.jsonl` and `per_turn.jsonl`. `sweep.py`
-prints the policy score table; pick the best row from that output.
-
-Pick the policy whose pass% beats `always_stay` with an acceptable
-escalation rate. Translate it to a `confidence_threshold` value. A policy
-that escalates ~20% of tasks maps roughly to `confidence_threshold: 0.5`
-with `cascade_strong_default`.
-
-Even 15–20 probe tasks produce a stable result because signal features are
-extracted from the strong-arm trajectories, which are available for all
-tasks from the pure-strong run.
-
-**Caveat on weak outcomes in cascade vs. pure-weak**
-
-In cascade, the weak model may inherit partial context from the strong arm
-(conversation history up to the escalation point). Pure-weak runs start
-fresh, so RESCUE is a conservative lower bound. Weak performs at least as
-well in cascade as it does alone.
-
-### Rate-limit isolation (production caveat)
-
-The YAML below keeps the classifier on `${OPENROUTER_API_KEY}` for a compact
-example. If the classifier and weak tier share a provider bucket, each classified
-turn adds one extra request to that bucket. Production deployments should use a
-separate classifier credential or quota bucket, or skip the classifier sub-block
-on quota-constrained deployments. Co-locating them on one bucket can produce
-sustained 429s at scale.
-
----
-
-## Profile configuration
-
-```yaml
-endpoints:
- openrouter:
- base_url: https://openrouter.ai/api/v1
- api_key: ${OPENROUTER_API_KEY}
-
-targets:
- strong:
- endpoint: openrouter
- model: openai/gpt-4o
- format: openai
- weak:
- endpoint: openrouter
- model: openai/gpt-4o-mini
- format: openai
-
-profiles:
- smart-cascade:
- type: cascade
- picker: cascade_strong_default # or cascade_weak_default
- confidence_threshold: 0.5 # recommended; range [0.0, 1.0]
- signal_recent_window: 3 # Rust sliding-window for recent_* counts
- fallback_target_on_evict: strong # required; see Context-Window Handling
- strong: strong # target id
- weak: weak # target id
- classifier: # optional
- model: openai/gpt-4o-mini
- api_key: ${OPENROUTER_API_KEY} # use a separate key/quota in production
- base_url: https://openrouter.ai/api/v1
- timeout_secs: 30.0
- recent_turn_window: 3
- enable_stats: true # default true
-```
-
-Save the file as `profiles.yaml` and start it with:
-
-```bash
-switchyard serve --config profiles.yaml --port 4000
-```
-
-Omit the `classifier` block to use signals only. If `confidence_threshold` is
-also omitted, this Rust profile uses its schema default of `0.7`; the example
-sets the recommended `0.5` explicitly.
-
-`fallback_target_on_evict` is required and must reference one of the
-declared target ids. See [Context-Window Handling](../operations/context_window.md) for
-exception types and error envelopes.
-
-!!! note "Launcher compatibility"
- Launcher subcommands do not accept `--config`. A launcher-owned cascade
- still requires the deprecated `--routing-profiles` compatibility path and
- its legacy `routes:` schema. Use the same `type: cascade`, picker, target,
- classifier, and explicit `confidence_threshold: 0.5` values there.
-
----
-
-## Observability
-
-### Per-tier token / cost stats (standard)
-
-```bash
-curl http://localhost:4000/v1/stats
-```
-
-Returns the `StatsAccumulator` snapshot: per-model calls, tokens,
-latency, cost. Bucketed by `ctx.selected_model`; the `tier` field comes
-from `ctx.selected_target`. The same shape lands in
-`routing_stats_final.json` for batch runs.
-
-### Decision-source metadata (cascade-specific)
-
-The profile records decision-source counts under
-`routing_decisions.cascade` in the stats JSON. The possible values are:
-
-| Source | When |
-|---|---|
-| `override` | Hard override fired (critical severity, clean tests). |
-| `dimensions` | Scorer crossed `confidence_threshold`. |
-| `llm-classifier` | Scorer was ambiguous and the classifier returned a verdict. |
-| `fall_open` | Scorer was ambiguous and the classifier failed or wasn't configured. Default tier used. |
-
-Harness writers snapshot stats with:
-
-```bash
-curl -s http://localhost:4000/v1/stats > routing_stats_final.json
-```
-
----
-
-## When *not* to use cascade
-
-- **Single-model deployments.** Use
- `PassthroughProfileConfig(...).build()` wrapped by `ProfileSwitchyard`.
-- **Probabilistic A/B splits.** Use
- [Random Routing](random_routing.md) (`type: random-routing` in profile configs).
- The cascade's signals are wasted on a fixed traffic ratio.
-- **No tool-result history.** Cascade needs meaningful tool-call traffic to
- populate `ToolResultSignal`. For pure chat-completion workloads every
- ambiguous request lands on the picker's default tier.
-
----
-
-## Related
-
-- [Architecture](../architecture.md): the end-to-end request lifecycle and
- system boundaries.
diff --git a/docs/routing_algorithms/llm_classifier_routing.md b/docs/routing_algorithms/llm_classifier_routing.md
index bbdffbee4..3c08be7ce 100644
--- a/docs/routing_algorithms/llm_classifier_routing.md
+++ b/docs/routing_algorithms/llm_classifier_routing.md
@@ -120,5 +120,5 @@ profile loaded by `switchyard serve --config` does not yet expose them. See
the interaction with routing decisions.
If the per-request classifier cost is too high, use
-[Cascade Routing](cascade_routing.md), which can route many turns from tool and
+[Stage-Router Routing](stage_router_routing.md), which can route many turns from tool and
agent-progress signals without an extra classifier call.
diff --git a/docs/routing_algorithms/overview.md b/docs/routing_algorithms/overview.md
index 81186fc1f..3b80c732a 100644
--- a/docs/routing_algorithms/overview.md
+++ b/docs/routing_algorithms/overview.md
@@ -17,7 +17,7 @@ for configuration and tuning.
|---|---|---|
| [Random Routing](random_routing.md) | You need a fixed strong/weak split for A/B tests, baselines, or cost experiments. | `random-routing` |
| [LLM Classifier Routing](llm_classifier_routing.md) | Request content should decide whether a turn needs the weak or strong tier. | `llm-routing` |
-| [Cascade Routing](cascade_routing.md) | Tool-result and agent-progress signals should route most turns without an extra classifier call. | `cascade` |
+| [Stage-Router Routing](stage_router_routing.md) | Tool-result and agent-progress signals should route most turns without an extra classifier call. | `stage_router` |
[Session Affinity (Sticky Routing)](sticky_routing.md) is an opt-in feature of
LLM classifier routing, not a standalone routing strategy. The classifier
@@ -149,7 +149,7 @@ Pins use a bounded in-process LRU keyed from the stable conversation prefix.
They are not shared across workers or restarts. See
[Sticky Routing](sticky_routing.md) for configuration and key derivation.
-Random and cascade routing do not expose session-affinity settings; they
+Random and stage-router routing do not expose session-affinity settings; they
continue to make a routing decision for each request.
!!! note "CLI schema availability"
diff --git a/docs/routing_algorithms/random_routing.md b/docs/routing_algorithms/random_routing.md
index 56c661a1f..360b10310 100644
--- a/docs/routing_algorithms/random_routing.md
+++ b/docs/routing_algorithms/random_routing.md
@@ -6,7 +6,7 @@ rest to a `weak` model. It does not inspect the prompt.
Use it for A/B tests, benchmark baselines, and gradual traffic ramps. If routing
should depend on task difficulty, use
[LLM Classifier Routing](llm_classifier_routing.md) or
-[Cascade Routing](cascade_routing.md).
+[Stage-Router Routing](stage_router_routing.md).
## Algorithm
diff --git a/docs/routing_algorithms/stage_router_routing.md b/docs/routing_algorithms/stage_router_routing.md
new file mode 100644
index 000000000..a9ec02383
--- /dev/null
+++ b/docs/routing_algorithms/stage_router_routing.md
@@ -0,0 +1,309 @@
+# Stage-Router Routing
+
+Stage-router routing sends each request to either a **capable** model or a
+cheaper **efficient** one, depending on where the agent is in its run. The goal
+is to spend the capable model on the turns that need it (exploration, error
+recovery, hard reasoning) and let the efficient model carry the routine,
+mechanical work. Which tier a turn defaults to depends on the picker you choose
+(`capable_first` or `efficient_first`); the signals then move individual turns
+off that default. You configure it with a single knob, `confidence_threshold`,
+plus an optional LLM classifier.
+
+If the selected backend hits a context-window overflow, the router retries once
+against `fallback_target_on_evict`; a second overflow surfaces a
+context-pool-exhausted error (see [Context-Window Handling](../operations/context_window.md)).
+
+## How it works
+
+A coding agent's run moves through stages: early on it explores the codebase and
+recovers from errors, and later it settles into more mechanical implementation.
+Those stages call for different amounts of model capability, which is what the
+router keys on.
+
+For each LLM call, stage-router estimates which stage the agent is in from the
+**tool-result history** on the conversation: whether writes and edits are
+landing, whether tests pass, whether commands error out, how much read-only
+exploration is happening, and how far into the run it is. It turns those signals
+into a confidence score for "this turn needs the capable tier", then routes:
+
+- the **capable** tier for uncertain, exploratory, or error-recovery turns, and
+- the **efficient** tier for settled, mechanical turns.
+
+`confidence_threshold` sets how sure that estimate must be before the router acts
+on the signal alone. Below it, the turn stays on the picker's default tier (or,
+if you added the optional classifier, goes to it first). A turn with no
+tool-result history yet has no stage to estimate, so it takes the default tier.
+
+The routing decision for one turn:
+
+```mermaid
+%%{init: {"flowchart": {"nodeSpacing": 18, "rankSpacing": 26}}}%%
+flowchart LR
+ t["turn"] --> g{"confidence >= threshold?"}
+ g -->|yes| s["signals pick capable/efficient"]
+ g -->|no| c{"classifier set?"}
+ c -->|yes| k["classifier picks capable/efficient"]
+ c -->|no| d["use picker default tier"]
+
+ classDef box font-family:monospace,fill:none,stroke:#9aa0a6,stroke-width:1px;
+ class t,s,k,d,g,c box;
+```
+
+With `capable_first`, the default is capable, so a turn only reaches the cheaper
+efficient model on a confident efficient signal (or an efficient verdict from
+the classifier). Raising the threshold shrinks that path; lowering it widens it.
+
+## Pickers
+
+The picker name says which tier is the **default**: the tier used when the
+signals are ambiguous and no classifier verdict is available.
+
+- **`capable_first`**: capable is the default; drop to efficient only when the
+ signals (or the classifier) clearly say so. Quality-first.
+- **`efficient_first`**: efficient is the default; escalate to capable only when
+ the signals (or the classifier) clearly say so. Cost-first.
+
+Both pickers read the same signals; only the default tier differs.
+
+## Tuning `confidence_threshold`
+
+The scorer rates each turn from `0` (signals are neutral) to `1` (signals point
+hard at one tier). `confidence_threshold` is the bar that rating has to clear
+before the router will switch off the picker's default tier. Clear it and the
+router routes to the tier the signals indicate; fall short and the turn stays on
+the default.
+
+With the default `capable_first` picker, every turn starts on the capable tier
+and only drops to the efficient tier when the signals say "efficient" and clear
+the threshold. So the threshold sets how much evidence it takes to switch to the
+cheaper tier:
+
+- Raise it and only strong, decisive signals drop a turn to efficient, so the
+ router stays on capable longer (more quality, more cost).
+- Lower it and weaker signals are enough to drop to efficient, so more turns go
+ cheap (more savings, more risk).
+
+`efficient_first` is the mirror: turns start on efficient and need a signal that
+clears the threshold to escalate to capable.
+
+(If you add the optional classifier, sub-threshold turns go to it instead of
+staying on the default tier.)
+
+**Set `0.5` explicitly.** It's the recommended starting point and is what the
+example below uses. The default when you omit the field depends on which config
+path you take:
+
+| Configuration path | Default when omitted |
+|---|---|
+| Profile config (`switchyard serve --config`) | `0.7` |
+| Deprecated route bundle (`--routing-profiles`) | `0.5` |
+
+Rather than rely on either default, set `confidence_threshold: 0.5` yourself.
+
+| `confidence_threshold` | Include `classifier:` block? | Typical use |
+|---|---|---|
+| `0.0` | no | Cost/latency-sensitive. Every signal-based verdict is accepted; no per-turn LLM call. Critical-error signals still escalate to capable. |
+| `0.5` | no | Recommended starting point. A single strong signal clears the threshold on its own; derived from SWE-Bench Pro calibration. |
+| `0.7` - `0.9` | yes | Classifier-assisted. Low-confidence turns go to the LLM classifier before falling back to the default tier. `0.7` is the profile-config default when the field is omitted. |
+| `1.0` | yes (required) | Classifier-driven. Equivalent to the legacy `coding_agent` profile. |
+
+The signal-vs-classifier split is dataset-dependent. Measure it in
+production via `routing_decisions.stage_router` on `/v1/stats` rather than relying on
+priors from this doc.
+
+### Calibrating the threshold from run data
+
+The recommended `0.5` starting point was derived from SWE-Bench Pro Python-75
+calibration. To tune for a different task set or model pair, follow this
+minimum-data path.
+
+**What you need**
+
+| Run | Coverage | Purpose |
+|---|---|---|
+| Pure-capable | ~40–75 representative tasks | Baseline outcomes + signal features |
+| Pure-efficient | ~20 tasks (sampled from capable results) | Counterfactual outcomes |
+
+Neither run needs to cover the full task set. A few dozen capable tasks gives
+enough outcome diversity; the efficient probe only needs to cover the interesting
+quadrant candidates identified from those capable results.
+
+**How to sample the efficient probe set**
+
+Stratify the pure-capable results across four quadrant candidates before running efficient:
+
+| Category | Criterion | Count | Value |
+|---|---|---|---|
+| Easy + clean | Capable passes, small diff, clear spec | ~5 | Establishes SAFE floor |
+| Easy + tricky | Capable passes, subtle logic | ~5 | Catches LOSS false-positives |
+| Hard + structural | Capable fails, large multi-file diff | ~5 | HARD noise baseline |
+| Hard + localized | Capable fails, small targeted fix | ~5 | Best RESCUE signal |
+
+Sample across repos and diff sizes. Don't over-represent one project.
+
+**Building RESCUE / LOSS quadrants**
+
+From the overlap tasks (those with both capable and efficient results):
+
+- `RESCUE` = capable-fail ∩ efficient-pass → escalation is beneficial here
+- `LOSS` = capable-pass ∩ efficient-fail → do NOT escalate here
+- `SAFE` = both pass
+- `HARD` = both fail
+
+**Running the sweep**
+
+Three scripts in `benchmark/calibration/stage_router/` form the pipeline:
+
+| Script | Input | Output | What it does |
+|---|---|---|---|
+| `signal_extractor.py` | Harbor task dir (JSONL trajectory) | one signal per turn | Replays a claude-code session, emitting the same signal the stage-router picker would have seen at each turn (write/edit/read counts, severity, tests passed, etc.) |
+| `calibrate.py` | Harbor run dirs (one per arm) | `per_task.jsonl`, `per_turn.jsonl` | Reads `result.json` + trajectory JSONL for each task in each arm. Calls `signal_extractor` to build per-turn signals, then writes one record per task (outcome + features) and one record per turn (signal snapshot). Also prints RESCUE/LOSS/SAFE/HARD quadrant counts. |
+| `sweep.py` | `per_task.jsonl`, `per_turn.jsonl` | Console table | Replays the per-turn signals through a set of escalation policies and scores each: pass%, escalation rate. The best-scoring policy that keeps escalation rate reasonable is your calibrated threshold. |
+
+```bash
+cd benchmark/calibration/stage_router
+python calibrate.py \
+ --capable-run-dir /tmp/runs/your_capable_run \
+ --efficient-run-dir /tmp/runs/your_efficient_probe
+python sweep.py
+```
+
+`calibrate.py` writes `per_task.jsonl` and `per_turn.jsonl`. `sweep.py`
+prints the policy score table; pick the best row from that output.
+
+Pick the policy whose pass% beats `always_stay` with an acceptable
+escalation rate. Translate it to a `confidence_threshold` value. A policy
+that escalates ~20% of tasks maps roughly to `confidence_threshold: 0.5`
+with `capable_first`.
+
+Even 15–20 probe tasks produce a stable result because signal features are
+extracted from the capable-arm trajectories, which are available for all
+tasks from the pure-capable run.
+
+**Caveat on efficient outcomes in stage-router vs. pure-efficient**
+
+In stage-router, the efficient model may inherit partial context from the capable arm
+(conversation history up to the escalation point). Pure-efficient runs start
+fresh, so RESCUE is a conservative lower bound. Efficient performs at least as
+well in stage-router as it does alone.
+
+## Profile configuration
+
+```yaml
+endpoints:
+ openrouter:
+ base_url: https://openrouter.ai/api/v1
+ api_key: ${OPENROUTER_API_KEY}
+
+# Targets are named by the model id they serve.
+targets:
+ openai/gpt-4o:
+ endpoint: openrouter
+ model: openai/gpt-4o
+ format: openai
+ openai/gpt-4o-mini:
+ endpoint: openrouter
+ model: openai/gpt-4o-mini
+ format: openai
+
+profiles:
+ smart-stage-router:
+ type: stage_router
+ picker: capable_first # or efficient_first
+ confidence_threshold: 0.5 # recommended; range [0.0, 1.0]
+ signal_recent_window: 3 # sliding window for recent signal counts
+ fallback_target_on_evict: openai/gpt-4o # required; see Context-Window Handling
+ capable: openai/gpt-4o # capable tier target id
+ efficient: openai/gpt-4o-mini # efficient tier target id
+ enable_stats: true # default true
+```
+
+Save the file as `profiles.yaml` and start it with:
+
+```bash
+switchyard serve --config profiles.yaml --port 4000
+```
+
+This is the recommended default: routing on tool signals alone, no classifier.
+If you omit `confidence_threshold`, the profile-config default of `0.7` applies;
+the example sets `0.5` explicitly.
+
+`fallback_target_on_evict` is required and must reference one of the
+declared target ids. See [Context-Window Handling](../operations/context_window.md) for
+exception types and error envelopes.
+
+### Optional: add an LLM classifier
+
+By default the router uses tool signals only. If you want a model to break the
+tie on low-confidence turns, add a `classifier:` block and set
+`confidence_threshold` above `0.0`. The classifier is consulted only for turns
+that fall below the threshold:
+
+```yaml
+ classifier:
+ model: openai/gpt-4o-mini
+ api_key: ${OPENROUTER_API_KEY} # prefer a separate key/quota in production
+ base_url: https://openrouter.ai/api/v1
+ timeout_secs: 30.0
+ recent_turn_window: 3
+```
+
+Give the classifier its own credential or quota bucket where you can. Sharing
+one provider bucket with the efficient tier adds a request per classified turn
+and can cause sustained 429s at scale.
+
+**Launcher compatibility.** Launcher subcommands don't accept `--config`. A
+launcher-owned stage-router still needs the deprecated `--routing-profiles` path
+and its legacy `routes:` schema. Use the same `type: stage_router`, picker,
+target, classifier, and explicit `confidence_threshold: 0.5` values there.
+
+## Observability
+
+### Per-tier token / cost stats (standard)
+
+```bash
+curl http://localhost:4000/v1/stats
+```
+
+Returns the stats snapshot: per-model calls, tokens, latency, and cost, bucketed
+by served model, each tagged with a `capable` or `efficient` `tier`. Batch
+harnesses usually capture this same snapshot to a file (see below).
+
+### Decision-source metadata (stage-router-specific)
+
+The profile counts why each turn was routed the way it was, under
+`routing_decisions.stage_router` in the stats JSON. For the `serve --config`
+profile the values are:
+
+| Source | When |
+|---|---|
+| `override` | A hard override fired (for example a critical error severity, or a clean test pass). |
+| `dimensions` | The signals crossed `confidence_threshold` and picked the tier. |
+| `llm-classifier` | The signals were ambiguous and the classifier returned a verdict. |
+| `fall_open` | The signals were ambiguous and the classifier failed or wasn't configured, so the default tier was used. |
+| `context_overflow_fallback` | A context-window overflow rerouted the turn to `fallback_target_on_evict`. |
+
+The deprecated `--routing-profiles` path reports the same sources except
+`context_overflow_fallback`, plus `no_signal` for turns that arrive before any
+tool-result history exists.
+
+To capture a snapshot for a batch run, redirect the endpoint to a file:
+
+```bash
+curl -s http://localhost:4000/v1/stats > routing_stats_final.json
+```
+
+## When *not* to use stage-router
+
+- **Single-model deployments.** Use a plain passthrough profile instead.
+- **Probabilistic A/B splits.** Use
+ [Random Routing](random_routing.md) (`type: random-routing` in profile configs).
+ The stage-router's signals are wasted on a fixed traffic ratio.
+- **No tool-result history.** Stage-router needs meaningful tool-call traffic to
+ populate the tool-result signal. For pure chat-completion workloads every
+ ambiguous request lands on the picker's default tier.
+
+## Related
+
+- [Architecture](../architecture.md): the end-to-end request lifecycle and
+ system boundaries.
diff --git a/examples/profiles.yaml b/examples/profiles.yaml
index b594a8372..018ed7fcb 100644
--- a/examples/profiles.yaml
+++ b/examples/profiles.yaml
@@ -4,9 +4,9 @@
#
# Each profile id and each target id is exposed as a model on GET /v1/models, so
# a client (or `switchyard launch claude --model <id>`) selects a profile by id:
-# fast passthrough to the weak target
-# smart-cascade signal-based cascade routing between weak and strong
-# weak / strong the targets, addressable directly
+# fast passthrough to the efficient model
+# smart-stage-router signal-based stage-router routing between the efficient and capable models
+# the model ids the targets, addressable directly
#
# All profile types here are Rust-defined, so this file is served by the Rust
# profile server. Files that include Python-defined profiles (see
@@ -17,12 +17,14 @@ endpoints:
base_url: https://openrouter.ai/api/v1
api_key: ${OPENROUTER_API_KEY}
+# Targets are named by the model id they serve, so the profile below reads as
+# "capable = <this model>, efficient = <that model>".
targets:
- strong:
+ anthropic/claude-opus-4.7:
endpoint: openrouter
model: anthropic/claude-opus-4.7
format: openai
- weak:
+ moonshotai/kimi-k2.6:
endpoint: openrouter
model: moonshotai/kimi-k2.6
format: openai
@@ -30,14 +32,14 @@ targets:
profiles:
fast:
type: passthrough
- target: weak
+ target: moonshotai/kimi-k2.6
- smart-cascade:
- type: cascade
- strong: strong
- weak: weak
- fallback_target_on_evict: strong
- picker: cascade_strong_default
+ smart-stage-router:
+ type: stage_router
+ capable: anthropic/claude-opus-4.7
+ efficient: moonshotai/kimi-k2.6
+ fallback_target_on_evict: anthropic/claude-opus-4.7
+ picker: capable_first
confidence_threshold: 0.7
signal_recent_window: 3
classifier:
diff --git a/mkdocs.yml b/mkdocs.yml
index 8ab0c48ed..8d4ffa84b 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -31,7 +31,7 @@ nav:
- Random Routing: routing_algorithms/random_routing.md
- LLM Classifier Routing: routing_algorithms/llm_classifier_routing.md
- Sticky Routing: routing_algorithms/sticky_routing.md
- - Cascade Routing: routing_algorithms/cascade_routing.md
+ - Stage-Router Routing: routing_algorithms/stage_router_routing.md
- Operations:
- Context-Window Handling: operations/context_window.md
- Reference:
diff --git a/pyproject.toml b/pyproject.toml
index b62f023ed..f3945e605 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -138,7 +138,7 @@ where = ["."]
include = ["switchyard*"]
[tool.setuptools.package-data]
-switchyard = ["py.typed", "lib/processors/cascade/prompts/*.md"]
+switchyard = ["py.typed", "lib/processors/stage_router/prompts/*.md"]
switchyard_rust = ["py.typed", "*.pyi"]
[tool.maturin]
diff --git a/switchyard/__init__.py b/switchyard/__init__.py
index e171d7c01..cb1790433 100644
--- a/switchyard/__init__.py
+++ b/switchyard/__init__.py
@@ -55,8 +55,6 @@ from switchyard.lib.processors.routellm_request_processor import (
RouteLLMRequestProcessor,
)
from switchyard.lib.profiles import (
- CascadeConfig,
- CascadeProfileConfig,
ClassifierConfig,
ContextAwareProfile,
DeterministicRoutingConfig,
@@ -85,6 +83,8 @@ from switchyard.lib.profiles import (
RandomRoutingProfileConfig,
RouteLLMConfig,
RouteLLMProfileConfig,
+ StageRouterConfig,
+ StageRouterProfileConfig,
TranslateProfileConfig,
build_profile,
load_profiles,
@@ -158,8 +158,8 @@ __all__ = [
"LLMBackend",
"NoopProfile",
"NoopProfileConfig",
- "CascadeConfig",
- "CascadeProfileConfig",
+ "StageRouterConfig",
+ "StageRouterProfileConfig",
"ClassifierConfig",
"ContextAwareProfile",
"DeterministicRoutingConfig",
diff --git a/switchyard/cli/configure_command.py b/switchyard/cli/configure_command.py
index d3ce2a56b..30379b502 100644
--- a/switchyard/cli/configure_command.py
+++ b/switchyard/cli/configure_command.py
@@ -452,7 +452,7 @@ def cmd_configure(args: argparse.Namespace) -> None:
# Resolve routing-profiles up front (CLI > existing config > interactive
# prompt) so the model picker can surface route ids + their tier models
# alongside the upstream catalog. Without this the wizard offers only the
- # raw `/v1/models` response and the user can't pick e.g. `opus-ds-cascade`
+ # raw `/v1/models` response and the user can't pick e.g. `opus-ds-stage_router`
# even when their YAML declares it.
routing_profiles = existing_config.routing_profiles
if args.routing_profiles is not None:
diff --git a/switchyard/cli/launchers/launcher_runtime.py b/switchyard/cli/launchers/launcher_runtime.py
index 641069c45..333d424c0 100644
--- a/switchyard/cli/launchers/launcher_runtime.py
+++ b/switchyard/cli/launchers/launcher_runtime.py
@@ -260,11 +260,11 @@ def _route_type_summary(route_type: str, route: object, route_key: str) -> str:
m = _model(clf)
return f", llm-classifier={m}" if m else ""
- if route_type == "cascade":
+ if route_type == "stage_router":
clf = _classifier_part(r)
threshold = r.get("confidence_threshold")
threshold_part = f", confidence_threshold={threshold}" if threshold is not None else ""
- return f"cascade: strong={_model(r.get('strong'))}, weak={_model(r.get('weak'))}{clf}{threshold_part}"
+ return f"stage_router: strong={_model(r.get('strong'))}, weak={_model(r.get('weak'))}{clf}{threshold_part}"
if route_type in ("deterministic", "llm_classifier"):
clf = _classifier_part(r)
profile = r.get("profile")
diff --git a/switchyard/cli/route_bundle.py b/switchyard/cli/route_bundle.py
index e3884245f..4ce5251bc 100644
--- a/switchyard/cli/route_bundle.py
+++ b/switchyard/cli/route_bundle.py
@@ -36,19 +36,19 @@ from switchyard.lib.config import LatencyServiceBackendConfig, LatencyServiceEnd
from switchyard.lib.processors.llm_classifier import DEFAULT_MAX_REQUEST_CHARS
from switchyard.lib.processors.llm_classifier.presets import PROFILE_FACTORIES
from switchyard.lib.profiles import (
- CascadeProfileConfig,
DeterministicRoutingProfileConfig,
LatencyServiceProfileConfig,
PlanExecuteProfileConfig,
ProfileSwitchyard,
RouteLLMProfileConfig,
+ StageRouterProfileConfig,
)
-from switchyard.lib.profiles.cascade_config import CascadeConfig
from switchyard.lib.profiles.deterministic_routing_config import DeterministicRoutingConfig
from switchyard.lib.profiles.plan_execute_config import PlanExecuteConfig
from switchyard.lib.profiles.plan_execute_presets import PlanExecutePresets
from switchyard.lib.profiles.random_routing import RandomRoutingConfig
from switchyard.lib.profiles.routellm import RouteLLMConfig
+from switchyard.lib.profiles.stage_router_config import StageRouterConfig
from switchyard.lib.route_table import ChainRuntime, RouteTable
from switchyard.lib.route_table_builders import (
build_passthrough_table,
@@ -231,7 +231,7 @@ _DETERMINISTIC_ROUTE_KEYS = (
"affinity_warmup_turns",
})
)
-_CASCADE_ROUTE_KEYS = (
+_STAGE_ROUTER_ROUTE_KEYS = (
_ROUTE_METADATA_KEYS
| _TARGET_DEFAULT_ROUTE_KEYS
| frozenset({
@@ -270,7 +270,7 @@ _DETERMINISTIC_CLASSIFIER_KEYS = frozenset({
"prompt",
"max_request_chars",
})
-_CASCADE_CLASSIFIER_KEYS = frozenset({
+_STAGE_ROUTER_CLASSIFIER_KEYS = frozenset({
"model",
"api_key",
"base_url",
@@ -292,7 +292,7 @@ _ROUTE_KEYS_BY_TYPE: Mapping[str, frozenset[str]] = {
"noop": _NOOP_ROUTE_KEYS,
"passthrough": _PASSTHROUGH_ROUTE_KEYS,
"deterministic": _DETERMINISTIC_ROUTE_KEYS,
- "cascade": _CASCADE_ROUTE_KEYS,
+ "stage_router": _STAGE_ROUTER_ROUTE_KEYS,
"plan_execute": _PLAN_EXECUTE_ROUTE_KEYS,
}
_DEFAULT_KEYS_BY_TYPE: Mapping[str, frozenset[str]] = {
@@ -303,7 +303,7 @@ _DEFAULT_KEYS_BY_TYPE: Mapping[str, frozenset[str]] = {
"passthrough": _PASSTHROUGH_SETTING_KEYS,
"noop": frozenset(),
"deterministic": _TARGET_DEFAULT_KEYS,
- "cascade": _TARGET_DEFAULT_KEYS,
+ "stage_router": _TARGET_DEFAULT_KEYS,
"plan_execute": _TARGET_DEFAULT_KEYS,
}
@@ -372,7 +372,7 @@ def routing_profile_model_ids(
"""User-callable model ids from a parsed routing-profiles bundle.
Returns each route's YAML key followed by its tier ``model`` fields
- (``strong`` / ``weak`` for cascade/deterministic/routellm/random_routing,
+ (``strong`` / ``weak`` for stage_router/deterministic/routellm/random_routing,
``planner`` / ``executor`` for plan_execute, ``target`` for
``model`` / ``passthrough``). Declaration order, later duplicates dropped.
Returns ``[]`` for a ``None`` or empty bundle.
@@ -538,11 +538,11 @@ def build_table_from_bundle(
)
continue
- # `cascade` and `deterministic` routes register the routing-policy chain
+ # `stage_router` and `deterministic` routes register the routing-policy chain
# at the route key AND hydrate each tier's catalog (`strong` + `weak`)
# into the table as direct passthroughs — same client-facing
# model-picker experience as random_routing's discovery path.
- if route_type in ("cascade", "deterministic"):
+ if route_type in ("stage_router", "deterministic"):
_merge_multi_target_discovery(
table,
model_id,
@@ -703,13 +703,13 @@ def _merge_multi_target_discovery(
pre_routing_request_processors: Sequence[Any] = (),
extra_response_processors: Sequence[Any] = (),
) -> None:
- """Expand a ``cascade``/``deterministic`` route with catalog discovery.
+ """Expand a ``stage_router``/``deterministic`` route with catalog discovery.
Registers two layers, route key first so ``registered_models()[0]`` is the
user-declared YAML key:
1. The route's primary routing-policy chain at the route key (the regular
- cascade/deterministic switchyard).
+ stage_router/deterministic switchyard).
2. Each tier (``strong`` + ``weak``) registered as a direct passthrough with
its catalog hydrated via :func:`_default_discovery_fn` — same shape the
launcher's per-tier registration produces, so client model pickers see
@@ -829,8 +829,8 @@ def _build_switchyard_for_route(
extra_response_processors=extra_response_processors,
)
- if route_type == "cascade":
- return _cascade_switchyard(
+ if route_type == "stage_router":
+ return _stage_router_switchyard(
model_id,
route,
target_defaults=target_defaults,
@@ -1001,7 +1001,7 @@ def _deterministic_switchyard(
)
-def _cascade_switchyard(
+def _stage_router_switchyard(
model_id: str,
route: Mapping[str, object],
target_defaults: Mapping[str, object],
@@ -1009,13 +1009,13 @@ def _cascade_switchyard(
pre_routing_request_processors: Sequence[Any] = (),
extra_response_processors: Sequence[Any] = (),
) -> ChainRuntime:
- """Build a cascade-routing Switchyard from a YAML ``type: cascade`` route.
+ """Build a stage-router-routing Switchyard from a YAML ``type: stage_router`` route.
- Schema (mapped onto :class:`CascadeConfig`)::
+ Schema (mapped onto :class:`StageRouterConfig`)::
route:
- type: cascade
- picker: cascade_strong_default # or cascade_weak_default
+ type: stage_router
+ picker: capable_first # or efficient_first
confidence_threshold: 0.7 # default; range [0.0, 1.0]
signal_recent_window: 3 # Rust sliding-window size
strong: <target spec> # e.g. { id: strong, model: ..., api_key: ..., format: anthropic }
@@ -1034,7 +1034,7 @@ def _cascade_switchyard(
"""
if route.get("strong") is None or route.get("weak") is None:
raise RouteBundleConfigError(
- f"route {model_id!r}: cascade route requires both 'strong' and "
+ f"route {model_id!r}: stage_router route requires both 'strong' and "
f"'weak' target specs",
)
if route.get("classifier") is not None:
@@ -1042,18 +1042,21 @@ def _cascade_switchyard(
route["classifier"] = _classifier_mapping(
route["classifier"],
target_defaults,
- allowed_keys=_CASCADE_CLASSIFIER_KEYS,
+ allowed_keys=_STAGE_ROUTER_CLASSIFIER_KEYS,
where=f"{model_id}.classifier",
)
- cascade_config = CascadeConfig.model_validate(
- _route_config(route, target_defaults, ("strong", "weak"))
- )
+ # The deprecated bundle keeps the shared strong/weak tier keys (also used by
+ # deterministic/routellm); map them onto StageRouterConfig's capable/efficient fields.
+ resolved = _route_config(route, target_defaults, ("strong", "weak"))
+ resolved["capable"] = resolved.pop("strong")
+ resolved["efficient"] = resolved.pop("weak")
+ stage_router_config = StageRouterConfig.model_validate(resolved)
return ProfileSwitchyard(
- CascadeProfileConfig.from_config(cascade_config)
+ StageRouterProfileConfig.from_config(stage_router_config)
.build()
.with_runtime_components(
stats_accumulator=stats,
- enable_stats=cascade_config.enable_stats,
+ enable_stats=stage_router_config.enable_stats,
pre_request_processors=pre_routing_request_processors,
response_processors=extra_response_processors,
)
@@ -1071,7 +1074,7 @@ def _plan_execute_switchyard(
) -> ChainRuntime:
"""Build a strong-planner / weak-executor chain from a ``type: plan_execute`` route.
- Mirrors :func:`_cascade_switchyard`: tiers and scalar fields go through the
+ Mirrors :func:`_stage_router_switchyard`: tiers and scalar fields go through the
shared ``_route_config`` → :meth:`PlanExecuteConfig.model_validate` path. An
omitted ``planner`` / ``executor`` defaults to the shipping preset model so a
minimal route reproduces the retired ``--plan-execute`` flag; every other
@@ -1334,8 +1337,8 @@ def _route_type(model_id: str, route: Mapping[str, object]) -> str:
"deterministic": "deterministic",
"llm_classifier": "deterministic",
"llm_classifier_routing": "deterministic",
- "cascade": "cascade",
- "cascade_routing": "cascade",
+ "stage_router": "stage_router",
+ "stage_router_routing": "stage_router",
"plan": "plan_execute",
"plan_execute": "plan_execute",
}
diff --git a/switchyard/cli/switchyard_cli.py b/switchyard/cli/switchyard_cli.py
index 92e71bf57..82e7acbec 100644
--- a/switchyard/cli/switchyard_cli.py
+++ b/switchyard/cli/switchyard_cli.py
@@ -1101,7 +1101,7 @@ def _build_parser() -> argparse.ArgumentParser:
" --model X single-model passthrough — every request "
"is rewritten to model=X. Falls back to the saved configure default.\n"
" --routing-profiles PATH serve a YAML bundle of routes (random, "
- "cascade, plan_execute, passthrough, …); the first declared route "
+ "stage_router, plan_execute, passthrough, …); the first declared route "
"is the initial model.\n\n"
"With neither flag, the saved routing bundle from "
"`switchyard configure` is used."
@@ -1192,7 +1192,7 @@ def _build_parser() -> argparse.ArgumentParser:
" --model X single-model passthrough — every request "
"is rewritten to model=X. Falls back to the saved configure default.\n"
" --routing-profiles PATH serve a YAML bundle of routes (random, "
- "cascade, plan_execute, passthrough, …); the first declared route "
+ "stage_router, plan_execute, passthrough, …); the first declared route "
"is the initial model.\n\n"
"With neither flag, the saved routing bundle from "
"`switchyard configure` is used."
@@ -1287,7 +1287,7 @@ def _build_parser() -> argparse.ArgumentParser:
" --model X single-model passthrough — every request "
"is rewritten to model=X. Falls back to the saved configure default.\n"
" --routing-profiles PATH serve a YAML bundle of routes (random, "
- "cascade, plan_execute, passthrough, …); the first declared route "
+ "stage_router, plan_execute, passthrough, …); the first declared route "
"is the initial model.\n\n"
"With neither flag, the saved routing bundle from "
"`switchyard configure` is used."
diff --git a/switchyard/lib/processors/cascade/__init__.py b/switchyard/lib/processors/cascade/__init__.py
deleted file mode 100644
index ff2a796e4..000000000
--- a/switchyard/lib/processors/cascade/__init__.py
+++ /dev/null
@@ -1,48 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-
-"""Cascade — weighted scorer + selective LLM-classifier."""
-
-from switchyard.lib.processors.cascade.classifier import (
- STRONG_TIER,
- WEAK_TIER,
- TierClassifier,
-)
-from switchyard.lib.processors.cascade.decision_log import (
- CONTEXT_KEY,
- CascadeDecisionLog,
- DecisionSource,
-)
-from switchyard.lib.processors.cascade.dimensions import (
- CodingAgentDimensions,
- from_signal,
-)
-from switchyard.lib.processors.cascade.picker import (
- STRONG,
- WEAK,
- pick_strong_default,
- pick_weak_default,
-)
-from switchyard.lib.processors.cascade.scorer import (
- DEFAULT_WEIGHTS,
- ScoreResult,
- score,
-)
-
-__all__ = [
- "CONTEXT_KEY",
- "DEFAULT_WEIGHTS",
- "STRONG",
- "STRONG_TIER",
- "CascadeDecisionLog",
- "CodingAgentDimensions",
- "DecisionSource",
- "ScoreResult",
- "TierClassifier",
- "WEAK",
- "WEAK_TIER",
- "from_signal",
- "pick_strong_default",
- "pick_weak_default",
- "score",
-]
diff --git a/switchyard/lib/processors/cascade/prompts/tier_classifier.md b/switchyard/lib/processors/cascade/prompts/tier_classifier.md
deleted file mode 100644
index c20c15d13..000000000
--- a/switchyard/lib/processors/cascade/prompts/tier_classifier.md
+++ /dev/null
@@ -1,5 +0,0 @@
-You are a routing classifier inside an agentic coding cascade. Given a compact summary of the agent's recent tool activity, decide whether the next model call should go to the STRONG tier (capable, expensive) or the WEAK tier (cheap, less capable).
-
-Respond with strict JSON: {"tier": "strong"} or {"tier": "weak"}.
-
-Pick WEAK when the agent shows concrete, low-friction progress (writes landing, tests passing, edits without errors). Pick STRONG when the agent is stalled, hitting errors, or facing a task likely to require careful reasoning.
diff --git a/switchyard/lib/processors/stage_router/__init__.py b/switchyard/lib/processors/stage_router/__init__.py
new file mode 100644
index 000000000..217acc7dc
--- /dev/null
+++ b/switchyard/lib/processors/stage_router/__init__.py
@@ -0,0 +1,48 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""StageRouter — weighted scorer + selective LLM-classifier."""
+
+from switchyard.lib.processors.stage_router.classifier import (
+ CAPABLE_TIER,
+ EFFICIENT_TIER,
+ TierClassifier,
+)
+from switchyard.lib.processors.stage_router.decision_log import (
+ CONTEXT_KEY,
+ DecisionSource,
+ StageRouterDecisionLog,
+)
+from switchyard.lib.processors.stage_router.dimensions import (
+ CodingAgentDimensions,
+ from_signal,
+)
+from switchyard.lib.processors.stage_router.picker import (
+ CAPABLE,
+ EFFICIENT,
+ pick_capable_first,
+ pick_efficient_first,
+)
+from switchyard.lib.processors.stage_router.scorer import (
+ DEFAULT_WEIGHTS,
+ ScoreResult,
+ score,
+)
+
+__all__ = [
+ "CONTEXT_KEY",
+ "DEFAULT_WEIGHTS",
+ "CAPABLE",
+ "CAPABLE_TIER",
+ "StageRouterDecisionLog",
+ "CodingAgentDimensions",
+ "DecisionSource",
+ "ScoreResult",
+ "TierClassifier",
+ "EFFICIENT",
+ "EFFICIENT_TIER",
+ "from_signal",
+ "pick_capable_first",
+ "pick_efficient_first",
+ "score",
+]
diff --git a/switchyard/lib/processors/cascade/classifier.py b/switchyard/lib/processors/stage_router/classifier.py
similarity index 94%
rename from switchyard/lib/processors/cascade/classifier.py
rename to switchyard/lib/processors/stage_router/classifier.py
index 96ab0c2b7..0e4fc0951 100644
--- a/switchyard/lib/processors/cascade/classifier.py
+++ b/switchyard/lib/processors/stage_router/classifier.py
@@ -20,11 +20,11 @@ if TYPE_CHECKING:
log = logging.getLogger(__name__)
#: Tier values returned by :meth:`TierClassifier.classify`. Mirrors picker constants.
-STRONG_TIER: str = "strong"
-WEAK_TIER: str = "weak"
+CAPABLE_TIER: str = "capable"
+EFFICIENT_TIER: str = "efficient"
#: ``ctx.metadata`` key for inbound conversation messages — read by the classifier.
-RECENT_MESSAGES_KEY: str = "cascade_recent_messages"
+RECENT_MESSAGES_KEY: str = "stage_router_recent_messages"
#: Per-message char cap when rendering recent turns into the classifier prompt.
_MAX_MESSAGE_CHARS: int = 400
@@ -33,7 +33,7 @@ _MAX_MESSAGE_CHARS: int = 400
def _load_system_prompt() -> str:
"""Read the classifier system prompt from the prompts/ package-data file."""
return (
- files("switchyard.lib.processors.cascade.prompts")
+ files("switchyard.lib.processors.stage_router.prompts")
.joinpath("tier_classifier.md")
.read_text(encoding="utf-8")
.strip()
@@ -65,13 +65,13 @@ def _summarise(
]
state_line = "State: " + ", ".join(parts)
if not recent_messages:
- return "Decide STRONG or WEAK for the next call. " + state_line
+ return "Decide CAPABLE or EFFICIENT for the next call. " + state_line
transcript_lines = ["Recent turns (most recent last):"]
for msg in recent_messages:
transcript_lines.append(_format_message(msg))
return (
- "Decide STRONG or WEAK for the next call.\n"
+ "Decide CAPABLE or EFFICIENT for the next call.\n"
+ state_line
+ "\n"
+ "\n".join(transcript_lines)
@@ -113,7 +113,7 @@ def _format_message(msg: Any) -> str:
def _parse_tier(response: object) -> str | None:
- """Extract ``"strong"`` / ``"weak"`` from a chat-completion response, or ``None``.
+ """Extract ``"capable"`` / ``"efficient"`` from a chat-completion response, or ``None``.
Mirrors ``_completion_content`` in
:mod:`switchyard.lib.processors.llm_classifier.request_processor` — only reads
@@ -135,7 +135,7 @@ def _parse_tier(response: object) -> str | None:
log.warning("classifier response not valid JSON: %r", content[:120])
return None
tier = payload.get("tier") if isinstance(payload, dict) else None
- if tier == STRONG_TIER or tier == WEAK_TIER:
+ if tier == CAPABLE_TIER or tier == EFFICIENT_TIER:
return tier
log.warning("classifier returned unexpected tier %r", tier)
return None
@@ -188,7 +188,7 @@ class TierClassifier:
self._stats = stats_accumulator
async def classify(self, ctx: ProxyContext, signal: ToolResultSignal) -> str | None:
- """Return ``"strong"``, ``"weak"``, or ``None`` (fall-open)."""
+ """Return ``"capable"``, ``"efficient"``, or ``None`` (fall-open)."""
recent_messages: list[Any] = []
if self._recent_turn_window > 0:
stashed = ctx.metadata.get(RECENT_MESSAGES_KEY) if hasattr(ctx, "metadata") else None
@@ -246,4 +246,4 @@ class TierClassifier:
return _parse_tier(response)
-__all__ = ["STRONG_TIER", "TierClassifier", "WEAK_TIER"]
+__all__ = ["CAPABLE_TIER", "TierClassifier", "EFFICIENT_TIER"]
diff --git a/switchyard/lib/processors/cascade/decision_log.py b/switchyard/lib/processors/stage_router/decision_log.py
similarity index 81%
rename from switchyard/lib/processors/cascade/decision_log.py
rename to switchyard/lib/processors/stage_router/decision_log.py
index 986950ae8..88812196b 100644
--- a/switchyard/lib/processors/cascade/decision_log.py
+++ b/switchyard/lib/processors/stage_router/decision_log.py
@@ -1,7 +1,7 @@
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
-"""Thread-safe per-source decision counter for the cascade picker."""
+"""Thread-safe per-source decision counter for the stage_router picker."""
from dataclasses import dataclass, field
from threading import Lock
@@ -16,12 +16,12 @@ DecisionSource = Literal[
]
#: ``ctx.metadata`` key the picker writes its decision source to.
-CONTEXT_KEY: str = "cascade_decision_source"
+CONTEXT_KEY: str = "stage_router_decision_source"
@dataclass
-class CascadeDecisionLog:
- """Thread-safe counter for cascade decision sources."""
+class StageRouterDecisionLog:
+ """Thread-safe counter for stage_router decision sources."""
counts: dict[str, int] = field(default_factory=dict)
_lock: Lock = field(default_factory=Lock, repr=False, compare=False)
@@ -40,4 +40,4 @@ class CascadeDecisionLog:
return sum(self.counts.values())
-__all__ = ["CONTEXT_KEY", "CascadeDecisionLog", "DecisionSource"]
+__all__ = ["CONTEXT_KEY", "StageRouterDecisionLog", "DecisionSource"]
diff --git a/switchyard/lib/processors/cascade/dimensions.py b/switchyard/lib/processors/stage_router/dimensions.py
similarity index 100%
rename from switchyard/lib/processors/cascade/dimensions.py
rename to switchyard/lib/processors/stage_router/dimensions.py
diff --git a/switchyard/lib/processors/cascade/picker.py b/switchyard/lib/processors/stage_router/picker.py
similarity index 68%
rename from switchyard/lib/processors/cascade/picker.py
rename to switchyard/lib/processors/stage_router/picker.py
index 83c950be5..ce2461298 100644
--- a/switchyard/lib/processors/cascade/picker.py
+++ b/switchyard/lib/processors/stage_router/picker.py
@@ -1,53 +1,53 @@
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
-"""Two pickers (strong-default / weak-default) that share override + scorer
+"""Two pickers (capable-first / efficient-first) that share override + scorer
logic; differ only in their fallback tier on low-confidence turns."""
import logging
from typing import TYPE_CHECKING
-from switchyard.lib.processors.cascade.decision_log import (
+from switchyard.lib.processors.stage_router.decision_log import (
CONTEXT_KEY,
- CascadeDecisionLog,
DecisionSource,
+ StageRouterDecisionLog,
)
-from switchyard.lib.processors.cascade.dimensions import from_signal
-from switchyard.lib.processors.cascade.scorer import DEFAULT_WEIGHTS, score
+from switchyard.lib.processors.stage_router.dimensions import from_signal
+from switchyard.lib.processors.stage_router.scorer import DEFAULT_WEIGHTS, score
if TYPE_CHECKING:
from collections.abc import Mapping
- from switchyard.lib.processors.cascade.classifier import TierClassifier
+ from switchyard.lib.processors.stage_router.classifier import TierClassifier
from switchyard.lib.proxy_context import ProxyContext
from switchyard_rust.components import ToolResultSignal
log = logging.getLogger(__name__)
-WEAK: int = 0
-STRONG: int = 1
+EFFICIENT: int = 0
+CAPABLE: int = 1
# Override thresholds — tunable in one place. Promote to YAML if calibration
# diverges across deployments.
-#: Force STRONG when the latest tool result hit a CRITICAL severity pattern.
+#: Force CAPABLE when the latest tool result hit a CRITICAL severity pattern.
SEVERITY_CRITICAL: float = 1.0
-#: Force WEAK when `tests_passed` AND the agent has been working long enough
+#: Force EFFICIENT when `tests_passed` AND the agent has been working long enough
#: (turn_depth) with few writes — interpreted as the run already settled.
CLEAN_TESTS_MIN_TURN_DEPTH: int = 10
CLEAN_TESTS_MAX_WRITES: int = 1
-async def pick_strong_default(
+async def pick_capable_first(
ctx: "ProxyContext",
confidence_threshold: float,
classifier: "TierClassifier | None" = None,
weights: "Mapping[str, float]" = DEFAULT_WEIGHTS,
- decision_log: CascadeDecisionLog | None = None,
+ decision_log: StageRouterDecisionLog | None = None,
) -> int:
- """STRONG default. WEAK only when the scorer is confidently negative."""
+ """CAPABLE default. EFFICIENT only when the scorer is confidently negative."""
return await _pick(
ctx,
- default_tier=STRONG,
+ default_tier=CAPABLE,
confidence_threshold=confidence_threshold,
classifier=classifier,
weights=weights,
@@ -55,17 +55,17 @@ async def pick_strong_default(
)
-async def pick_weak_default(
+async def pick_efficient_first(
ctx: "ProxyContext",
confidence_threshold: float,
classifier: "TierClassifier | None" = None,
weights: "Mapping[str, float]" = DEFAULT_WEIGHTS,
- decision_log: CascadeDecisionLog | None = None,
+ decision_log: StageRouterDecisionLog | None = None,
) -> int:
- """WEAK default. STRONG only when the scorer is confidently positive."""
+ """EFFICIENT default. CAPABLE only when the scorer is confidently positive."""
return await _pick(
ctx,
- default_tier=WEAK,
+ default_tier=EFFICIENT,
confidence_threshold=confidence_threshold,
classifier=classifier,
weights=weights,
@@ -79,7 +79,7 @@ async def _pick(
confidence_threshold: float,
classifier: "TierClassifier | None",
weights: "Mapping[str, float]",
- decision_log: CascadeDecisionLog | None,
+ decision_log: StageRouterDecisionLog | None,
) -> int:
from switchyard_rust.components import (
get_tool_result_signal, # local import: heavy native module
@@ -96,22 +96,22 @@ async def _pick(
dimensions = from_signal(signal)
result = score(dimensions, weights=weights)
if result.confidence >= confidence_threshold:
- tier = STRONG if result.score > 0 else WEAK
+ tier = CAPABLE if result.score > 0 else EFFICIENT
return _record(ctx, decision_log, "dimensions", tier)
if classifier is None:
return _record(ctx, decision_log, "fall_open", default_tier)
verdict = await classifier.classify(ctx, signal)
- if verdict == "strong":
- return _record(ctx, decision_log, "llm-classifier", STRONG)
- if verdict == "weak":
- return _record(ctx, decision_log, "llm-classifier", WEAK)
+ if verdict == "capable":
+ return _record(ctx, decision_log, "llm-classifier", CAPABLE)
+ if verdict == "efficient":
+ return _record(ctx, decision_log, "llm-classifier", EFFICIENT)
return _record(ctx, decision_log, "fall_open", default_tier)
def _record(
ctx: "ProxyContext",
- decision_log: CascadeDecisionLog | None,
+ decision_log: StageRouterDecisionLog | None,
source: DecisionSource,
tier: int,
) -> int:
@@ -129,14 +129,14 @@ def _record(
def _apply_overrides(signal: "ToolResultSignal") -> int | None:
"""Non-negotiable, signal-derived shortcuts that bypass the scorer."""
if signal.severity >= SEVERITY_CRITICAL:
- return STRONG
+ return CAPABLE
if (
signal.tests_passed
and signal.turn_depth >= CLEAN_TESTS_MIN_TURN_DEPTH
and signal.write_count <= CLEAN_TESTS_MAX_WRITES
):
- return WEAK
+ return EFFICIENT
return None
-__all__ = ["STRONG", "WEAK", "pick_strong_default", "pick_weak_default"]
+__all__ = ["CAPABLE", "EFFICIENT", "pick_capable_first", "pick_efficient_first"]
diff --git a/switchyard/lib/processors/stage_router/prompts/tier_classifier.md b/switchyard/lib/processors/stage_router/prompts/tier_classifier.md
new file mode 100644
index 000000000..25f570fcf
--- /dev/null
+++ b/switchyard/lib/processors/stage_router/prompts/tier_classifier.md
@@ -0,0 +1,5 @@
+You are a routing classifier inside an agentic coding stage-router. Given a compact summary of the agent's recent tool activity, decide whether the next model call should go to the CAPABLE tier (frontier, expensive) or the EFFICIENT tier (cheap, less powerful).
+
+Respond with strict JSON: {"tier": "capable"} or {"tier": "efficient"}.
+
+Pick EFFICIENT when the agent shows concrete, low-friction progress (writes landing, tests passing, edits without errors). Pick CAPABLE when the agent is stalled, hitting errors, or facing a task likely to require careful reasoning.
diff --git a/switchyard/lib/processors/cascade/scorer.py b/switchyard/lib/processors/stage_router/scorer.py
similarity index 91%
rename from switchyard/lib/processors/cascade/scorer.py
rename to switchyard/lib/processors/stage_router/scorer.py
index 41e2b1c37..0c3763ad5 100644
--- a/switchyard/lib/processors/cascade/scorer.py
+++ b/switchyard/lib/processors/stage_router/scorer.py
@@ -8,9 +8,9 @@ from __future__ import annotations
from collections.abc import Mapping
from dataclasses import dataclass, field
-from switchyard.lib.processors.cascade.dimensions import CodingAgentDimensions
+from switchyard.lib.processors.stage_router.dimensions import CodingAgentDimensions
-#: Default linear weights. Positive ⇒ STRONG; negative ⇒ WEAK. Calibrated so
+#: Default linear weights. Positive ⇒ CAPABLE; negative ⇒ EFFICIENT. Calibrated so
#: a single high-impact axis lands past the 0.5 default confidence threshold.
DEFAULT_WEIGHTS: Mapping[str, float] = {
"severity": 0.80,
diff --git a/switchyard/lib/processors/cascade_request_processor.py b/switchyard/lib/processors/stage_router_request_processor.py
similarity index 74%
rename from switchyard/lib/processors/cascade_request_processor.py
rename to switchyard/lib/processors/stage_router_request_processor.py
index 432e1c32a..b91c02d4f 100644
--- a/switchyard/lib/processors/cascade_request_processor.py
+++ b/switchyard/lib/processors/stage_router_request_processor.py
@@ -2,7 +2,7 @@
# SPDX-License-Identifier: Apache-2.0
"""Tier picker component — stamps ``ctx.selected_target``/``selected_model``.
-Fails open to the weak tier on picker exceptions."""
+Fails open to the efficient tier on picker exceptions."""
from __future__ import annotations
@@ -10,15 +10,15 @@ import logging
from collections.abc import Awaitable, Callable, Sequence
from typing import TYPE_CHECKING, Any, cast
-from switchyard.lib.processors.cascade import (
+from switchyard.lib.processors.stage_router import (
+ CAPABLE,
CONTEXT_KEY,
- STRONG,
- WEAK,
- CascadeDecisionLog,
- pick_strong_default,
- pick_weak_default,
+ EFFICIENT,
+ StageRouterDecisionLog,
+ pick_capable_first,
+ pick_efficient_first,
)
-from switchyard.lib.processors.cascade.classifier import RECENT_MESSAGES_KEY, TierClassifier
+from switchyard.lib.processors.stage_router.classifier import RECENT_MESSAGES_KEY, TierClassifier
if TYPE_CHECKING:
from switchyard.lib.backends.llm_target import LlmTarget
@@ -31,14 +31,14 @@ log = logging.getLogger(__name__)
#: Async picker signature. The factory pre-binds knobs and the optional classifier.
TierPicker = Callable[["ProxyContext"], Awaitable[int]]
-#: YAML-resolvable picker names; mirrors :class:`CascadePickerMode`.
+#: YAML-resolvable picker names; mirrors :class:`StageRouterPickerMode`.
BUILTIN_PICKERS: dict[str, Callable[..., Awaitable[int]]] = {
- "cascade_strong_default": pick_strong_default,
- "cascade_weak_default": pick_weak_default,
+ "capable_first": pick_capable_first,
+ "efficient_first": pick_efficient_first,
}
-class CascadeRequestProcessor:
+class StageRouterRequestProcessor:
"""Picks a tier and stamps it on the context. Policy lives in the picker."""
def __init__(
@@ -47,20 +47,20 @@ class CascadeRequestProcessor:
targets: Sequence[LlmTarget],
picker: TierPicker,
classifier: TierClassifier | None = None,
- decision_log: CascadeDecisionLog | None = None,
+ decision_log: StageRouterDecisionLog | None = None,
) -> None:
if len(targets) != 2:
- raise ValueError(f"cascade requires exactly 2 targets, got {len(targets)}")
+ raise ValueError(f"stage_router requires exactly 2 targets, got {len(targets)}")
self._target_ids = [t.id for t in targets]
self._target_models = [t.model for t in targets]
self._picker = picker
self._classifier = classifier
self._max_index = len(targets) - 1
- self._decision_log = decision_log if decision_log is not None else CascadeDecisionLog()
+ self._decision_log = decision_log if decision_log is not None else StageRouterDecisionLog()
self._stats_accumulator: StatsAccumulator | None = None
def attach_stats_accumulator(self, stats_accumulator: StatsAccumulator) -> None:
- """Attach serving-level stats to cascade-only routing components."""
+ """Attach serving-level stats to stage_router-only routing components."""
self._stats_accumulator = stats_accumulator
if self._classifier is not None:
self._classifier.attach_stats_accumulator(stats_accumulator)
@@ -84,7 +84,7 @@ class CascadeRequestProcessor:
ctx.selected_model = self._target_models[idx]
await self._record_decision_source(ctx)
log.debug(
- "cascade pick: idx=%d target=%s model=%s",
+ "stage_router pick: idx=%d target=%s model=%s",
idx, ctx.selected_target, ctx.selected_model,
)
return request
@@ -93,8 +93,8 @@ class CascadeRequestProcessor:
try:
idx = await self._picker(ctx)
except Exception:
- log.exception("cascade picker raised; falling back to index 0 (weak)")
- return WEAK
+ log.exception("stage_router picker raised; falling back to index 0 (efficient)")
+ return EFFICIENT
return max(0, min(idx, self._max_index))
async def _record_decision_source(self, ctx: ProxyContext) -> None:
@@ -106,19 +106,19 @@ class CascadeRequestProcessor:
return
try:
await cast(Any, self._stats_accumulator).record_routing_decision(
- "cascade",
+ "stage_router",
source,
)
except Exception:
- log.debug("failed to record cascade decision source", exc_info=True)
+ log.debug("failed to record stage_router decision source", exc_info=True)
__all__ = [
"BUILTIN_PICKERS",
- "STRONG",
- "WEAK",
- "CascadeRequestProcessor",
+ "CAPABLE",
+ "EFFICIENT",
+ "StageRouterRequestProcessor",
"TierPicker",
- "pick_strong_default",
- "pick_weak_default",
+ "pick_capable_first",
+ "pick_efficient_first",
]
diff --git a/switchyard/lib/profiles/__init__.py b/switchyard/lib/profiles/__init__.py
index 39254bc51..e71f5dcae 100644
--- a/switchyard/lib/profiles/__init__.py
+++ b/switchyard/lib/profiles/__init__.py
@@ -3,8 +3,6 @@
"""Python profile abstractions matching the components-v2 design."""
-from switchyard.lib.profiles.cascade import CascadeProfileConfig
-from switchyard.lib.profiles.cascade_config import CascadeConfig, ClassifierConfig
from switchyard.lib.profiles.deterministic_routing_config import (
DeterministicRoutingConfig,
)
@@ -46,6 +44,8 @@ from switchyard.lib.profiles.random_routing import (
)
from switchyard.lib.profiles.random_routing_presets import RandomRoutingPresets
from switchyard.lib.profiles.routellm import RouteLLMConfig, RouteLLMProfileConfig
+from switchyard.lib.profiles.stage_router import StageRouterProfileConfig
+from switchyard.lib.profiles.stage_router_config import ClassifierConfig, StageRouterConfig
from switchyard.lib.profiles.switchyard_adapter import ProfileSwitchyard
from switchyard.lib.profiles.table import (
ProfileConfigError,
@@ -56,8 +56,8 @@ from switchyard.lib.profiles.table import (
from switchyard.lib.profiles.translate_profile_config import TranslateProfileConfig
__all__ = [
- "CascadeProfileConfig",
- "CascadeConfig",
+ "StageRouterProfileConfig",
+ "StageRouterConfig",
"ClassifierConfig",
"DeterministicRoutingConfig",
"DeterministicRoutingProfileConfig",
diff --git a/switchyard/lib/profiles/cascade.py b/switchyard/lib/profiles/stage_router.py
similarity index 67%
rename from switchyard/lib/profiles/cascade.py
rename to switchyard/lib/profiles/stage_router.py
index ee41ee3c1..8429832f1 100644
--- a/switchyard/lib/profiles/cascade.py
+++ b/switchyard/lib/profiles/stage_router.py
@@ -1,42 +1,42 @@
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
-"""Profile-owned signal cascade routing construction."""
+"""Profile-owned signal stage_router routing construction."""
from __future__ import annotations
import functools
from typing import Any, Self
-from switchyard.lib.processors.cascade import CascadeDecisionLog, TierClassifier
-from switchyard.lib.processors.cascade_request_processor import (
+from switchyard.lib.processors.reasoning_hint import model_accepts_reasoning_hint
+from switchyard.lib.processors.stage_router import StageRouterDecisionLog, TierClassifier
+from switchyard.lib.processors.stage_router_request_processor import (
BUILTIN_PICKERS,
- CascadeRequestProcessor,
+ StageRouterRequestProcessor,
TierPicker,
)
-from switchyard.lib.processors.reasoning_hint import model_accepts_reasoning_hint
-from switchyard.lib.profiles.cascade_config import (
- CascadeConfig,
+from switchyard.lib.profiles.chain import ComponentChainProfile
+from switchyard.lib.profiles.stage_router_config import (
ClassifierConfig,
+ StageRouterConfig,
)
-from switchyard.lib.profiles.chain import ComponentChainProfile
from switchyard.lib.profiles.table import profile_config
from switchyard.lib.roles import LLMBackend
-@profile_config("cascade")
-class CascadeProfileConfig:
- """Profile config wrapper for signal-driven strong/weak cascade profiles."""
+@profile_config("stage_router")
+class StageRouterProfileConfig:
+ """Profile config wrapper for signal-driven capable/efficient stage_router profiles."""
- config: CascadeConfig
+ config: StageRouterConfig
@classmethod
- def from_config(cls, config: CascadeConfig) -> Self:
+ def from_config(cls, config: StageRouterConfig) -> Self:
"""Create a profile config from the validated parsing model."""
return cls(config=config)
def build(self) -> ComponentChainProfile:
- """Build the cascade profile runtime."""
+ """Build the stage_router profile runtime."""
from switchyard.lib.backends.multi_llm_backend import build_multi_llm_backend
from switchyard_rust.components import DimensionCollector
@@ -45,18 +45,18 @@ class CascadeProfileConfig:
request_processors.append(
DimensionCollector(recent_window=config.signal_recent_window)
)
- decision_log = CascadeDecisionLog()
+ decision_log = StageRouterDecisionLog()
classifier = _build_classifier(config.classifier)
request_processors.append(
- CascadeRequestProcessor(
- targets=(config.weak, config.strong),
+ StageRouterRequestProcessor(
+ targets=(config.efficient, config.capable),
picker=_build_tier_picker(config, decision_log, classifier),
classifier=classifier,
decision_log=decision_log,
)
)
- backend: LLMBackend = build_multi_llm_backend((config.weak, config.strong))
+ backend: LLMBackend = build_multi_llm_backend((config.efficient, config.capable))
return ComponentChainProfile(
request_processors=request_processors,
@@ -66,11 +66,11 @@ class CascadeProfileConfig:
def _build_tier_picker(
- config: CascadeConfig,
- decision_log: CascadeDecisionLog,
+ config: StageRouterConfig,
+ decision_log: StageRouterDecisionLog,
classifier: TierClassifier | None,
) -> TierPicker:
- """Resolve the named cascade picker and bind its runtime knobs."""
+ """Resolve the named stage_router picker and bind its runtime knobs."""
picker_fn = BUILTIN_PICKERS.get(config.picker)
if picker_fn is None:
allowed = ", ".join(sorted(BUILTIN_PICKERS))
@@ -84,7 +84,7 @@ def _build_tier_picker(
def _build_classifier(config: ClassifierConfig | None) -> TierClassifier | None:
- """Build the optional LLM fallback classifier for cascade routing."""
+ """Build the optional LLM fallback classifier for stage_router routing."""
if config is None:
return None
return TierClassifier(
@@ -97,4 +97,4 @@ def _build_classifier(config: ClassifierConfig | None) -> TierClassifier | None:
)
-__all__ = ["CascadeProfileConfig"]
+__all__ = ["StageRouterProfileConfig"]
diff --git a/switchyard/lib/profiles/cascade_config.py b/switchyard/lib/profiles/stage_router_config.py
similarity index 83%
rename from switchyard/lib/profiles/cascade_config.py
rename to switchyard/lib/profiles/stage_router_config.py
index c3dc4a564..ae199d158 100644
--- a/switchyard/lib/profiles/cascade_config.py
+++ b/switchyard/lib/profiles/stage_router_config.py
@@ -1,7 +1,7 @@
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
-"""Declarative config for cascade profiles. See ``docs/cascade_routing.md``."""
+"""Declarative config for stage_router profiles. See ``docs/stage_router_routing.md``."""
from __future__ import annotations
@@ -14,7 +14,7 @@ from switchyard.lib.backends.llm_target import LlmTarget, coerce_llm_target
#: Picker mode accepted in YAML. The profile resolves it to a :class:`TierPicker`.
#: The name describes the *default tier* — what the picker returns when the
#: scorer is ambiguous and no classifier is configured.
-CascadePickerMode = Literal["cascade_strong_default", "cascade_weak_default"]
+StageRouterPickerMode = Literal["capable_first", "efficient_first"]
class ClassifierConfig(BaseModel):
@@ -34,18 +34,18 @@ class ClassifierConfig(BaseModel):
recent_turn_window: int = Field(default=3, ge=0)
-class CascadeConfig(BaseModel):
- """Configuration for the cascade-routing profile."""
+class StageRouterConfig(BaseModel):
+ """Configuration for the stage-router-routing profile."""
model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True, extra="forbid")
- strong: LlmTarget
- weak: LlmTarget
+ capable: LlmTarget
+ efficient: LlmTarget
#: Target ID the post-routing guard rewrites picks to when the picked
#: target has been evicted from the pool (e.g. after a context-window
- #: overflow). Must match either ``strong.id`` or ``weak.id``.
+ #: overflow). Must match either ``capable.id`` or ``efficient.id``.
fallback_target_on_evict: str
- picker: CascadePickerMode = "cascade_strong_default"
+ picker: StageRouterPickerMode = "capable_first"
#: Scorer confidence in ``[0, 1]`` below which the picker consults the
#: classifier (if configured) or returns its default tier. ``0.0`` forces
#: pure-deterministic routing; ``1.0`` forces every turn through the
@@ -60,12 +60,12 @@ class CascadeConfig(BaseModel):
classifier: ClassifierConfig | None = None
enable_stats: bool = True
- @field_validator("strong", "weak", mode="before")
+ @field_validator("capable", "efficient", mode="before")
@classmethod
def _coerce_target(cls, value: object, info: ValidationInfo) -> LlmTarget:
return coerce_llm_target(value, default_id=info.field_name or "target")
- @field_validator("strong", "weak")
+ @field_validator("capable", "efficient")
@classmethod
def _target_model_non_empty(cls, tier: LlmTarget) -> LlmTarget:
if not tier.model:
@@ -75,7 +75,7 @@ class CascadeConfig(BaseModel):
@field_validator("fallback_target_on_evict")
@classmethod
def _fallback_matches_existing_target(cls, value: str, info: ValidationInfo) -> str:
- valid_ids = {info.data[key].id for key in ("strong", "weak") if key in info.data}
+ valid_ids = {info.data[key].id for key in ("capable", "efficient") if key in info.data}
if value not in valid_ids:
raise ValueError(
f"fallback_target_on_evict={value!r} must match one of "
diff --git a/tests/e2e/test_evict_reroute_e2e.py b/tests/e2e/test_evict_reroute_e2e.py
index bf1dcc226..b620cd8d7 100644
--- a/tests/e2e/test_evict_reroute_e2e.py
+++ b/tests/e2e/test_evict_reroute_e2e.py
@@ -101,20 +101,24 @@ def _assert_eviction_stats(snapshot: dict) -> None:
@pytest.mark.timeout(120)
-async def test_cascade_evicts_weak_and_reroutes_to_strong(nvidia_api_key: str) -> None:
- """``type: cascade`` reroutes to ``strong`` when weak overflows."""
- from switchyard.lib.profiles import CascadeConfig, CascadeProfileConfig, ProfileSwitchyard
+async def test_stage_router_evicts_weak_and_reroutes_to_strong(nvidia_api_key: str) -> None:
+ """``type: stage_router`` reroutes to ``strong`` when weak overflows."""
+ from switchyard.lib.profiles import (
+ ProfileSwitchyard,
+ StageRouterConfig,
+ StageRouterProfileConfig,
+ )
stats = StatsAccumulator()
- config = CascadeConfig(
- strong=_strong_target(nvidia_api_key),
- weak=_weak_target(nvidia_api_key),
- picker="cascade_weak_default",
+ config = StageRouterConfig(
+ capable=_strong_target(nvidia_api_key),
+ efficient=_weak_target(nvidia_api_key),
+ picker="efficient_first",
confidence_threshold=0.0,
fallback_target_on_evict="strong",
)
switchyard = ProfileSwitchyard(
- CascadeProfileConfig.from_config(config)
+ StageRouterProfileConfig.from_config(config)
.build()
.with_runtime_components(
stats_accumulator=stats,
@@ -127,7 +131,7 @@ async def test_cascade_evicts_weak_and_reroutes_to_strong(nvidia_api_key: str) -
response = await client.post(
"/v1/chat/completions",
json={
- "model": "cascade-test",
+ "model": "stage_router-test",
"messages": [{"role": "user", "content": _OVERFLOW_TEXT}],
"max_tokens": 16,
},
diff --git a/tests/readme/test_readme.py b/tests/readme/test_readme.py
index bcf069f18..c07fdbad3 100644
--- a/tests/readme/test_readme.py
+++ b/tests/readme/test_readme.py
@@ -8,7 +8,7 @@ Companion to ``tests/getting_started/``. Three guards:
* the "Use as a Python library" snippet executes (via ``--markdown-docs`` +
the passthrough→noop fixture in ``conftest.py``);
* README route examples validate against the route-bundle schema;
-* canonical routing pages still build cascade and LLM-routing profile examples;
+* canonical routing pages still build stage_router and LLM-routing profile examples;
* every CLI subcommand / flag the README names still exists.
"""
@@ -28,7 +28,7 @@ from switchyard_rust.profiles import parse_profile_config_str
REPO_ROOT = Path(__file__).resolve().parents[2]
README_PATH = REPO_ROOT / "README.md"
ROUTING_DOC_PATHS = (
- REPO_ROOT / "docs" / "routing_algorithms" / "cascade_routing.md",
+ REPO_ROOT / "docs" / "routing_algorithms" / "stage_router_routing.md",
REPO_ROOT / "docs" / "routing_algorithms" / "llm_classifier_routing.md",
REPO_ROOT / "docs" / "routing_algorithms" / "overview.md",
)
@@ -101,7 +101,7 @@ def test_all_yaml_route_blocks_in_readme_validate_against_the_schema(
assert validated_routes, "no README yaml block parsed as a route bundle"
-def test_cascade_and_llm_routing_yaml_blocks_in_canonical_docs_build(
+def test_stage_router_and_llm_routing_yaml_blocks_in_canonical_docs_build(
monkeypatch: pytest.MonkeyPatch,
) -> None:
monkeypatch.setenv("OPENROUTER_API_KEY", "sk-or-readme")
@@ -119,7 +119,7 @@ def test_cascade_and_llm_routing_yaml_blocks_in_canonical_docs_build(
relevant_profile_ids = [
profile_id
for profile_id, profile in payload["profiles"].items()
- if profile.get("type") in {"cascade", "llm-routing"}
+ if profile.get("type") in {"stage_router", "llm-routing"}
]
if not relevant_profile_ids:
continue
diff --git a/tests/test_configure_model_picker_inputs.py b/tests/test_configure_model_picker_inputs.py
index 19e400e88..45d7589a9 100644
--- a/tests/test_configure_model_picker_inputs.py
+++ b/tests/test_configure_model_picker_inputs.py
@@ -11,7 +11,7 @@ Pins the two helpers that feed `wizard.select_model(...)`:
catalog in first-seen order.
Without these in the picker pipeline the wizard offers only the upstream
-catalog and the user can't pick a route key like `opus-ds-cascade` even when
+catalog and the user can't pick a route key like `opus-ds-stage_router` even when
their YAML declares it.
"""
@@ -28,13 +28,13 @@ def test_empty_or_none_bundle_returns_empty() -> None:
def test_extracts_route_keys_and_tier_models() -> None:
- """Cascade + deterministic routes contribute the route key plus
+ """StageRouter + deterministic routes contribute the route key plus
strong/weak tier models. Classifier is intentionally skipped (internal)."""
bundle = {
"routes": {
- "opus-ds-cascade": {
- "type": "cascade",
- "picker": "cascade_strong_default",
+ "opus-ds-stage_router": {
+ "type": "stage_router",
+ "picker": "capable_first",
"fallback_target_on_evict": "strong",
"strong": {"model": "aws/anthropic/bedrock-claude-opus-4-7"},
"weak": {"model": "nvidia/deepseek-ai/evals-deepseek-v4-pro"},
@@ -51,7 +51,7 @@ def test_extracts_route_keys_and_tier_models() -> None:
},
}
assert _routing_profile_model_ids(bundle) == [
- "opus-ds-cascade",
+ "opus-ds-stage_router",
"aws/anthropic/bedrock-claude-opus-4-7",
"nvidia/deepseek-ai/evals-deepseek-v4-pro",
"opus-ds-classifier",
@@ -107,14 +107,14 @@ def test_plan_execute_planner_executor_extracted() -> None:
def test_merge_candidate_ids_dedupes_preserves_first_seen_order() -> None:
"""Routing-profile entries first, then upstream catalog. Duplicates from
later sources drop."""
- routing = ["opus-ds-cascade", "aws/anthropic/bedrock-claude-opus-4-7"]
+ routing = ["opus-ds-stage_router", "aws/anthropic/bedrock-claude-opus-4-7"]
upstream = [
"openai/gpt-5.2",
"aws/anthropic/bedrock-claude-opus-4-7", # dup with routing[1]
"nvidia/nvidia/nemotron-3-super-120b-long-ctx",
]
assert _merge_candidate_ids(routing, upstream) == [
- "opus-ds-cascade",
+ "opus-ds-stage_router",
"aws/anthropic/bedrock-claude-opus-4-7",
"openai/gpt-5.2",
"nvidia/nvidia/nemotron-3-super-120b-long-ctx",
diff --git a/tests/test_profile_migration.py b/tests/test_profile_migration.py
index 98090ffe9..e0a14d94f 100644
--- a/tests/test_profile_migration.py
+++ b/tests/test_profile_migration.py
@@ -259,36 +259,36 @@ profiles:
"""
-def _cascade_profile_config(base_url: str) -> str:
+def _stage_router_profile_config(base_url: str) -> str:
return f"""
targets:
strong:
model: provider/strong
format: openai
- base_url: "{base_url}/v2-cascade/v1"
+ base_url: "{base_url}/v2-stage_router/v1"
api_key: test-key
weak:
model: provider/weak
format: openai
- base_url: "{base_url}/v2-cascade/v1"
+ base_url: "{base_url}/v2-stage_router/v1"
api_key: test-key
classifier:
model: provider/classifier
format: openai
- base_url: "{base_url}/v2-cascade-classifier/v1"
+ base_url: "{base_url}/v2-stage_router-classifier/v1"
api_key: test-key
profiles:
- cascade-profile:
- type: cascade
- strong: strong
- weak: weak
+ stage_router-profile:
+ type: stage_router
+ capable: strong
+ efficient: weak
fallback_target_on_evict: strong
- picker: cascade_strong_default
+ picker: capable_first
confidence_threshold: 0.7
classifier:
model: provider/classifier
api_key: test-key
- base_url: "{base_url}/v2-cascade-classifier/v1"
+ base_url: "{base_url}/v2-stage_router-classifier/v1"
"""
@@ -475,30 +475,30 @@ async def test_llm_routing_profile_routes_with_strict_classifier(
assert "response_format" not in classifier_body
-async def test_cascade_profile_routes_with_classifier(
+async def test_stage_router_profile_routes_with_classifier(
openai_stub: _OpenAICompatStub,
) -> None:
openai_stub.respond_json(
200,
_completion_payload(
"provider/classifier",
- "/v2-cascade-classifier/v1/chat/completions",
- json.dumps({"tier": "weak"}),
+ "/v2-stage_router-classifier/v1/chat/completions",
+ json.dumps({"tier": "efficient"}),
),
)
profile = _profile_runner(
- _cascade_profile_config(openai_stub.base_url),
- "cascade-profile",
+ _stage_router_profile_config(openai_stub.base_url),
+ "stage_router-profile",
)
response = await profile.run(
- ChatRequest.openai_chat(_chat_payload("cascade-profile")),
+ ChatRequest.openai_chat(_chat_payload("stage_router-profile")),
)
assert response.body["model"] == "provider/weak"
assert [call["path"] for call in openai_stub.requests] == [
- "/v2-cascade-classifier/v1/chat/completions",
- "/v2-cascade/v1/chat/completions",
+ "/v2-stage_router-classifier/v1/chat/completions",
+ "/v2-stage_router/v1/chat/completions",
]
assert [call["body"]["model"] for call in openai_stub.requests] == [
"provider/classifier",
diff --git a/tests/test_route_bundle.py b/tests/test_route_bundle.py
index 80cb15f79..a4435b7f5 100644
--- a/tests/test_route_bundle.py
+++ b/tests/test_route_bundle.py
@@ -1053,15 +1053,15 @@ class TestDeterministicRouteType:
) is True
-class TestCascadeRouteType:
- """`type: cascade` wires the cascade-routing chain via YAML."""
+class TestStageRouterRouteType:
+ """`type: stage_router` wires the stage-router-routing chain via YAML."""
def _bundle(self) -> dict:
return {
"routes": {
- "myrouter/cascade": {
- "type": "cascade",
- "picker": "cascade_strong_default",
+ "myrouter/stage_router": {
+ "type": "stage_router",
+ "picker": "capable_first",
"strong": {
"id": "strong",
"model": "anthropic/claude-opus-4-7",
@@ -1085,10 +1085,10 @@ class TestCascadeRouteType:
def test_registers_route_key_and_tier_passthroughs(self):
from switchyard.cli.route_bundle import build_route_bundle_table
table = build_route_bundle_table(self._bundle())
- # Unified ordering: route key first as the cascade virtual id,
+ # Unified ordering: route key first as the stage-router virtual id,
# tier models registered as direct passthroughs after.
assert table.registered_models() == [
- "myrouter/cascade",
+ "myrouter/stage_router",
"anthropic/claude-opus-4-7",
"nvidia/nemotron-3-super",
]
@@ -1099,7 +1099,7 @@ class TestCascadeRouteType:
build_route_bundle_table,
)
bundle = self._bundle()
- del bundle["routes"]["myrouter/cascade"]["strong"]
+ del bundle["routes"]["myrouter/stage_router"]["strong"]
with pytest.raises(RouteBundleConfigError) as exc:
build_route_bundle_table(bundle)
assert "strong" in str(exc.value)
@@ -1110,7 +1110,7 @@ class TestCascadeRouteType:
build_route_bundle_table,
)
bundle = self._bundle()
- del bundle["routes"]["myrouter/cascade"]["weak"]
+ del bundle["routes"]["myrouter/stage_router"]["weak"]
with pytest.raises(RouteBundleConfigError) as exc:
build_route_bundle_table(bundle)
assert "weak" in str(exc.value)
@@ -1121,7 +1121,7 @@ class TestCascadeRouteType:
build_route_bundle_table,
)
bundle = self._bundle()
- bundle["routes"]["myrouter/cascade"]["picker"] = "no-such-picker"
+ bundle["routes"]["myrouter/stage_router"]["picker"] = "no-such-picker"
with pytest.raises((RouteBundleConfigError, ValueError)) as exc:
build_route_bundle_table(bundle)
assert "picker" in str(exc.value).lower()
@@ -1132,7 +1132,7 @@ class TestCascadeRouteType:
build_route_bundle_table,
)
bundle = self._bundle()
- del bundle["routes"]["myrouter/cascade"]["fallback_target_on_evict"]
+ del bundle["routes"]["myrouter/stage_router"]["fallback_target_on_evict"]
# Pydantic ValidationError extends ValueError; route_bundle does not
# additionally wrap it for missing-field cases.
with pytest.raises((RouteBundleConfigError, ValueError)) as exc:
@@ -1145,7 +1145,7 @@ class TestCascadeRouteType:
build_route_bundle_table,
)
bundle = self._bundle()
- bundle["routes"]["myrouter/cascade"]["fallback_target_on_evict"] = "nope"
+ bundle["routes"]["myrouter/stage_router"]["fallback_target_on_evict"] = "nope"
with pytest.raises((RouteBundleConfigError, ValueError)) as exc:
build_route_bundle_table(bundle)
assert "fallback_target_on_evict" in str(exc.value)
@@ -1156,18 +1156,18 @@ class TestCascadeRouteType:
build_route_bundle_table,
)
bundle = self._bundle()
- bundle["routes"]["myrouter/cascade"]["bogus_field"] = 1
+ bundle["routes"]["myrouter/stage_router"]["bogus_field"] = 1
with pytest.raises(RouteBundleConfigError) as exc:
build_route_bundle_table(bundle)
assert "bogus_field" in str(exc.value)
def test_accepts_both_pickers(self):
from switchyard.cli.route_bundle import build_route_bundle_table
- for picker in ("cascade_strong_default", "cascade_weak_default"):
+ for picker in ("capable_first", "efficient_first"):
bundle = self._bundle()
- bundle["routes"]["myrouter/cascade"]["picker"] = picker
+ bundle["routes"]["myrouter/stage_router"]["picker"] = picker
table = build_route_bundle_table(bundle)
- assert "myrouter/cascade" in table.registered_models()
+ assert "myrouter/stage_router" in table.registered_models()
def test_rejects_removed_legacy_knobs(self):
from switchyard.cli.route_bundle import (
@@ -1175,7 +1175,7 @@ class TestCascadeRouteType:
build_route_bundle_table,
)
bundle = self._bundle()
- bundle["routes"]["myrouter/cascade"]["escalate_at"] = 0.5
+ bundle["routes"]["myrouter/stage_router"]["escalate_at"] = 0.5
with pytest.raises(RouteBundleConfigError) as exc:
build_route_bundle_table(bundle)
assert "escalate_at" in str(exc.value)
@@ -1183,26 +1183,26 @@ class TestCascadeRouteType:
def test_classifier_block_is_optional(self):
from switchyard.cli.route_bundle import build_route_bundle_table
bundle = self._bundle()
- bundle["routes"]["myrouter/cascade"]["classifier"] = {
+ bundle["routes"]["myrouter/stage_router"]["classifier"] = {
"model": "nvidia/deepseek-ai/deepseek-v4-flash",
"api_key": "sk-classifier",
"base_url": "https://classifier.invalid/v1",
}
table = build_route_bundle_table(bundle)
- assert "myrouter/cascade" in table.registered_models()
+ assert "myrouter/stage_router" in table.registered_models()
def test_signal_recent_window_accepted(self):
from switchyard.cli.route_bundle import build_route_bundle_table
bundle = self._bundle()
- bundle["routes"]["myrouter/cascade"]["signal_recent_window"] = 5
+ bundle["routes"]["myrouter/stage_router"]["signal_recent_window"] = 5
table = build_route_bundle_table(bundle)
- assert "myrouter/cascade" in table.registered_models()
+ assert "myrouter/stage_router" in table.registered_models()
def test_classifier_inherits_route_defaults(self):
from switchyard.cli.route_bundle import build_route_bundle_table
- from switchyard.lib.processors.cascade import TierClassifier
- from switchyard.lib.processors.cascade_request_processor import (
- CascadeRequestProcessor,
+ from switchyard.lib.processors.stage_router import TierClassifier
+ from switchyard.lib.processors.stage_router_request_processor import (
+ StageRouterRequestProcessor,
)
table = build_route_bundle_table({
@@ -1213,9 +1213,9 @@ class TestCascadeRouteType:
"timeout": 12.0,
},
"routes": {
- "defaults/cascade": {
- "type": "cascade",
- "picker": "cascade_strong_default",
+ "defaults/stage_router": {
+ "type": "stage_router",
+ "picker": "capable_first",
"fallback_target_on_evict": "strong",
"strong": {"id": "strong", "model": "strong/model"},
"weak": {"id": "weak", "model": "weak/model"},
@@ -1223,10 +1223,10 @@ class TestCascadeRouteType:
},
},
})
- switchyard = table.lookup_switchyard("defaults/cascade")
+ switchyard = table.lookup_switchyard("defaults/stage_router")
processor = next(
c for c in switchyard.iter_components()
- if isinstance(c, CascadeRequestProcessor)
+ if isinstance(c, StageRouterRequestProcessor)
)
classifier = processor._picker.keywords["classifier"]
@@ -1235,10 +1235,10 @@ class TestCascadeRouteType:
assert classifier._recent_turn_window == 3
async def test_classifier_usage_records_into_route_bundle_stats(self) -> None:
- """Route-bundle cascade classifiers write usage into shared stats."""
+ """Route-bundle stage_router classifiers write usage into shared stats."""
from switchyard.cli.route_bundle import build_route_bundle_table
- from switchyard.lib.processors.cascade_request_processor import (
- CascadeRequestProcessor,
+ from switchyard.lib.processors.stage_router_request_processor import (
+ StageRouterRequestProcessor,
)
from switchyard.lib.profiles.chain import ComponentChainProfile
from switchyard.lib.stats_accumulator import StatsAccumulator
@@ -1256,7 +1256,7 @@ class TestCascadeRouteType:
choices=[
SimpleNamespace(
message=SimpleNamespace(
- content=json.dumps({"tier": "strong"}),
+ content=json.dumps({"tier": "capable"}),
),
)
],
@@ -1269,26 +1269,26 @@ class TestCascadeRouteType:
stats = StatsAccumulator()
bundle = self._bundle()
- bundle["routes"]["myrouter/cascade"]["confidence_threshold"] = 1.0
- bundle["routes"]["myrouter/cascade"]["classifier"] = {
+ bundle["routes"]["myrouter/stage_router"]["confidence_threshold"] = 1.0
+ bundle["routes"]["myrouter/stage_router"]["classifier"] = {
"model": "classifier/model",
"api_key": "sk-classifier",
"base_url": "https://classifier.invalid/v1",
}
table = build_route_bundle_table(bundle, stats_accumulator=stats)
- switchyard = table.lookup_switchyard("myrouter/cascade")
+ switchyard = table.lookup_switchyard("myrouter/stage_router")
assert isinstance(switchyard._profile, ComponentChainProfile)
processor = next(
component
for component in switchyard.iter_components()
- if isinstance(component, CascadeRequestProcessor)
+ if isinstance(component, StageRouterRequestProcessor)
)
assert processor._classifier is not None
client = _ClassifierClient()
processor._classifier._client = client # type: ignore[assignment]
processed = await switchyard._profile.process(ProfileInput(ChatRequest.openai_chat({
- "model": "myrouter/cascade",
+ "model": "myrouter/stage_router",
"messages": [{"role": "user", "content": "hello"}],
"max_tokens": 8,
})))
@@ -1301,7 +1301,7 @@ class TestCascadeRouteType:
assert snapshot["classifier"]["models"]["classifier/model"]["prompt_tokens"] == 13
assert snapshot["classifier"]["models"]["classifier/model"]["completion_tokens"] == 5
assert snapshot["classifier"]["models"]["classifier/model"]["cached_tokens"] == 2
- assert snapshot["routing_decisions"]["cascade"]["llm-classifier"] == 1
+ assert snapshot["routing_decisions"]["stage_router"]["llm-classifier"] == 1
class TestPlanExecuteRouteType:
@@ -1388,12 +1388,12 @@ class TestPlanExecuteRouteType:
assert not any(isinstance(c, StatsResponseProcessor) for c in components)
-def test_cascade_route_hydrates_tier_catalogs(
+def test_stage_router_route_hydrates_tier_catalogs(
monkeypatch: pytest.MonkeyPatch,
) -> None:
- """``type: cascade`` registers each tier's catalog alongside the
+ """``type: stage_router`` registers each tier's catalog alongside the
routing-policy chain — strong/weak as direct passthroughs, plus the
- route's YAML key as the cascade virtual id.
+ route's YAML key as the stage-router virtual id.
The classifier tier (when present) is intentionally NOT discovered — it's
an internal-only LLM call, not a user-facing target.
@@ -1409,9 +1409,9 @@ def test_cascade_route_hydrates_tier_catalogs(
table = build_route_bundle_table({
"routes": {
- "opus-ds-cascade": {
- "type": "cascade",
- "picker": "cascade_strong_default",
+ "opus-ds-stage_router": {
+ "type": "stage_router",
+ "picker": "capable_first",
"fallback_target_on_evict": "strong",
"strong": {
"id": "strong",
@@ -1429,10 +1429,10 @@ def test_cascade_route_hydrates_tier_catalogs(
},
})
- # Unified ordering: cascade virtual id first, then tier models + catalog.
+ # Unified ordering: stage_router virtual id first, then tier models + catalog.
# The classifier tier is absent here AND would be skipped even if present.
assert table.registered_models() == [
- "opus-ds-cascade",
+ "opus-ds-stage_router",
"strong/model",
"weak/model",
"catalog/strong-extra",
@@ -1443,7 +1443,7 @@ def test_cascade_route_hydrates_tier_catalogs(
def test_deterministic_route_hydrates_tier_catalogs(
monkeypatch: pytest.MonkeyPatch,
) -> None:
- """``type: deterministic`` — same catalog-hydration shape as cascade,
+ """``type: deterministic`` — same catalog-hydration shape as stage_router,
with the classifier tier intentionally skipped."""
monkeypatch.setattr(
"switchyard.cli.route_bundle.fetch_model_ids",
@@ -1494,12 +1494,12 @@ def test_deterministic_route_hydrates_tier_catalogs(
def test_route_bundle_keeps_first_multi_target_route_as_default() -> None:
- """Cascade/deterministic discovery merges preserve the first YAML route."""
+ """StageRouter/deterministic discovery merges preserve the first YAML route."""
table = build_route_bundle_table({
"routes": {
- "first-cascade": {
- "type": "cascade",
- "picker": "cascade_strong_default",
+ "first-stage_router": {
+ "type": "stage_router",
+ "picker": "capable_first",
"fallback_target_on_evict": "strong",
"strong": {
"id": "strong",
@@ -1514,9 +1514,9 @@ def test_route_bundle_keeps_first_multi_target_route_as_default() -> None:
"base_url": "https://first-weak.example/v1",
},
},
- "second-cascade": {
- "type": "cascade",
- "picker": "cascade_strong_default",
+ "second-stage_router": {
+ "type": "stage_router",
+ "picker": "capable_first",
"fallback_target_on_evict": "strong",
"strong": {
"id": "strong",
@@ -1534,7 +1534,7 @@ def test_route_bundle_keeps_first_multi_target_route_as_default() -> None:
},
})
- assert table.default_model() == "first-cascade"
+ assert table.default_model() == "first-stage_router"
_AFFINITY_DET_ROUTE = {
diff --git a/tests/test_routing_banner.py b/tests/test_routing_banner.py
index 854d99eb6..390db9331 100644
--- a/tests/test_routing_banner.py
+++ b/tests/test_routing_banner.py
@@ -22,10 +22,10 @@ from switchyard.cli.launchers.launcher_runtime import (
)
from switchyard.cli.launchers.openclaw_launcher import launch_openclaw
-_CASCADE_YAML = textwrap.dedent("""\
+_STAGE_ROUTER_YAML = textwrap.dedent("""\
routes:
my_route:
- type: cascade
+ type: stage_router
confidence_threshold: 0.7
strong:
model: strong-model/v1
@@ -48,12 +48,12 @@ class TestStrategyHelpers:
"""passthrough_strategy_summary returns 'passthrough → <model>'."""
assert passthrough_strategy_summary("my/model") == "passthrough → my/model"
- def test_routing_profiles_cascade(self, tmp_path):
- """routing_profiles_strategy_summary describes the default cascade route."""
+ def test_routing_profiles_stage_router(self, tmp_path):
+ """routing_profiles_strategy_summary describes the default stage_router route."""
p = tmp_path / "profiles.yaml"
- p.write_text(_CASCADE_YAML)
+ p.write_text(_STAGE_ROUTER_YAML)
result = routing_profiles_strategy_summary(str(p), "my_route")
- assert result == "cascade: strong=strong-model/v1, weak=weak-model/v1, llm-classifier=clf-model/v1, confidence_threshold=0.7"
+ assert result == "stage_router: strong=strong-model/v1, weak=weak-model/v1, llm-classifier=clf-model/v1, confidence_threshold=0.7"
def test_routing_profiles_passthrough_type(self, tmp_path):
"""routing_profiles_strategy_summary describes a passthrough-type route."""
@@ -153,7 +153,7 @@ class TestCodexRoutingBanner:
def test_routing_profiles_banner(self, tmp_path):
"""launch_codex describes the default route type for routing-profiles launch."""
profiles_path = tmp_path / "profiles.yaml"
- profiles_path.write_text(_CASCADE_YAML)
+ profiles_path.write_text(_STAGE_ROUTER_YAML)
captured: dict = {}
with (
_patch_codex_runner(captured),
@@ -171,7 +171,7 @@ class TestCodexRoutingBanner:
codex_args=[],
routing_profiles=str(profiles_path),
)
- assert _captured_strategy(captured) == "cascade: strong=strong-model/v1, weak=weak-model/v1, llm-classifier=clf-model/v1, confidence_threshold=0.7"
+ assert _captured_strategy(captured) == "stage_router: strong=strong-model/v1, weak=weak-model/v1, llm-classifier=clf-model/v1, confidence_threshold=0.7"
class TestOpenclawRoutingBanner:
@@ -192,7 +192,7 @@ class TestOpenclawRoutingBanner:
def test_routing_profiles_banner(self, tmp_path):
"""launch_openclaw describes the default route type for routing-profiles launch."""
profiles_path = tmp_path / "profiles.yaml"
- profiles_path.write_text(_CASCADE_YAML)
+ profiles_path.write_text(_STAGE_ROUTER_YAML)
captured: dict = {}
with (
_patch_openclaw_runner(captured),
@@ -210,7 +210,7 @@ class TestOpenclawRoutingBanner:
openclaw_args=[],
routing_profiles=str(profiles_path),
)
- assert _captured_strategy(captured) == "cascade: strong=strong-model/v1, weak=weak-model/v1, llm-classifier=clf-model/v1, confidence_threshold=0.7"
+ assert _captured_strategy(captured) == "stage_router: strong=strong-model/v1, weak=weak-model/v1, llm-classifier=clf-model/v1, confidence_threshold=0.7"
class TestClaudeRoutingBanner:
@@ -231,7 +231,7 @@ class TestClaudeRoutingBanner:
def test_routing_profiles_banner(self, tmp_path):
"""launch_claude describes the default route type for routing-profiles launch."""
profiles_path = tmp_path / "profiles.yaml"
- profiles_path.write_text(_CASCADE_YAML)
+ profiles_path.write_text(_STAGE_ROUTER_YAML)
captured: dict = {}
with (
_patch_claude_runner(captured),
@@ -249,4 +249,4 @@ class TestClaudeRoutingBanner:
claude_args=[],
routing_profiles=str(profiles_path),
)
- assert _captured_strategy(captured) == "cascade: strong=strong-model/v1, weak=weak-model/v1, llm-classifier=clf-model/v1, confidence_threshold=0.7"
+ assert _captured_strategy(captured) == "stage_router: strong=strong-model/v1, weak=weak-model/v1, llm-classifier=clf-model/v1, confidence_threshold=0.7"
diff --git a/tests/test_serve_profile_config.py b/tests/test_serve_profile_config.py
index 1c077834c..ba5d5a997 100644
--- a/tests/test_serve_profile_config.py
+++ b/tests/test_serve_profile_config.py
@@ -42,12 +42,12 @@ profiles:
fast:
type: passthrough
target: weak
- smart-cascade:
- type: cascade
- strong: strong
- weak: weak
+ smart-stage-router:
+ type: stage_router
+ capable: strong
+ efficient: weak
fallback_target_on_evict: strong
- picker: cascade_strong_default
+ picker: capable_first
confidence_threshold: 0.7
"""
@@ -156,7 +156,7 @@ def _write(tmp_path: Path, text: str, name: str = "profiles.yaml") -> Path:
def test_dry_run_validates_rust_profiles_and_direct_targets(tmp_path: Path) -> None:
- # passthrough + cascade + the two targets (directly addressable).
+ # passthrough + stage_router + the two targets (directly addressable).
path = _write(tmp_path, _RUST_CONFIG)
# dry_run loads, resolves, and builds the registry, then returns without
# binding a socket. No exception == a servable config.
diff --git a/tests/test_cascade_classifier.py b/tests/test_stage_router_classifier.py
similarity index 89%
rename from tests/test_cascade_classifier.py
rename to tests/test_stage_router_classifier.py
index 6c95e0ce4..92518f8cf 100644
--- a/tests/test_cascade_classifier.py
+++ b/tests/test_stage_router_classifier.py
@@ -16,10 +16,10 @@ from typing import Any
import pytest
-from switchyard.lib.processors.cascade.classifier import (
+from switchyard.lib.processors.stage_router.classifier import (
+ CAPABLE_TIER,
+ EFFICIENT_TIER,
RECENT_MESSAGES_KEY,
- STRONG_TIER,
- WEAK_TIER,
TierClassifier,
)
from switchyard_rust.components import DimensionCollector, get_tool_result_signal
@@ -66,23 +66,23 @@ async def _build_signal() -> Any:
@pytest.mark.asyncio
-async def test_returns_strong_on_valid_strong_response():
+async def test_returns_capable_on_valid_capable_response():
ctx, signal = await _build_signal()
classifier = TierClassifier(
model="m", api_key="k",
- client=_StubClient(_Resp(content=json.dumps({"tier": "strong"}))),
+ client=_StubClient(_Resp(content=json.dumps({"tier": "capable"}))),
)
- assert await classifier.classify(ctx, signal) == STRONG_TIER
+ assert await classifier.classify(ctx, signal) == CAPABLE_TIER
@pytest.mark.asyncio
-async def test_returns_weak_on_valid_weak_response():
+async def test_returns_efficient_on_valid_efficient_response():
ctx, signal = await _build_signal()
classifier = TierClassifier(
model="m", api_key="k",
- client=_StubClient(_Resp(content=json.dumps({"tier": "weak"}))),
+ client=_StubClient(_Resp(content=json.dumps({"tier": "efficient"}))),
)
- assert await classifier.classify(ctx, signal) == WEAK_TIER
+ assert await classifier.classify(ctx, signal) == EFFICIENT_TIER
@pytest.mark.asyncio
@@ -142,7 +142,7 @@ async def test_default_window_omits_recent_messages():
async def acompletion(self, **kwargs: object) -> _Resp:
self.calls += 1
captured["messages"] = kwargs["messages"]
- return _Resp(content=json.dumps({"tier": "strong"}))
+ return _Resp(content=json.dumps({"tier": "capable"}))
classifier = TierClassifier(
model="m", api_key="k", recent_turn_window=0, client=_Recorder(),
@@ -163,7 +163,7 @@ async def test_disable_reasoning_passes_enable_thinking_false_extra_body():
class _Recorder:
async def acompletion(self, **kwargs: object) -> _Resp:
captured.update(kwargs)
- return _Resp(content=json.dumps({"tier": "weak"}))
+ return _Resp(content=json.dumps({"tier": "efficient"}))
classifier = TierClassifier(model="m", api_key="k", client=_Recorder())
await classifier.classify(ctx, signal)
@@ -183,7 +183,7 @@ async def test_disable_reasoning_false_omits_extra_body():
class _Recorder:
async def acompletion(self, **kwargs: object) -> _Resp:
captured.update(kwargs)
- return _Resp(content=json.dumps({"tier": "strong"}))
+ return _Resp(content=json.dumps({"tier": "capable"}))
classifier = TierClassifier(
model="m", api_key="k", disable_reasoning=False, client=_Recorder(),
@@ -209,7 +209,7 @@ async def test_window_4_appends_last_four_messages():
class _Recorder:
async def acompletion(self, **kwargs: object) -> _Resp:
captured["messages"] = kwargs["messages"]
- return _Resp(content=json.dumps({"tier": "weak"}))
+ return _Resp(content=json.dumps({"tier": "efficient"}))
classifier = TierClassifier(
model="m", api_key="k", recent_turn_window=4, client=_Recorder(),
diff --git a/tests/test_cascade_pickers.py b/tests/test_stage_router_pickers.py
similarity index 73%
rename from tests/test_cascade_pickers.py
rename to tests/test_stage_router_pickers.py
index 597e9635b..3fa6f3fd6 100644
--- a/tests/test_cascade_pickers.py
+++ b/tests/test_stage_router_pickers.py
@@ -1,23 +1,23 @@
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
-"""Behavioural tests for the cascade pickers."""
+"""Behavioural tests for the stage_router pickers."""
from dataclasses import dataclass
from typing import Any
import pytest
-from switchyard.lib.processors.cascade import (
- STRONG,
- WEAK,
- CascadeDecisionLog,
+from switchyard.lib.processors.stage_router import (
+ CAPABLE,
+ EFFICIENT,
+ StageRouterDecisionLog,
TierClassifier,
)
-from switchyard.lib.processors.cascade.decision_log import CONTEXT_KEY
-from switchyard.lib.processors.cascade.picker import (
- pick_strong_default,
- pick_weak_default,
+from switchyard.lib.processors.stage_router.decision_log import CONTEXT_KEY
+from switchyard.lib.processors.stage_router.picker import (
+ pick_capable_first,
+ pick_efficient_first,
)
from switchyard_rust.components import DimensionCollector
from switchyard_rust.core import ChatRequest, ProxyContext
@@ -79,28 +79,28 @@ def _stub_classifier(tier: str | None) -> TierClassifier:
@pytest.mark.asyncio
-async def test_critical_severity_overrides_to_strong():
+async def test_critical_severity_overrides_to_capable():
ctx = await _ctx([
_msg_tool_result("Out of memory: cannot allocate memory"),
{"role": "user", "content": "retry"},
])
- assert await pick_strong_default(ctx, confidence_threshold=0.7) == STRONG
- assert await pick_weak_default(ctx, confidence_threshold=0.7) == STRONG
+ assert await pick_capable_first(ctx, confidence_threshold=0.7) == CAPABLE
+ assert await pick_efficient_first(ctx, confidence_threshold=0.7) == CAPABLE
@pytest.mark.asyncio
-async def test_tests_passed_with_edits_drops_to_weak():
+async def test_tests_passed_with_edits_drops_to_efficient():
messages = [_msg_tool_call("Edit")] * 3 + [_msg_tool_result("all tests passed")] * 3
messages += [{"role": "user", "content": "ok continue"}] * 12
ctx = await _ctx(messages)
- assert await pick_strong_default(ctx, confidence_threshold=0.7) == WEAK
+ assert await pick_capable_first(ctx, confidence_threshold=0.7) == EFFICIENT
@pytest.mark.asyncio
async def test_no_signal_returns_default_tier():
ctx = ProxyContext() # signal not stamped
- assert await pick_strong_default(ctx, confidence_threshold=0.7) == STRONG
- assert await pick_weak_default(ctx, confidence_threshold=0.7) == WEAK
+ assert await pick_capable_first(ctx, confidence_threshold=0.7) == CAPABLE
+ assert await pick_efficient_first(ctx, confidence_threshold=0.7) == EFFICIENT
@pytest.mark.asyncio
@@ -108,10 +108,10 @@ async def test_low_confidence_consults_classifier_when_configured():
"""Empty trajectory yields confidence 0.0 — picker must call the classifier."""
messages = [{"role": "user", "content": "hi"}]
ctx = await _ctx(messages)
- classifier = _stub_classifier(tier="weak")
- assert await pick_strong_default(
+ classifier = _stub_classifier(tier="efficient")
+ assert await pick_capable_first(
ctx, confidence_threshold=0.7, classifier=classifier,
- ) == WEAK
+ ) == EFFICIENT
assert classifier._client.calls == 1 # type: ignore[attr-defined]
@@ -119,8 +119,8 @@ async def test_low_confidence_consults_classifier_when_configured():
async def test_low_confidence_falls_back_to_default_without_classifier():
messages = [{"role": "user", "content": "hi"}]
ctx = await _ctx(messages)
- assert await pick_strong_default(ctx, confidence_threshold=0.7) == STRONG
- assert await pick_weak_default(ctx, confidence_threshold=0.7) == WEAK
+ assert await pick_capable_first(ctx, confidence_threshold=0.7) == CAPABLE
+ assert await pick_efficient_first(ctx, confidence_threshold=0.7) == EFFICIENT
@pytest.mark.asyncio
@@ -129,19 +129,19 @@ async def test_classifier_fall_open_on_unknown_tier():
messages = [{"role": "user", "content": "hi"}]
ctx = await _ctx(messages)
classifier = _stub_classifier(tier=None)
- assert await pick_strong_default(
+ assert await pick_capable_first(
ctx, confidence_threshold=0.7, classifier=classifier,
- ) == STRONG
+ ) == CAPABLE
@pytest.mark.asyncio
async def test_threshold_zero_skips_classifier_entirely():
- """``confidence_threshold=0`` means accept every scorer verdict, however weak."""
+ """``confidence_threshold=0`` means accept every scorer verdict, however efficient."""
messages = [{"role": "user", "content": "hi"}]
ctx = await _ctx(messages)
- classifier = _stub_classifier(tier="strong")
+ classifier = _stub_classifier(tier="capable")
# Empty trajectory → scorer near zero, default sign decides; classifier not consulted.
- await pick_strong_default(ctx, confidence_threshold=0.0, classifier=classifier)
+ await pick_capable_first(ctx, confidence_threshold=0.0, classifier=classifier)
assert classifier._client.calls == 0 # type: ignore[attr-defined]
@@ -151,21 +151,21 @@ async def test_dimensions_branch_routes_by_scorer_sign():
A single TodoWrite in the recent window pushes ``planning_active`` to
1.0 (weight -0.70) — that alone clears the 0.7 confidence threshold,
- so ``_pick`` takes the dimensions branch and returns WEAK by sign
+ so ``_pick`` takes the dimensions branch and returns EFFICIENT by sign
without consulting the classifier.
"""
- log = CascadeDecisionLog()
- classifier = _stub_classifier(tier="strong") # would push STRONG if reached
+ log = StageRouterDecisionLog()
+ classifier = _stub_classifier(tier="capable") # would push CAPABLE if reached
ctx = await _ctx([
_msg_tool_call("TodoWrite"),
_msg_tool_result("ok"),
{"role": "user", "content": "next"},
])
- tier = await pick_strong_default(
+ tier = await pick_capable_first(
ctx, confidence_threshold=0.7, classifier=classifier, decision_log=log,
)
assert ctx.metadata[CONTEXT_KEY] == "dimensions"
- assert tier == WEAK # negative score → WEAK regardless of strong-default fallback
+ assert tier == EFFICIENT # negative score → EFFICIENT regardless of capable-first fallback
assert classifier._client.calls == 0 # type: ignore[attr-defined]
assert log.snapshot()["dimensions"] == 1
@@ -173,24 +173,24 @@ async def test_dimensions_branch_routes_by_scorer_sign():
@pytest.mark.asyncio
async def test_decision_log_counts_sources():
"""Each decision path increments exactly one bucket in the shared log."""
- log = CascadeDecisionLog()
- # override path: critical severity → STRONG, source=override
+ log = StageRouterDecisionLog()
+ # override path: critical severity → CAPABLE, source=override
ctx_critical = await _ctx([
_msg_tool_result("Out of memory: cannot allocate memory"),
{"role": "user", "content": "retry"},
])
- await pick_strong_default(ctx_critical, confidence_threshold=0.7, decision_log=log)
+ await pick_capable_first(ctx_critical, confidence_threshold=0.7, decision_log=log)
assert ctx_critical.metadata[CONTEXT_KEY] == "override"
# fall_open path: low confidence, no classifier → default tier
ctx_neutral = await _ctx([{"role": "user", "content": "hi"}])
- await pick_strong_default(ctx_neutral, confidence_threshold=0.99, decision_log=log)
+ await pick_capable_first(ctx_neutral, confidence_threshold=0.99, decision_log=log)
assert ctx_neutral.metadata[CONTEXT_KEY] == "fall_open"
# classifier path: low confidence, classifier configured → classifier verdict
- classifier = _stub_classifier(tier="weak")
+ classifier = _stub_classifier(tier="efficient")
ctx_class = await _ctx([{"role": "user", "content": "hi"}])
- await pick_strong_default(
+ await pick_capable_first(
ctx_class, confidence_threshold=0.99, classifier=classifier, decision_log=log,
)
assert ctx_class.metadata[CONTEXT_KEY] == "llm-classifier"
diff --git a/tests/test_cascade_profile.py b/tests/test_stage_router_profile.py
similarity index 72%
rename from tests/test_cascade_profile.py
rename to tests/test_stage_router_profile.py
index 916e7ecdd..67b69de6b 100644
--- a/tests/test_cascade_profile.py
+++ b/tests/test_stage_router_profile.py
@@ -1,7 +1,7 @@
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
-"""Unit tests for cascade profile classifier construction."""
+"""Unit tests for stage_router profile classifier construction."""
from __future__ import annotations
@@ -11,9 +11,9 @@ from typing import Any
import pytest
-from switchyard.lib.processors.cascade_request_processor import CascadeRequestProcessor
-from switchyard.lib.profiles.cascade import CascadeProfileConfig, _build_classifier
-from switchyard.lib.profiles.cascade_config import CascadeConfig, ClassifierConfig
+from switchyard.lib.processors.stage_router_request_processor import StageRouterRequestProcessor
+from switchyard.lib.profiles.stage_router import StageRouterProfileConfig, _build_classifier
+from switchyard.lib.profiles.stage_router_config import ClassifierConfig, StageRouterConfig
from switchyard.lib.stats_accumulator import StatsAccumulator
from switchyard_rust.core import ChatRequest
from switchyard_rust.profiles import ProfileInput
@@ -22,7 +22,7 @@ from switchyard_rust.profiles import ProfileInput
class _ClassifierClient:
"""Fake async classifier client that returns one deterministic tier verdict."""
- def __init__(self, tier: str = "weak") -> None:
+ def __init__(self, tier: str = "efficient") -> None:
"""Store the tier returned by later classifier calls."""
self._tier = tier
self.calls = 0
@@ -67,31 +67,31 @@ def test_deepseek_classifier_keeps_reasoning_disabled() -> None:
@pytest.mark.parametrize(
("picker", "expected_target"),
[
- ("cascade_strong_default", "weak"),
- ("cascade_weak_default", "weak"),
+ ("capable_first", "efficient"),
+ ("efficient_first", "efficient"),
],
)
async def test_runtime_stats_reach_profile_classifier(
picker: str,
expected_target: str,
) -> None:
- """Python cascade classifier overhead is visible in shared routing stats."""
+ """Python stage_router classifier overhead is visible in shared routing stats."""
stats = StatsAccumulator()
- config = CascadeConfig.model_validate({
+ config = StageRouterConfig.model_validate({
"picker": picker,
"confidence_threshold": 1.0,
- "fallback_target_on_evict": "strong",
- "strong": {
- "id": "strong",
- "model": "strong/model",
- "api_key": "strong-key",
- "base_url": "http://127.0.0.1:9/strong/v1",
+ "fallback_target_on_evict": "capable",
+ "capable": {
+ "id": "capable",
+ "model": "capable/model",
+ "api_key": "capable-key",
+ "base_url": "http://127.0.0.1:9/capable/v1",
},
- "weak": {
- "id": "weak",
- "model": "weak/model",
- "api_key": "weak-key",
- "base_url": "http://127.0.0.1:9/weak/v1",
+ "efficient": {
+ "id": "efficient",
+ "model": "efficient/model",
+ "api_key": "efficient-key",
+ "base_url": "http://127.0.0.1:9/efficient/v1",
},
"classifier": {
"model": "classifier/model",
@@ -100,18 +100,18 @@ async def test_runtime_stats_reach_profile_classifier(
},
})
profile = (
- CascadeProfileConfig.from_config(config)
+ StageRouterProfileConfig.from_config(config)
.build()
.with_runtime_components(stats_accumulator=stats, enable_stats=True)
)
processor = next(
component
for component in profile.iter_components()
- if isinstance(component, CascadeRequestProcessor)
+ if isinstance(component, StageRouterRequestProcessor)
)
classifier = processor._classifier
assert classifier is not None
- client = _ClassifierClient(tier="weak")
+ client = _ClassifierClient(tier="efficient")
classifier._client = client # type: ignore[assignment]
processed = await profile.process(ProfileInput(_chat_request()))
@@ -128,13 +128,13 @@ async def test_runtime_stats_reach_profile_classifier(
assert model_stats["completion_tokens"] == 7
assert model_stats["cached_tokens"] == 3
assert model_stats["model_call_latency"]["count"] == 1
- assert snapshot["routing_decisions"]["cascade"]["llm-classifier"] == 1
+ assert snapshot["routing_decisions"]["stage_router"]["llm-classifier"] == 1
def _chat_request() -> ChatRequest:
- """Build the OpenAI request shape passed through the cascade profile."""
+ """Build the OpenAI request shape passed through the stage_router profile."""
return ChatRequest.openai_chat({
- "model": "cascade-route",
+ "model": "stage_router-route",
"messages": [
{
"role": "user",
diff --git a/tests/test_cascade_request_processor.py b/tests/test_stage_router_request_processor.py
similarity index 62%
rename from tests/test_cascade_request_processor.py
rename to tests/test_stage_router_request_processor.py
index f1be671a5..0958384fd 100644
--- a/tests/test_cascade_request_processor.py
+++ b/tests/test_stage_router_request_processor.py
@@ -1,7 +1,7 @@
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
-"""Tests for :class:`CascadeRequestProcessor`.
+"""Tests for :class:`StageRouterRequestProcessor`.
The processor is a thin async dispatcher: it runs an async picker against the
:class:`ToolResultSignal` stamped upstream by :class:`DimensionCollector` and
@@ -14,8 +14,8 @@ from __future__ import annotations
import pytest
from switchyard.lib.backends.llm_target import BackendFormat, LlmTarget
-from switchyard.lib.processors.cascade import pick_strong_default, pick_weak_default
-from switchyard.lib.processors.cascade_request_processor import CascadeRequestProcessor
+from switchyard.lib.processors.stage_router import pick_capable_first, pick_efficient_first
+from switchyard.lib.processors.stage_router_request_processor import StageRouterRequestProcessor
from switchyard_rust.components import DimensionCollector
from switchyard_rust.core import ChatRequest, ProxyContext
@@ -30,8 +30,8 @@ def _target(label: str, model: str) -> LlmTarget:
)
-WEAK = _target("weak", "vendor/weak-model")
-STRONG = _target("strong", "vendor/strong-model")
+EFFICIENT = _target("efficient", "vendor/efficient-model")
+CAPABLE = _target("capable", "vendor/capable-model")
async def _populated_ctx(messages: list[dict]) -> tuple[ProxyContext, ChatRequest]:
@@ -42,44 +42,44 @@ async def _populated_ctx(messages: list[dict]) -> tuple[ProxyContext, ChatReques
return ctx, request
-async def _strong_pick(ctx: ProxyContext) -> int:
- return await pick_strong_default(ctx, confidence_threshold=0.7)
+async def _capable_pick(ctx: ProxyContext) -> int:
+ return await pick_capable_first(ctx, confidence_threshold=0.7)
-async def _weak_pick(ctx: ProxyContext) -> int:
- return await pick_weak_default(ctx, confidence_threshold=0.7)
+async def _efficient_pick(ctx: ProxyContext) -> int:
+ return await pick_efficient_first(ctx, confidence_threshold=0.7)
def test_requires_exactly_two_targets():
with pytest.raises(ValueError, match="exactly 2 targets"):
- CascadeRequestProcessor(targets=(WEAK,), picker=_strong_pick)
+ StageRouterRequestProcessor(targets=(EFFICIENT,), picker=_capable_pick)
with pytest.raises(ValueError, match="exactly 2 targets"):
- CascadeRequestProcessor(targets=(WEAK, STRONG, STRONG), picker=_strong_pick)
+ StageRouterRequestProcessor(targets=(EFFICIENT, CAPABLE, CAPABLE), picker=_capable_pick)
@pytest.mark.asyncio
-async def test_strong_default_stamps_strong_on_first_turn_no_signal():
+async def test_capable_first_stamps_capable_on_first_turn_no_signal():
"""First turn: no ToolResultSignal yet → no_signal path → default tier."""
- processor = CascadeRequestProcessor(targets=(WEAK, STRONG), picker=_strong_pick)
+ processor = StageRouterRequestProcessor(targets=(EFFICIENT, CAPABLE), picker=_capable_pick)
ctx, request = await _populated_ctx([{"role": "user", "content": "hi"}])
await processor.process(ctx, request)
- assert ctx.selected_target == "strong"
- assert ctx.selected_model == "vendor/strong-model"
+ assert ctx.selected_target == "capable"
+ assert ctx.selected_model == "vendor/capable-model"
@pytest.mark.asyncio
-async def test_weak_default_stamps_weak_on_first_turn_no_signal():
+async def test_efficient_first_stamps_efficient_on_first_turn_no_signal():
"""First turn: no ToolResultSignal yet → no_signal path → default tier."""
- processor = CascadeRequestProcessor(targets=(WEAK, STRONG), picker=_weak_pick)
+ processor = StageRouterRequestProcessor(targets=(EFFICIENT, CAPABLE), picker=_efficient_pick)
ctx, request = await _populated_ctx([{"role": "user", "content": "hi"}])
await processor.process(ctx, request)
- assert ctx.selected_target == "weak"
+ assert ctx.selected_target == "efficient"
@pytest.mark.asyncio
-async def test_strong_default_falls_open_to_strong_on_low_confidence():
+async def test_capable_first_falls_open_to_capable_on_low_confidence():
"""Signal present but scorer below threshold + no classifier → fall_open to default."""
- processor = CascadeRequestProcessor(targets=(WEAK, STRONG), picker=_strong_pick)
+ processor = StageRouterRequestProcessor(targets=(EFFICIENT, CAPABLE), picker=_capable_pick)
# One Read + one clean tool_result + a follow-up user message. This produces
# a non-None ToolResultSignal (so the no_signal short-circuit is bypassed)
# but the scorer only sees a small no_error_streak penalty — confidence
@@ -91,13 +91,13 @@ async def test_strong_default_falls_open_to_strong_on_low_confidence():
{"role": "user", "content": "next"},
])
await processor.process(ctx, request)
- assert ctx.selected_target == "strong"
+ assert ctx.selected_target == "capable"
@pytest.mark.asyncio
-async def test_weak_default_falls_open_to_weak_on_low_confidence():
- """Sibling check on the weak-default picker, same low-confidence shape."""
- processor = CascadeRequestProcessor(targets=(WEAK, STRONG), picker=_weak_pick)
+async def test_efficient_first_falls_open_to_efficient_on_low_confidence():
+ """Sibling check on the efficient-first picker, same low-confidence shape."""
+ processor = StageRouterRequestProcessor(targets=(EFFICIENT, CAPABLE), picker=_efficient_pick)
ctx, request = await _populated_ctx([
{"role": "assistant",
"tool_calls": [{"function": {"name": "Read", "arguments": "{}"}}]},
@@ -105,7 +105,7 @@ async def test_weak_default_falls_open_to_weak_on_low_confidence():
{"role": "user", "content": "next"},
])
await processor.process(ctx, request)
- assert ctx.selected_target == "weak"
+ assert ctx.selected_target == "efficient"
@pytest.mark.asyncio
@@ -115,30 +115,30 @@ async def test_critical_severity_escalates_both_pickers():
"content": "Out of memory: cannot allocate memory"},
{"role": "user", "content": "try again"},
]
- for picker in (_strong_pick, _weak_pick):
- processor = CascadeRequestProcessor(targets=(WEAK, STRONG), picker=picker)
+ for picker in (_capable_pick, _efficient_pick):
+ processor = StageRouterRequestProcessor(targets=(EFFICIENT, CAPABLE), picker=picker)
ctx, request = await _populated_ctx(fatal)
await processor.process(ctx, request)
- assert ctx.selected_target == "strong"
+ assert ctx.selected_target == "capable"
@pytest.mark.asyncio
async def test_request_is_not_mutated():
- processor = CascadeRequestProcessor(targets=(WEAK, STRONG), picker=_strong_pick)
+ processor = StageRouterRequestProcessor(targets=(EFFICIENT, CAPABLE), picker=_capable_pick)
ctx, request = await _populated_ctx([{"role": "user", "content": "hi"}])
returned = await processor.process(ctx, request)
assert returned is request
@pytest.mark.asyncio
-async def test_buggy_picker_falls_back_to_weak():
+async def test_buggy_picker_falls_back_to_efficient():
async def bad_picker(_ctx: ProxyContext) -> int:
raise RuntimeError("boom")
- processor = CascadeRequestProcessor(targets=(WEAK, STRONG), picker=bad_picker)
+ processor = StageRouterRequestProcessor(targets=(EFFICIENT, CAPABLE), picker=bad_picker)
ctx, request = await _populated_ctx([{"role": "user", "content": "hi"}])
await processor.process(ctx, request)
- assert ctx.selected_target == "weak"
+ assert ctx.selected_target == "efficient"
@pytest.mark.asyncio
@@ -146,7 +146,7 @@ async def test_picker_index_is_clamped():
async def overshooting_picker(_ctx: ProxyContext) -> int:
return 99
- processor = CascadeRequestProcessor(targets=(WEAK, STRONG), picker=overshooting_picker)
+ processor = StageRouterRequestProcessor(targets=(EFFICIENT, CAPABLE), picker=overshooting_picker)
ctx, request = await _populated_ctx([{"role": "user", "content": "hi"}])
await processor.process(ctx, request)
- assert ctx.selected_target == "strong"
+ assert ctx.selected_target == "capable"
diff --git a/tests/test_cascade_scorer.py b/tests/test_stage_router_scorer.py
similarity index 92%
rename from tests/test_cascade_scorer.py
rename to tests/test_stage_router_scorer.py
index 85e7bac2a..ed2aa6b01 100644
--- a/tests/test_cascade_scorer.py
+++ b/tests/test_stage_router_scorer.py
@@ -1,17 +1,17 @@
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
-"""Unit tests for the cascade dimensions + scorer."""
+"""Unit tests for the stage-router dimensions + scorer."""
from __future__ import annotations
import pytest
-from switchyard.lib.processors.cascade.dimensions import (
+from switchyard.lib.processors.stage_router.dimensions import (
CodingAgentDimensions,
from_signal,
)
-from switchyard.lib.processors.cascade.scorer import DEFAULT_WEIGHTS, score
+from switchyard.lib.processors.stage_router.scorer import DEFAULT_WEIGHTS, score
from switchyard_rust.components import DimensionCollector
from switchyard_rust.core import ChatRequest, ProxyContext
@@ -37,7 +37,7 @@ def test_zero_signal_scores_to_zero():
assert result.confidence == 0.0
-def test_critical_severity_pushes_toward_strong():
+def test_critical_severity_pushes_toward_capable():
dims = _zero_dimensions()
dims = CodingAgentDimensions(**{**dims.__dict__, "severity": 1.0})
result = score(dims)
@@ -45,7 +45,7 @@ def test_critical_severity_pushes_toward_strong():
assert result.confidence == abs(result.score)
-def test_tests_passed_pushes_toward_weak():
+def test_tests_passed_pushes_toward_efficient():
dims = _zero_dimensions()
dims = CodingAgentDimensions(**{**dims.__dict__, "tests_passed": 1.0})
result = score(dims)
diff --git a/tests/test_switchyard_rust_profile_bindings.py b/tests/test_switchyard_rust_profile_bindings.py
index 9d21b519c..1ff8aadab 100644
--- a/tests/test_switchyard_rust_profile_bindings.py
+++ b/tests/test_switchyard_rust_profile_bindings.py
@@ -77,13 +77,13 @@ class _MockOpenAIHandler(BaseHTTPRequestHandler):
finish_reason = "tool_calls"
elif body.get("response_format", {}).get("type") == "json_schema":
schema_name = body["response_format"]["json_schema"]["name"]
- if schema_name == "CascadeTierDecision":
- message = {"role": "assistant", "content": json.dumps({"tier": "weak"})}
+ if schema_name == "StageRouterTierDecision":
+ message = {"role": "assistant", "content": json.dumps({"tier": "efficient"})}
elif (
body.get("response_format", {}).get("type") == "json_object"
and body.get("model") == "provider/classifier"
):
- message = {"role": "assistant", "content": json.dumps({"tier": "weak"})}
+ message = {"role": "assistant", "content": json.dumps({"tier": "efficient"})}
response = {
"id": "chatcmpl-profile-bindings",
@@ -186,12 +186,12 @@ profiles:
weak: weak
classifier: classifier
profile_name: coding_agent
- cascade:
- type: cascade
- strong: strong
- weak: weak
+ stage_router:
+ type: stage_router
+ capable: strong
+ efficient: weak
fallback_target_on_evict: strong
- picker: cascade_strong_default
+ picker: capable_first
confidence_threshold: 0.7
classifier:
model: provider/classifier
@@ -226,11 +226,11 @@ def test_profile_config_plan_is_inspectable() -> None:
assert document.profile_ids() == [
"bench",
- "cascade",
"direct",
"latency",
"llm",
"random",
+ "stage_router",
]
assert document.profile_type("direct") == "passthrough"
assert document.profile_body("random") == {
@@ -240,25 +240,25 @@ def test_profile_config_plan_is_inspectable() -> None:
"rng_seed": 7,
}
rust_document = document.without_profiles(["random"])
- assert rust_document.profile_ids() == ["bench", "cascade", "direct", "latency", "llm"]
+ assert rust_document.profile_ids() == ["bench", "direct", "latency", "llm", "stage_router"]
plan = document.resolve()
assert isinstance(plan, ProfileConfigPlan)
assert plan.profile_ids() == [
"bench",
- "cascade",
"direct",
"latency",
"llm",
"random",
+ "stage_router",
]
assert plan.target_ids() == ["classifier", "direct", "latency", "strong", "weak"]
assert plan.profile_type("direct") == "passthrough"
assert plan.profile_type("random") == "random-routing"
assert plan.profile_type("latency") == "latency-service"
assert plan.profile_type("llm") == "llm-routing"
- assert plan.profile_type("cascade") == "cascade"
+ assert plan.profile_type("stage_router") == "stage_router"
assert plan.profile_type("bench") == "noop"
assert plan.profile_type("missing") is None
@@ -272,11 +272,11 @@ def test_profile_config_plan_is_inspectable() -> None:
profiles = plan.build_profiles()
assert sorted(profiles) == [
"bench",
- "cascade",
"direct",
"latency",
"llm",
"random",
+ "stage_router",
]
assert all(isinstance(profile, Profile) for profile in profiles.values())
assert profiles["direct"].profile_id == "direct"
@@ -294,11 +294,11 @@ def test_profile_config_can_be_loaded_from_path(
plan = load_profile_config(path)
assert plan.profile_ids() == [
"bench",
- "cascade",
"direct",
"latency",
"llm",
"random",
+ "stage_router",
]
@@ -323,7 +323,7 @@ async def test_native_profiles_run_against_local_openai_mock(
random_response = await plan.build_profile("random").run(_request("client/random"))
latency_response = await plan.build_profile("latency").run(_request("client/latency"))
llm_response = await plan.build_profile("llm").run(_request("client/llm-routing"))
- cascade_response = await plan.build_profile("cascade").run(_request("client/cascade"))
+ stage_router_response = await plan.build_profile("stage_router").run(_request("client/stage_router"))
assert direct_response.body["model"] == "provider/direct"
assert direct_response.body["mock_path"] == "/direct/v1/chat/completions"
@@ -333,8 +333,8 @@ async def test_native_profiles_run_against_local_openai_mock(
assert latency_response.body["mock_path"] == "/latency/v1/chat/completions"
assert llm_response.body["model"] == "provider/weak"
assert llm_response.body["mock_path"] == "/weak/v1/chat/completions"
- assert cascade_response.body["model"] == "provider/weak"
- assert cascade_response.body["mock_path"] == "/weak/v1/chat/completions"
+ assert stage_router_response.body["model"] == "provider/weak"
+ assert stage_router_response.body["mock_path"] == "/weak/v1/chat/completions"
assert [call["body"]["model"] for call in mock_openai_server.calls] == [
"provider/direct",
"provider/strong",
@@ -348,8 +348,8 @@ async def test_native_profiles_run_against_local_openai_mock(
assert llm_classifier_body["tools"][0]["function"]["strict"] is True
assert llm_classifier_body["tool_choice"]["function"]["name"] == "select_route"
assert "response_format" not in llm_classifier_body
- cascade_classifier_body = mock_openai_server.calls[5]["body"]
- assert cascade_classifier_body["response_format"]["type"] == "json_object"
+ stage_router_classifier_body = mock_openai_server.calls[5]["body"]
+ assert stage_router_classifier_body["response_format"]["type"] == "json_object"
def test_profile_binding_errors_map_to_switchyard_exceptions() -> None:
@@ -419,9 +419,9 @@ def test_concrete_profile_trios_are_not_reexported_from_rust_profiles() -> None:
"LlmRoutingProfileConfig",
"LlmRoutingProfile",
"LlmRoutingProcessedRequest",
- "CascadeProfileConfig",
- "CascadeProfile",
- "CascadeProcessedRequest",
+ "StageRouterProfileConfig",
+ "StageRouterProfile",
+ "StageRouterProcessedRequest",
"NoopProfileConfig",
"NoopProfile",
"NoopProcessedRequest",