fix(stage-router): warn when capable-first cannot offload via scorer

[ting-hong-shieh]

What

Warn when a capable_first stage router uses a confidence threshold that prevents the scorer from selecting the efficient tier. For example, 0.5 exceeds the efficient confidence ceiling of approximately 0.462117.

The warning runs once when StageClassifier is constructed, not on each request. It appears in the runner and server, including the Python server path, because they set up tracing output. A direct switchyard.libsy.stage_router() call runs the same check, but that path sets up no tracing output, so the warning is not shown. It computes the ceiling through the existing scorer and uses the picker's closed probability band, including the exact boundary. Routing behavior is unchanged: an optional LLM classifier can still select efficient.

The documentation adds a short section on this limit for capable_first.

Why

Closes #264.

The current TOML schema requires an explicit threshold, but capable_first with 0.5 still silently disables scorer-driven offloading. This implements the issue's warning option without changing scoring weights or introducing new public APIs.

Notes for reviewers

Start with StageClassifier::new in crates/libsy/src/algorithms/util/stage.rs. One regression test checks warning output and picker behavior at 0.45, the exact ceiling, and 0.5.

This branch is rebased onto main. main removed hard de-escalation in #651, so the warning, test, and docs no longer mention it.

Validation after the rebase:

• cargo test -p switchyard-libsy: 322 passed.
• cargo clippy --workspace --all-targets -- -D warnings and cargo fmt --all --check: passed.
• Strict MkDocs build: passed.

Validation before the rebase:

• cargo test --workspace: 757 passed, 1 ignored.
• uv run ruff check .: passed; uv run pytest tests/: 116 passed, 2 skipped.
• A temporary adversarial test checked 56,250 signal combinations against the efficient ceiling and 65 adjacent floating-point thresholds for agreement between the warning and picker. It passed and was removed from the final diff.

Validation used the project's Python 3.14 interpreter for PyO3 and allowed local ports for mock HTTP servers. No live model benchmark was run; 0.45 is documented as below the ceiling, not as a calibrated recommendation.

Summary by CodeRabbit

• New Features

  • Added warnings in capable_first mode when production scoring cannot reach the configured confidence threshold for efficient selection.
  • Preserved hard de-escalation behavior and classifier exceptions for ambiguous cases.

• Documentation

  • Clarified confidence threshold comparisons, routing behavior, scorer limits, warning conditions, and threshold calibration guidance.
  • Specified that the recommended 0.5 threshold applies to efficient_first.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 3f434bda-6b1c-45a9-a61d-587daadfa062

📥 Commits

Reviewing files that changed from the base of the PR and between f27abd6 and dc2bfc7.

📒 Files selected for processing (2)

• crates/libsy/src/algorithms/util/stage.rs
• docs/routing_algorithms/stage_router_routing.md

Included review availability: Your plan provides up to 12 included reviews per hour; 11 remain after this review.

---

Walkthrough

Changes

Stage threshold behavior

Layer / File(s)	Summary
Constructor warning and validation crates/libsy/src/algorithms/util/stage.rs	StageClassifier::new warns when capable_first uses a threshold at or above the efficient scorer ceiling. Tests cover threshold boundaries, picker behavior, ambiguous results, and hard de-escalation.
Routing rule documentation docs/routing_algorithms/stage_router_routing.md	The documentation requires confidence to be strictly greater than the threshold and describes capable_first, its scorer ceiling, warning behavior, exceptions, and efficient_first calibration.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to dc2bf

The warning and documentation changes are ready to merge; no concrete regressions remain identified.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 6 functions across 1 files. (1 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Issue #264 requires users to see when capable_first cannot use scorer-driven efficient-tier selection at the confidence ceiling. StageClassifier::new now computes the ceiling through `score_signal…
Out of Scope Changes check	✅ Passed	The changes stay within Issue #264. The Rust changes add the requested configuration warning and focused automated tests. The documentation changes explain the threshold boundary, picker-specific beha…
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main change: adding a warning when capable_first cannot offload through the scorer.

Full details: Docstring Coverage

Explanation

Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 6 functions across 1 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

---

_{A rabbit reads each line,
The patch grows clear beneath the moon,
Small changes hop in place,
Tests guard the garden path,
Reviews bloom before the dawn.}

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

[ayushag-nv]

++ @sabhatinas for review

[afourniernv]

Small wording nit: direct switchyard.libsy.stage_router() reaches this code, but that path doesn’t install a tracing subscriber, so Python-only users won’t see the warning. The Python server path does. Could we narrow the “covers Python bindings” line? I don’t think this PR needs any additional Python logging work.

[ting-hong-shieh]

Good catch, thanks. I narrowed the description: the warning shows on the runner and server paths, including the Python server. Direct switchyard.libsy.stage_router() runs the check but has no tracing output set up, so it stays silent. No Python logging changes in this PR.