feat(router): add escalation_router profile with judge-latched strong/weak routing

[linj-glitch]

Summary

Ports the escalation-router work from the private fork (branch linj_router_exp) to the public repo.

• Adds an escalation_router profile with judge-latched strong/weak routing, including the escalation-judge request processor, profile configs, and route_bundle CLI support.
• ESC8 escalation-judge campaign through ESC7 plus a prompt generalization audit: judge prompt refinements, cost-estimator updates (switchyard/lib/cost_estimator.py, crates/switchyard-components/src/stats/cost.rs), and expanded tests.
• Adds routing-algorithm docs (docs/routing_algorithms/escalation_router_routing.md) and registers them in mkdocs.yml.

Note: changes under the benchmark/ folder from the original branch are intentionally excluded from this PR.

Test plan

• tests/test_escalation_judge_request_processor.py
• tests/test_escalation_router_profile.py
• tests/test_route_bundle.py

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added escalation-router routing, which starts requests on a weaker tier and can permanently promote them to a stronger tier when a judge detects difficulty.
  • Added YAML configuration support and public configuration exports for escalation routing.
  • Added session-affinity latching, configurable confirmation rules, fallbacks, timeouts, and judge controls.
  • Added pricing support for Nemotron 3 Ultra and additional Claude model variants.

• Documentation

  • Added comprehensive escalation-router configuration and behavior documentation.
  • Updated routing strategy navigation and overview guidance.

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://NVIDIA-NeMo.github.io/Switchyard/pr-preview/pr-62/
Built to branch gh-pages at 2026-07-15 23:48 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[coderabbitai]

Walkthrough

Adds an escalation-router profile that starts requests on a weak tier, uses a trajectory judge for one-way escalation to a strong tier, persists decisions with session affinity, integrates YAML route bundles, exports configuration types, documents the behavior, and updates model pricing aliases.

Changes

Escalation Router

Layer / File(s)	Summary
Trajectory judge and escalation latch switchyard/lib/processors/escalation_judge_request_processor.py, tests/test_escalation_judge_request_processor.py	Adds structured judge verdicts, transcript summarization, fail-open handling, confirmation windows, deep session keys, affinity latching, verdict output, statistics, and behavioral coverage.
Configuration and runtime profile construction switchyard/lib/profiles/..., switchyard/__init__.py, tests/test_escalation_router_profile.py	Adds validated strong, weak, and judge targets; constructs tiered backends and judge processors; and publicly exports the new configuration types.
YAML route-bundle integration switchyard/cli/route_bundle.py, tests/test_route_bundle.py	Adds escalation_router route validation, aliases, target discovery, switchyard construction, and invalid-configuration tests.
Routing documentation and navigation docs/routing_algorithms/*, mkdocs.yml, .agents/skills/switchyard-lib-core/SKILL.md	Documents escalation behavior, configuration, affinity, benchmarking, limitations, navigation, and related implementation guidance.
Model pricing coverage crates/switchyard-components/src/stats/cost.rs, switchyard/lib/cost_estimator.py	Adds pricing entries and aliases for Nemotron Ultra and Claude Opus/Sonnet deployments.

Estimated code review effort: 4 (Complex) | ~60 minutes

Poem

I’m a rabbit routing through the hay,
Weak at dawn, strong later in the day.
A judge spots trouble, latches tight,
Prices bloom for every byte.
Docs and tests now guide the way!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 22.73% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding an escalation_router profile with judge-latched strong/weak routing.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

tests/test_escalation_router_profile.py (1)

105-124: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Coverage gap: judge_timeout_s not asserted.

This test threads several judge_* settings but omits judge_timeout_s. Adding an override + assertion (e.g. _config(judge_timeout_s=12.0) → judge._config.timeout_s == 12.0) would have surfaced the wiring gap flagged in escalation_router_profile_config.py.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/test_escalation_router_profile.py` around lines 105 - 124, Extend
test_build_threads_judge_settings to pass a non-default judge_timeout_s value
through _config, then assert the resulting judge._config.timeout_s matches it.
Keep the existing judge settings and assertions unchanged.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/routing_algorithms/escalation_router_routing.md`:
- Line 73: Update the session_key_depth link and the corresponding heading
reference in the routing documentation so the link target matches the generated
Markdown slug for “Repeated-trial benchmarking (k>1)”. Ensure all references use
the same valid anchor and satisfy markdownlint MD051.

In `@docs/routing_algorithms/overview.md`:
- Around line 156-160: Update the escalation-router description to clarify that
the judge runs on every turn from EscalationJudgeConfig.min_judge_turn onward
until the latch fires, while earlier turns route weak without a judge call.
Preserve the existing affinity and strong-tier pinning behavior.

---

Nitpick comments:
In `@tests/test_escalation_router_profile.py`:
- Around line 105-124: Extend test_build_threads_judge_settings to pass a
non-default judge_timeout_s value through _config, then assert the resulting
judge._config.timeout_s matches it. Keep the existing judge settings and
assertions unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: ae4d07e2-3bd2-4af8-b27e-66c159c6b73a

📥 Commits

Reviewing files that changed from the base of the PR and between a2a939d and 4a16e3c.

📒 Files selected for processing (15)

• .agents/skills/switchyard-lib-core/SKILL.md
• crates/switchyard-components/src/stats/cost.rs
• docs/routing_algorithms/escalation_router_routing.md
• docs/routing_algorithms/overview.md
• mkdocs.yml
• switchyard/__init__.py
• switchyard/cli/route_bundle.py
• switchyard/lib/cost_estimator.py
• switchyard/lib/processors/escalation_judge_request_processor.py
• switchyard/lib/profiles/__init__.py
• switchyard/lib/profiles/escalation_router_config.py
• switchyard/lib/profiles/escalation_router_profile_config.py
• tests/test_escalation_judge_request_processor.py
• tests/test_escalation_router_profile.py
• tests/test_route_bundle.py

[ayushag-nv]

This looks like a extension of LLM classifier or existing stage router. I suggest we should consider this as a design to extend our existing routers to accomodate this like we did for Session Pinning in the existing routers.

NA