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
feat(libsy): stage router (signals only) (#135)
Greg Clarke3e7c474b5a7
diff --git a/crates/libsy/examples/ensemble.rs b/crates/libsy/examples/ensemble.rsindex 0495a6b2b..7a543c3ca 100644--- a/crates/libsy/examples/ensemble.rs+++ b/crates/libsy/examples/ensemble.rs@@ -717,7 +717,7 @@ mod tests {_request: Request,_decision: Arc<dyn Decision>,) -> std::result::Result<Response, switchyard_protocol::LlmClientError> {- Err(switchyard_protocol::LlmClientError::Other(+ Err(switchyard_protocol::LlmClientError::General("upstream down".into(),))}diff --git a/crates/libsy/src/algorithms/util.rs b/crates/libsy/src/algorithms/util.rsindex 601cffef3..c77354a8f 100644--- a/crates/libsy/src/algorithms/util.rs+++ b/crates/libsy/src/algorithms/util.rs@@ -1,8 +1,11 @@// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.// SPDX-License-Identifier: Apache-2.0-pub mod affinity;-pub mod subagent;+mod affinity;+pub(crate) mod handoff_notes;+pub(crate) mod stage_router;+mod subagent;+pub(crate) mod tool_signals;pub use affinity::AffinityRouter;pub use subagent::SubagentOverride;diff --git a/crates/libsy/src/algorithms/util/handoff_notes.rs b/crates/libsy/src/algorithms/util/handoff_notes.rsnew file mode 100644index 000000000..dbaba4c67--- /dev/null+++ b/crates/libsy/src/algorithms/util/handoff_notes.rs@@ -0,0 +1,172 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++//! Stage-router handoff notes.+//!+//! When a turn escalates to the strong tier (or hands back to the weak tier),+//! a short **deterministic** note can be handed to the model taking over so it+//! knows *why* — without re-diagnosing (weak→strong) or re-architecting settled+//! work (strong→weak). This is not a model call; the note text comes from config.+//!+//! [`HandoffNoteProcessor`] reacts to [`Event::Decision`] (replayed after the+//! tier is chosen, before the model call), derives escalate vs de-escalate from+//! the chosen tier plus the `decision_source` the picker stashed, and records+//! the matching note on the [`State`] under [`HANDOFF_NOTE_KEY`]. A later+//! request-injection step splices it into the outbound request — that step is+//! intentionally not wired here.++use async_trait::async_trait;++use crate::{Event, Processor, Result, State, StateValue};++/// `State.extra` key under which the computed handoff note is recorded for a+/// later request-injection step to consume.+pub const HANDOFF_NOTE_KEY: &str = "handoff_note";++/// Records a handoff note on the decision, based on the chosen tier and the+/// picker's `decision_source`. Deterministic — no model call.+pub struct HandoffNoteProcessor {+ escalation_note: String,+ deescalation_note: Option<String>,+ only_on_wrong_signal_escalation: bool,+}++impl HandoffNoteProcessor {+ /// Configure the notes: the `escalation_note` handed to the strong tier, an+ /// optional `deescalation_note` handed back to the weak tier, and whether+ /// the escalation note fires only on a signal-driven escalation+ /// (`override` / `dimensions`) rather than a `fall_open` default.+ pub fn new(+ escalation_note: impl Into<String>,+ deescalation_note: Option<String>,+ only_on_wrong_signal_escalation: bool,+ ) -> Self {+ Self {+ escalation_note: escalation_note.into(),+ deescalation_note,+ only_on_wrong_signal_escalation,+ }+ }++ /// The note to record for a decision routed to `tier` with picker `source`,+ /// or `None` when no note applies.+ fn note_for(&self, tier: &str, source: Option<&str>) -> Option<String> {+ match tier {+ // Escalation to the strong tier. When gated, only a signal-driven+ // escalation qualifies — never a `fall_open` default.+ "strong" => {+ let signal_driven = matches!(source, Some("override") | Some("dimensions"));+ (!self.only_on_wrong_signal_escalation || signal_driven)+ .then(|| self.escalation_note.clone())+ }+ // Hand-back to the weak tier, when a de-escalation note is configured.+ "weak" => self.deescalation_note.clone(),+ _ => None,+ }+ }+}++#[async_trait]+impl Processor for HandoffNoteProcessor {+ async fn process(&self, state: &mut State, event: Event<'_>) -> Result<()> {+ let Event::Decision(decision) = event else {+ return Ok(());+ };+ let tier = decision.selected_model().to_string();+ // Read (and release the borrow on) the source the picker stashed.+ let source = match state.extra.get("decision_source") {+ Some(StateValue::String(source)) => Some(source.clone()),+ _ => None,+ };+ if let Some(note) = self.note_for(&tier, source.as_deref()) {+ state+ .extra+ .insert(HANDOFF_NOTE_KEY.to_string(), StateValue::String(note));+ }+ Ok(())+ }+}++#[cfg(test)]+mod tests {+ use super::*;+ use crate::Decision;++ struct FakeDecision(&'static str);+ impl Decision for FakeDecision {+ fn selected_model(&self) -> &str {+ self.0+ }+ fn reasoning(&self) -> Option<&str> {+ None+ }+ fn as_any(&self) -> &dyn std::any::Any {+ self+ }+ }++ fn state_with_source(source: &str) -> State {+ let mut state = State::default();+ state.extra.insert(+ "decision_source".to_string(),+ StateValue::String(source.to_string()),+ );+ state+ }++ async fn run(processor: &HandoffNoteProcessor, state: &mut State, tier: &'static str) {+ processor+ .process(state, Event::Decision(&FakeDecision(tier)))+ .await+ .unwrap();+ }++ #[tokio::test]+ async fn escalation_note_recorded_on_signal_driven_strong() {+ let processor = HandoffNoteProcessor::new("recovering from an error", None, true);+ for source in ["override", "dimensions"] {+ let mut state = state_with_source(source);+ run(&processor, &mut state, "strong").await;+ assert!(matches!(+ state.extra.get(HANDOFF_NOTE_KEY),+ Some(StateValue::String(note)) if note == "recovering from an error"+ ));+ }+ }++ #[tokio::test]+ async fn no_escalation_note_on_fall_open_default_when_gated() {+ let processor = HandoffNoteProcessor::new("recovering from an error", None, true);+ let mut state = state_with_source("fall_open");+ run(&processor, &mut state, "strong").await;+ assert!(!state.extra.contains_key(HANDOFF_NOTE_KEY));+ }++ #[tokio::test]+ async fn escalation_note_on_fall_open_when_not_gated() {+ let processor = HandoffNoteProcessor::new("recovering from an error", None, false);+ let mut state = state_with_source("fall_open");+ run(&processor, &mut state, "strong").await;+ assert!(state.extra.contains_key(HANDOFF_NOTE_KEY));+ }++ #[tokio::test]+ async fn deescalation_note_recorded_on_weak_when_configured() {+ let processor =+ HandoffNoteProcessor::new("esc", Some("settled — carry on".to_string()), true);+ let mut state = state_with_source("tests_passed");+ run(&processor, &mut state, "weak").await;+ assert!(matches!(+ state.extra.get(HANDOFF_NOTE_KEY),+ Some(StateValue::String(note)) if note == "settled — carry on"+ ));+ }++ #[tokio::test]+ async fn no_deescalation_note_when_unconfigured() {+ let processor = HandoffNoteProcessor::new("esc", None, true);+ let mut state = state_with_source("tests_passed");+ run(&processor, &mut state, "weak").await;+ assert!(!state.extra.contains_key(HANDOFF_NOTE_KEY));+ }+}diff --git a/crates/libsy/src/algorithms/util/stage_router.rs b/crates/libsy/src/algorithms/util/stage_router.rsnew file mode 100644index 000000000..a4474bd81--- /dev/null+++ b/crates/libsy/src/algorithms/util/stage_router.rs@@ -0,0 +1,591 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++//! Stage-router scoring and tier selection — the shared routing core.+//!+//! Given a [`ToolSignals`] (extracted by the dimension collector), this+//! module decides whether a coding-agent turn should go to the **capable**+//! (strong) or **efficient** (weak) tier. It is the single source of truth for+//! the decision, shared by the Rust profile and the Python processor via+//! bindings — only the outer shell differs in how it fetches the decision.+//!+//! Two axes:+//!+//! * **error** — did the recent tool results error? (`severity`)+//! * **production** — is the agent producing code? (`spinning` / `exploring`+//! push toward capable; `production_intensity` pushes toward efficient)+//!+//! Signals are scored with fixed weights, summed, and `tanh`-squashed into+//! `(-1, +1)`; `confidence` is the magnitude. The `confidence_threshold` dials+//! how much corroboration a decisive escalation needs (see [`score_signal`]).++#![allow(dead_code)]++use async_trait::async_trait;++use crate::{+ Classification, Classifier, Driver, Request, Result, Score, State, StateValue, ToolSignals,+};++/// Turn depth below which stall signals stay quiet — early no-write turns are+/// normal exploration, not a stall.+const STALL_MIN_TURN_DEPTH: u32 = 8;+/// Gain applied before the tanh squash — spreads the small raw weighted sum+/// across the usable confidence range. Without it confidence would cap near+/// ±0.20 and mid/high thresholds would be unreachable.+const SCORE_GAIN: f64 = 5.0;+/// Strongest error severity the scorer sees: critical (`1.0`) is caught by the+/// override, so hard (`0.7`) normalises `severity` to one signal unit.+const HARD_SEVERITY: f64 = 0.7;+/// Weight one maxed signal contributes. Small enough that no single axis pegs+/// the decision; corroboration across the two axes is what raises confidence.+const SIGNAL_UNIT: f64 = 0.10;+/// Critical severity forces the capable tier regardless of the scorer.+const SEVERITY_CRITICAL: f32 = 1.0;++/// The two tiers a turn can route to.+#[derive(Clone, Copy, Debug, Eq, PartialEq)]+pub enum Tier {+ /// Weak / cheap tier.+ Efficient,+ /// Strong / capable tier.+ Capable,+}++/// Which tier to default to when the scorer is not confident.+#[derive(Clone, Copy, Debug, Eq, PartialEq)]+pub enum PickerMode {+ /// Default to capable unless the scorer confidently picks efficient.+ CapableFirst,+ /// Default to efficient unless the scorer confidently picks capable.+ EfficientFirst,+}++impl PickerMode {+ fn default_tier(self) -> Tier {+ match self {+ Self::CapableFirst => Tier::Capable,+ Self::EfficientFirst => Tier::Efficient,+ }+ }+}++/// What produced a decision — for stats and explainability.+#[derive(Clone, Copy, Debug, Eq, PartialEq)]+pub enum DecisionSource {+ /// Hard override (critical severity or context compaction).+ Override,+ /// Settled run: recent tests passed with recent production and no error.+ TestsPassed,+ /// Scorer crossed `confidence_threshold`.+ Dimensions,+ /// Scorer was not confident; the caller should consult its classifier.+ FallOpen,+}++impl DecisionSource {+ /// Stable lowercase label used in stats.+ pub fn as_str(self) -> &'static str {+ match self {+ Self::Override => "override",+ Self::TestsPassed => "tests_passed",+ Self::Dimensions => "dimensions",+ Self::FallOpen => "fall_open",+ }+ }+}++/// A signed score in `(-1, +1)` and its magnitude. `confidence == score.abs()`.+#[derive(Clone, Copy, Debug, PartialEq)]+pub struct ScoreResult {+ /// Signed score: positive → capable, negative → efficient.+ pub score: f64,+ /// Decision certainty, `score.abs()`.+ pub confidence: f64,+}++/// The two-axis feature view of a single [`ToolSignals`].+#[derive(Clone, Copy, Debug, PartialEq)]+pub struct CodingAgentDimensions {+ /// Windowed max error severity in `[0, 1]`.+ pub severity: f64,+ /// `1.0` when a deep turn has no reads, plans, writes, or edits (pure churn).+ pub spinning: f64,+ /// `1.0` when a deep turn reads/plans but does not write or edit.+ pub exploring: f64,+ /// Fraction of recent tool ops that produced code (writes + edits).+ pub production_intensity: f64,+}++/// Outcome of [`pick_tier`]: either a resolved decision, or a signal that the+/// caller should consult its (impl-specific, async) classifier.+#[derive(Clone, Copy, Debug, PartialEq)]+pub enum PickOutcome {+ /// The tier was decided without the classifier.+ Resolved {+ /// The chosen tier.+ tier: Tier,+ /// What produced it.+ source: DecisionSource,+ /// Signed scorer value (`0.0` for override / tests-passed).+ score: f64,+ /// Scorer confidence (`None` where the scorer did not run).+ confidence: Option<f64>,+ },+ /// The scorer was below threshold. The caller runs its classifier; if it+ /// has none (or it fails), fall open to `default_tier`.+ ConsultClassifier {+ /// Signed scorer value, for logging.+ score: f64,+ /// Scorer confidence, for logging.+ confidence: f64,+ /// Tier to fall open to when no classifier resolves it.+ default_tier: Tier,+ },+}++/// Project a [`ToolSignals`] onto the two-axis dimension space.+pub fn dimensions_from_signal(signal: &ToolSignals) -> CodingAgentDimensions {+ let recent_ops = signal.recent_write_count+ + signal.recent_edit_count+ + signal.recent_read_count+ + signal.recent_todowrite_count;+ let deep_enough = signal.turn_depth >= STALL_MIN_TURN_DEPTH;+ let no_production = signal.recent_write_count == 0 && signal.recent_edit_count == 0;+ let investigating = signal.recent_read_count >= 1 || signal.recent_todowrite_count >= 1;+ // spinning vs exploring partition the "not producing" case by investigative+ // activity, so at most one fires — no double-counting on the production axis.+ let spinning = deep_enough && no_production && !investigating;+ let exploring = deep_enough && no_production && investigating;++ CodingAgentDimensions {+ severity: f64::from(signal.severity),+ spinning: if spinning { 1.0 } else { 0.0 },+ exploring: if exploring { 1.0 } else { 0.0 },+ production_intensity: ratio(+ signal.recent_write_count + signal.recent_edit_count,+ recent_ops,+ ),+ }+}++/// Score a signal: weighted sum of the dimensions, `tanh`-squashed.+///+/// The raw sum is small — one maxed signal is `±0.10`, two corroborating+/// signals `±0.20`. `tanh(gain·raw)` spreads that into a usable range, so the+/// `confidence_threshold` reads roughly: `~0.3` escalates on one signal, `~0.5`+/// needs about one-and-a-half, `~0.7` needs two to corroborate.+pub fn score_signal(signal: &ToolSignals) -> ScoreResult {+ let d = dimensions_from_signal(signal);+ // Error axis (severity, spinning, exploring → +capable) minus the production+ // axis (→ −efficient). Each maxed signal is one SIGNAL_UNIT; severity is+ // normalised by its hard cap so it lands there too.+ let raw = SIGNAL_UNIT+ * (d.severity / HARD_SEVERITY + d.spinning + d.exploring - d.production_intensity);+ let score = (SCORE_GAIN * raw).tanh();+ ScoreResult {+ score,+ confidence: score.abs(),+ }+}++/// Hard **escalate** — force the strong tier no matter what the scorer would+/// say. Fires on a critical error or a compacted context.+fn should_escalate(signal: &ToolSignals) -> bool {+ // Compaction wipes the accumulated signals, so a task that had escalated+ // would snap back to weak — a context big enough to overflow belongs strong.+ if signal.compacted {+ return true;+ }+ // A critical error is unambiguous.+ signal.severity >= SEVERITY_CRITICAL+}++/// Hard **de-escalate** — drop to the cheap tier on a settled turn: tests+/// passed, code was just written or edited, and nothing errored in the window.+fn should_deescalate(signal: &ToolSignals) -> bool {+ signal.tests_passed+ && (signal.recent_write_count + signal.recent_edit_count) >= 1+ && signal.severity <= 0.0+}++/// Decide a turn's tier from its signal.+///+/// The rules run in order; the first that fires wins:+///+/// 1. **Escalate** — a hard reason to go strong (critical error / compaction).+/// 2. **De-escalate** — a hard reason to go cheap (a settled turn).+/// 3. **Scorer** — no hard reason, so weigh the two axes; if confident, follow it.+/// 4. **Fall open** — not confident: hand to the classifier, else the default.+///+/// Rules 1 and 2 are the two hard shortcuts that skip the scorer — one always+/// escalates, one always de-escalates. **Escalate is checked first**, so a+/// critical error still wins on a turn whose tests also happened to pass.+///+/// Deterministic and pure: the async classifier lives in the caller, so rule 4+/// returns [`PickOutcome::ConsultClassifier`] instead of calling it here. The+/// `no_signal` case (no tool activity yet) is handled one level up.+pub fn pick_tier(signal: &ToolSignals, mode: PickerMode, confidence_threshold: f64) -> PickOutcome {+ // 1. Escalate — a hard reason to go strong, ahead of everything else.+ if should_escalate(signal) {+ return resolved(Tier::Capable, DecisionSource::Override, 0.0, Some(1.0));+ }++ // 2. De-escalate — a hard reason to go cheap (the turn is winding down).+ if should_deescalate(signal) {+ return resolved(Tier::Efficient, DecisionSource::TestsPassed, 0.0, None);+ }++ // 3. Scorer — no hard reason either way, so weigh error vs production. If+ // confident enough, follow the sign: positive → strong, negative → cheap.+ let scored = score_signal(signal);+ if scored.confidence >= confidence_threshold {+ let tier = if scored.score > 0.0 {+ Tier::Capable+ } else {+ Tier::Efficient+ };+ return resolved(+ tier,+ DecisionSource::Dimensions,+ scored.score,+ Some(scored.confidence),+ );+ }++ // 4. Fall open — the signals didn't corroborate enough to be sure. Hand off+ // to the caller's classifier; with none, land on the picker's default.+ PickOutcome::ConsultClassifier {+ score: scored.score,+ confidence: scored.confidence,+ default_tier: mode.default_tier(),+ }+}++/// Build a resolved outcome (a decision made without the classifier).+fn resolved(+ tier: Tier,+ source: DecisionSource,+ score: f64,+ confidence: Option<f64>,+) -> PickOutcome {+ PickOutcome::Resolved {+ tier,+ source,+ score,+ confidence,+ }+}++fn ratio(numerator: u32, denominator: u32) -> f64 {+ if denominator == 0 {+ 0.0+ } else {+ f64::from(numerator) / f64::from(denominator)+ }+}++/// Signal-only stage-router classifier: scores each turn onto the strong/weak+/// tiers from tool-result signals, via the configured picker mode and the+/// confidence the scorer must reach before it acts on the signal alone.+pub struct StageClassifier {+ mode: PickerMode,+ confidence_threshold: f64,+}++impl StageClassifier {+ /// Build a classifier with the given default tier (`mode`) and+ /// `confidence_threshold`.+ pub fn new(mode: PickerMode, confidence_threshold: f64) -> Self {+ Self {+ mode,+ confidence_threshold,+ }+ }+}++#[async_trait]+impl Classifier for StageClassifier {+ async fn score(+ &self,+ state: &mut State,+ _request: &Request,+ _driver: Option<&Driver>,+ ) -> Result<Classification> {+ let tool_signals = &state.tool_signals;+ let Some(signal) = tool_signals else {+ // No tool activity yet — nothing to score, so fall open to the+ // picker's configured default tier (same as a below-threshold turn).+ let target = match self.mode.default_tier() {+ Tier::Capable => "strong",+ Tier::Efficient => "weak",+ };+ state.extra.insert(+ "default_target".to_string(),+ StateValue::String(target.to_string()),+ );+ state.extra.insert(+ "decision_source".to_string(),+ StateValue::String(DecisionSource::FallOpen.as_str().to_string()),+ );+ return Ok(Classification::Ambiguous(vec![Score {+ target: target.to_string(),+ confidence: 0.0,+ }]));+ };++ let outcome = pick_tier(signal, self.mode, self.confidence_threshold);+ match outcome {+ PickOutcome::Resolved {+ tier,+ source,+ score,+ ..+ } => {+ let target = match tier {+ Tier::Capable => "strong",+ Tier::Efficient => "weak",+ };+ state.extra.insert(+ "decision_source".to_string(),+ StateValue::String(source.as_str().to_string()),+ );+ let conf = score.abs();+ // TODO add the non-target to this score set?+ Ok(Classification::Scores(vec![Score {+ target: target.to_string(),+ confidence: conf,+ }]))+ }+ PickOutcome::ConsultClassifier {+ score,+ default_tier,+ ..+ } => {+ let target = match default_tier {+ Tier::Capable => "strong",+ Tier::Efficient => "weak",+ };+ state.extra.insert(+ "default_target".to_string(),+ StateValue::String(target.to_string()),+ );+ state.extra.insert(+ "decision_source".to_string(),+ StateValue::String(DecisionSource::FallOpen.as_str().to_string()),+ );+ let conf = score.abs();+ // TODO add the non-target to this score set?+ Ok(Classification::Ambiguous(vec![Score {+ target: target.to_string(),+ confidence: conf,+ }]))+ }+ }+ }+}++#[cfg(test)]+mod tests {+ use super::*;+ use serde_json::json;+ use switchyard_protocol::{Metadata, Request, WireFormat};++ fn signal_from(messages: serde_json::Value) -> ToolSignals {+ let raw_request = Some(json!({"model": "m", "messages": messages}));+ let request = Request {+ raw_request,+ metadata: Some(Metadata {+ wire_format: Some(WireFormat::OpenAiChat),+ ..Default::default()+ }),+ ..Default::default()+ };+ ToolSignals::from_request(&request, None)+ }++ #[test]+ fn critical_severity_overrides_to_capable() {+ let mut signal = signal_from(json!([{"role": "user", "content": "hi"}]));+ signal.severity = SEVERITY_CRITICAL;+ match pick_tier(&signal, PickerMode::EfficientFirst, 0.5) {+ PickOutcome::Resolved { tier, source, .. } => {+ assert_eq!(tier, Tier::Capable);+ assert_eq!(source, DecisionSource::Override);+ }+ other => panic!("expected override, got {other:?}"),+ }+ }++ #[test]+ fn compaction_overrides_to_capable() {+ let mut signal = signal_from(json!([{"role": "user", "content": "hi"}]));+ signal.compacted = true;+ assert!(matches!(+ pick_tier(&signal, PickerMode::EfficientFirst, 0.5),+ PickOutcome::Resolved {+ tier: Tier::Capable,+ source: DecisionSource::Override,+ ..+ }+ ));+ }++ #[test]+ fn one_signal_scores_below_half() {+ // A single full wrong signal ≈ 0.46 confidence — just under 0.5.+ let mut signal = signal_from(json!([{"role": "user", "content": "hi"}]));+ signal.severity = HARD_SEVERITY as f32;+ let scored = score_signal(&signal);+ assert!(scored.score > 0.0);+ assert!(+ scored.confidence < 0.5,+ "one signal should not clear 0.5: {scored:?}"+ );+ }++ #[test]+ fn quiet_signal_falls_open_to_default() {+ let signal = signal_from(json!([{"role": "user", "content": "hi"}]));+ match pick_tier(&signal, PickerMode::EfficientFirst, 0.5) {+ PickOutcome::ConsultClassifier { default_tier, .. } => {+ assert_eq!(default_tier, Tier::Efficient);+ }+ other => panic!("expected consult-classifier, got {other:?}"),+ }+ }++ // ─── StageClassifier ─────────────────────────────────────────────────++ /// A `State` carrying `signal` as its tool signals.+ fn state_with(signal: ToolSignals) -> State {+ State {+ tool_signals: Some(signal),+ ..Default::default()+ }+ }++ #[tokio::test]+ async fn classifier_defaults_without_tool_signals() -> Result<()> {+ // No tool activity yet → route to the picker's configured default tier+ // (efficient_first → weak), recorded in `extra` for the caller.+ let mut state = State::default();+ let classification = StageClassifier::new(PickerMode::EfficientFirst, 0.5)+ .score(&mut state, &Request::default(), None)+ .await?;+ match classification {+ Classification::Ambiguous(scores) => {+ assert_eq!(scores.len(), 1);+ assert_eq!(scores[0].target, "weak");+ }+ _ => panic!("expected an ambiguous default classification"),+ }+ assert!(matches!(+ state.extra.get("default_target"),+ Some(StateValue::String(target)) if target == "weak"+ ));+ assert!(matches!(+ state.extra.get("decision_source"),+ Some(StateValue::String(source)) if source == "fall_open"+ ));+ Ok(())+ }++ #[tokio::test]+ async fn classifier_escalates_critical_severity_to_strong() -> Result<()> {+ // Critical severity is a hard override → a definite score for the strong tier.+ let signal = ToolSignals {+ severity: SEVERITY_CRITICAL,+ ..Default::default()+ };+ let mut state = state_with(signal);+ let classification = StageClassifier::new(PickerMode::EfficientFirst, 0.5)+ .score(&mut state, &Request::default(), None)+ .await?;+ match classification {+ Classification::Scores(scores) => {+ assert_eq!(scores.len(), 1);+ assert_eq!(scores[0].target, "strong");+ }+ _ => panic!("expected a definite classification"),+ }+ // The decision source travels downstream (for handoff-note gating).+ assert!(matches!(+ state.extra.get("decision_source"),+ Some(StateValue::String(source)) if source == "override"+ ));+ Ok(())+ }++ #[tokio::test]+ async fn classifier_deescalates_settled_turn_to_weak() -> Result<()> {+ // Tests passed with recent production and no error → the settled-turn shortcut+ // resolves straight to a definite weak-tier score.+ let signal = ToolSignals {+ tests_passed: true,+ recent_write_count: 1,+ severity: 0.0,+ ..Default::default()+ };+ let mut state = state_with(signal);+ let classification = StageClassifier::new(PickerMode::EfficientFirst, 0.5)+ .score(&mut state, &Request::default(), None)+ .await?;+ match classification {+ Classification::Scores(scores) => {+ assert_eq!(scores.len(), 1);+ assert_eq!(scores[0].target, "weak");+ }+ _ => panic!("expected a definite classification"),+ }+ Ok(())+ }++ #[tokio::test]+ async fn classifier_falls_open_to_default_and_records_it() -> Result<()> {+ // A quiet signal corroborates neither axis → ambiguous, defaulting to the+ // efficient (weak) tier, which is also stashed in `extra` for the caller.+ let mut state = state_with(ToolSignals::default());+ let classification = StageClassifier::new(PickerMode::EfficientFirst, 0.5)+ .score(&mut state, &Request::default(), None)+ .await?;+ match classification {+ Classification::Ambiguous(scores) => {+ assert_eq!(scores.len(), 1);+ assert_eq!(scores[0].target, "weak");+ }+ _ => panic!("expected an ambiguous classification"),+ }+ assert!(matches!(+ state.extra.get("default_target"),+ Some(StateValue::String(target)) if target == "weak"+ ));+ assert!(matches!(+ state.extra.get("decision_source"),+ Some(StateValue::String(source)) if source == "fall_open"+ ));+ Ok(())+ }++ #[tokio::test]+ async fn classifier_honors_configured_mode_on_fall_open() -> Result<()> {+ // Same quiet signal, but capable_first defaults the fall-open to strong —+ // proving the configured picker mode is used, not a hardcoded default.+ let mut state = state_with(ToolSignals::default());+ let classification = StageClassifier::new(PickerMode::CapableFirst, 0.5)+ .score(&mut state, &Request::default(), None)+ .await?;+ match classification {+ Classification::Ambiguous(scores) => {+ assert_eq!(scores.len(), 1);+ assert_eq!(scores[0].target, "strong");+ }+ _ => panic!("expected an ambiguous classification"),+ }+ assert!(matches!(+ state.extra.get("default_target"),+ Some(StateValue::String(target)) if target == "strong"+ ));+ Ok(())+ }+}diff --git a/crates/libsy/src/signal/tool_signals.rs b/crates/libsy/src/algorithms/util/tool_signals.rssimilarity index 97%rename from crates/libsy/src/signal/tool_signals.rsrename to crates/libsy/src/algorithms/util/tool_signals.rsindex 91b4ffaa6..570af5fa2 100644--- a/crates/libsy/src/signal/tool_signals.rs+++ b/crates/libsy/src/algorithms/util/tool_signals.rs@@ -11,9 +11,16 @@//!//! All logic is pure and deterministic — no I/O, no shared state.+#![allow(dead_code)]++use async_trait::async_trait;use serde_json::Value;use switchyard_protocol::{Request, WireFormat};+use crate::Result;++use crate::{Event, Processor, State};+// ─── severity constants ───────────────────────────────────────────────────────const SOFT: f32 = 0.3;@@ -176,11 +183,11 @@ static NUMERIC_FAILURE_KEYWORDS: &[&str] = &["failed", "failure", "failures", "e/// Default sliding-window size for `recent_*` counts and windowed severity.///-/// A 5-call horizon captures "what is the agent doing right now" while keeping+/// A short horizon captures "what is the agent doing right now" while keeping/// signals sticky — an error or stall persists a few recovery turns instead of/// flickering off the moment one clean result lands. Override per-extractor by/// calling [`extract_tool_signals_with_window`] directly.-pub const DEFAULT_RECENT_WINDOW: usize = 5;+pub const DEFAULT_RECENT_WINDOW: usize = 3;// ─── output type ─────────────────────────────────────────────────────────────@@ -249,6 +256,34 @@ enum ToolCategory {Other,}+/// Request-side processor that extracts tool-result signals from each request+/// and stores them on the request `State` for downstream routing.+#[derive(Debug, Clone)]+pub struct ToolSignalProcessor {+ /// Number of trailing tool results the `recent_*` counts and windowed+ /// severity are computed over.+ pub recent_window: usize,+}++impl Default for ToolSignalProcessor {+ fn default() -> Self {+ Self {+ recent_window: DEFAULT_RECENT_WINDOW,+ }+ }+}++#[async_trait]+impl Processor for ToolSignalProcessor {+ async fn process(&self, state: &mut State, event: Event<'_>) -> Result<()> {+ if let Event::Request(req) = event {+ let tool_signal = ToolSignals::from_request(req, Some(self.recent_window));+ state.tool_signals = Some(tool_signal);+ }+ Ok(())+ }+}+fn classify_tool_call(name: &str, command: Option<&str>) -> ToolCategory {let lower = name.to_lowercase();if WRITE_TOOL_NAMES.contains(&lower.as_str()) {@@ -879,8 +914,8 @@ mod tests {#[test]fn recent_window_counts_only_last_default_window_tool_calls() {- // 5 writes + 1 edit at the end → the default window (5) should see- // the last 5 calls: 1 edit + 4 writes (not all 6 calls).+ // 5 writes + 1 edit at the end → the default window (3) should see+ // the last 3 calls: 1 edit + 2 writes (not all 6 calls).let request = openai_chat_request(json!({"messages": [{"role": "assistant", "tool_calls": [{"function": {"name": "Write"}}]},@@ -900,7 +935,7 @@ mod tests {let sig = ToolSignals::from_request(&request, None);assert_eq!(sig.write_count, 5);assert_eq!(sig.edit_count, 1);- assert_eq!(sig.recent_write_count, 4);+ assert_eq!(sig.recent_write_count, 2);assert_eq!(sig.recent_edit_count, 1);}diff --git a/crates/libsy/src/core/state.rs b/crates/libsy/src/core/state.rsindex 330ca3e7f..51d4812d7 100644--- a/crates/libsy/src/core/state.rs+++ b/crates/libsy/src/core/state.rs@@ -6,6 +6,8 @@ use std::sync::Arc;use tokio::sync::Mutex;+use crate::ToolSignals;+/// A value in a session's [`State`].#[derive(Debug, Clone)]pub enum StateValue {@@ -19,6 +21,10 @@ pub enum StateValue {#[derive(Debug, Clone, Default)]pub struct State {pub turn_count: u32,+ /// Tool-result signals for the current request, set by the tool-signal+ /// processor. `None` until it runs or when the request has no tool activity,+ /// so routers must treat absence as "no signal yet".+ pub tool_signals: Option<ToolSignals>,pub extra: HashMap<String, StateValue>,}diff --git a/crates/libsy/src/lib.rs b/crates/libsy/src/lib.rsindex 8270ff8b8..c59a48e0c 100644--- a/crates/libsy/src/lib.rs+++ b/crates/libsy/src/lib.rs@@ -86,5 +86,15 @@ pub use error::{DriverError, LibsyError, Result};pub mod algorithms;mod observability;-mod signal;-pub use signal::{ToolSignals, DEFAULT_RECENT_WINDOW};+pub use algorithms::util::tool_signals::{ToolSignals, DEFAULT_RECENT_WINDOW};++/// Stage-router scoring and tier selection — the shared signal-driven routing+/// core (scorer, picker, and the `StageClassifier`).+// TODO cleanup once switchyard-components is removed+pub mod stage_router {+ pub use crate::algorithms::util::handoff_notes::{HandoffNoteProcessor, HANDOFF_NOTE_KEY};+ pub use crate::algorithms::util::stage_router::{+ dimensions_from_signal, pick_tier, score_signal, CodingAgentDimensions, DecisionSource,+ PickOutcome, PickerMode, ScoreResult, StageClassifier, Tier,+ };+}diff --git a/crates/libsy/src/signal.rs b/crates/libsy/src/signal.rsdeleted file mode 100644index 4a705550f..000000000--- a/crates/libsy/src/signal.rs+++ /dev/null@@ -1,5 +0,0 @@-// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.-// SPDX-License-Identifier: Apache-2.0--pub mod tool_signals;-pub use tool_signals::{ToolSignals, DEFAULT_RECENT_WINDOW};diff --git a/crates/switchyard-components/src/stage_router.rs b/crates/switchyard-components/src/stage_router.rsindex cf8c7d83a..f961fcf0e 100644--- a/crates/switchyard-components/src/stage_router.rs+++ b/crates/switchyard-components/src/stage_router.rs@@ -1,340 +1,15 @@// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.// SPDX-License-Identifier: Apache-2.0-//! Stage-router scoring and tier selection — the shared routing core.+//! Stage-router tier selection — thin re-export of libsy's decision core.//!-//! Decides whether a coding-agent turn goes to the **capable** (strong) or-//! **efficient** (weak) tier from its [`ToolResultSignal`]. Single source of-//! truth, shared by the Rust profile and the Python processor via bindings —-//! only the outer shell differs in how it fetches the decision.-//!-//! Two axes: **error** (`severity`) and **production** (`spinning`/`exploring`-//! push toward capable, `production_intensity` toward efficient). Scored,-//! `tanh`-squashed to `(-1, +1)`, dialed by `confidence_threshold`. See-//! [`pick_tier`] for the decision ladder.--use crate::dimension_collector::ToolResultSignal;--/// Turn depth below which stall signals stay quiet — early no-write turns are-/// normal exploration, not a stall.-const STALL_MIN_TURN_DEPTH: u32 = 8;-/// Gain applied before the tanh squash — spreads the small raw weighted sum-/// across the usable confidence range. Without it confidence would cap near-/// ±0.20 and mid/high thresholds would be unreachable.-const SCORE_GAIN: f64 = 5.0;-/// Strongest error severity the scorer sees: critical (`1.0`) is caught by the-/// override, so hard (`0.7`) normalises `severity` to one signal unit.-const HARD_SEVERITY: f64 = 0.7;-/// Weight one maxed signal contributes. Small enough that no single axis pegs-/// the decision; corroboration across the two axes is what raises confidence.-const SIGNAL_UNIT: f64 = 0.10;-/// Critical severity forces the capable tier regardless of the scorer.-const SEVERITY_CRITICAL: f32 = 1.0;--/// The two tiers a turn can route to.-#[derive(Clone, Copy, Debug, Eq, PartialEq)]-pub enum Tier {- /// Weak / cheap tier.- Efficient,- /// Strong / capable tier.- Capable,-}--/// Which tier to default to when the scorer is not confident.-#[derive(Clone, Copy, Debug, Eq, PartialEq)]-pub enum PickerMode {- /// Default to capable unless the scorer confidently picks efficient.- CapableFirst,- /// Default to efficient unless the scorer confidently picks capable.- EfficientFirst,-}--impl PickerMode {- fn default_tier(self) -> Tier {- match self {- Self::CapableFirst => Tier::Capable,- Self::EfficientFirst => Tier::Efficient,- }- }-}--/// What produced a decision — for stats and explainability.-#[derive(Clone, Copy, Debug, Eq, PartialEq)]-pub enum DecisionSource {- /// Hard override (critical severity or context compaction).- Override,- /// Settled run: recent tests passed with recent production and no error.- TestsPassed,- /// Scorer crossed `confidence_threshold`.- Dimensions,- /// Scorer was not confident; the caller should consult its classifier.- FallOpen,-}--impl DecisionSource {- /// Stable lowercase label used in stats.- pub fn as_str(self) -> &'static str {- match self {- Self::Override => "override",- Self::TestsPassed => "tests_passed",- Self::Dimensions => "dimensions",- Self::FallOpen => "fall_open",- }- }-}--/// A signed score in `(-1, +1)` and its magnitude. `confidence == score.abs()`.-#[derive(Clone, Copy, Debug, PartialEq)]-pub struct ScoreResult {- /// Signed score: positive → capable, negative → efficient.- pub score: f64,- /// Decision certainty, `score.abs()`.- pub confidence: f64,-}--/// The two-axis feature view of a single [`ToolResultSignal`].-#[derive(Clone, Copy, Debug, PartialEq)]-pub struct CodingAgentDimensions {- /// Windowed max error severity in `[0, 1]`.- pub severity: f64,- /// `1.0` when a deep turn has no reads, plans, writes, or edits (pure churn).- pub spinning: f64,- /// `1.0` when a deep turn reads/plans but does not write or edit.- pub exploring: f64,- /// Fraction of recent tool ops that produced code (writes + edits).- pub production_intensity: f64,-}--/// Outcome of [`pick_tier`]: either a resolved decision, or a signal that the-/// caller should consult its (impl-specific, async) classifier.-#[derive(Clone, Copy, Debug, PartialEq)]-pub enum PickOutcome {- /// The tier was decided without the classifier.- Resolved {- /// The chosen tier.- tier: Tier,- /// What produced it.- source: DecisionSource,- /// Signed scorer value (`0.0` for override / tests-passed).- score: f64,- /// Scorer confidence (`None` where the scorer did not run).- confidence: Option<f64>,- },- /// The scorer was below threshold. The caller runs its classifier; if it- /// has none (or it fails), fall open to `default_tier`.- ConsultClassifier {- /// Signed scorer value, for logging.- score: f64,- /// Scorer confidence, for logging.- confidence: f64,- /// Tier to fall open to when no classifier resolves it.- default_tier: Tier,- },-}--/// Project a [`ToolResultSignal`] onto the two-axis dimension space.-pub fn dimensions_from_signal(signal: &ToolResultSignal) -> CodingAgentDimensions {- let recent_ops = signal.recent_write_count- + signal.recent_edit_count- + signal.recent_read_count- + signal.recent_todowrite_count;- let deep_enough = signal.turn_depth >= STALL_MIN_TURN_DEPTH;- let no_production = signal.recent_write_count == 0 && signal.recent_edit_count == 0;- let investigating = signal.recent_read_count >= 1 || signal.recent_todowrite_count >= 1;- // spinning vs exploring partition the "not producing" case by investigative- // activity, so at most one fires — no double-counting on the production axis.- let spinning = deep_enough && no_production && !investigating;- let exploring = deep_enough && no_production && investigating;-- CodingAgentDimensions {- severity: f64::from(signal.severity),- spinning: if spinning { 1.0 } else { 0.0 },- exploring: if exploring { 1.0 } else { 0.0 },- production_intensity: ratio(- signal.recent_write_count + signal.recent_edit_count,- recent_ops,- ),- }-}--/// Score a signal on the two axes, `tanh`-squashed to `(-1, +1)`.-///-/// One maxed signal reads ~`0.46` confidence, two ~`0.76` — so the threshold-/// dials corroboration: `~0.3` clears on one signal, `~0.5` on ~1.5, `~0.7` on two.-pub fn score_signal(signal: &ToolResultSignal) -> ScoreResult {- let d = dimensions_from_signal(signal);- // Error axis (severity, spinning, exploring → +capable) minus the production- // axis (→ −efficient). Each maxed signal is one SIGNAL_UNIT; severity is- // normalised by its hard cap so it lands there too.- let raw = SIGNAL_UNIT- * (d.severity / HARD_SEVERITY + d.spinning + d.exploring - d.production_intensity);- let score = (SCORE_GAIN * raw).tanh();- ScoreResult {- score,- confidence: score.abs(),- }-}--/// Hard **escalate** — force the strong tier no matter what the scorer would-/// say. Fires on a critical error or a compacted context.-fn should_escalate(signal: &ToolResultSignal) -> bool {- // Compaction wipes the accumulated signals, so a task that had escalated- // would snap back to weak — a context big enough to overflow belongs strong.- if signal.compacted {- return true;- }- // A critical error is unambiguous.- signal.severity >= SEVERITY_CRITICAL-}--/// Hard **de-escalate** — drop to the cheap tier on a settled turn: tests-/// passed, code was just written or edited, and nothing errored in the window.-fn should_deescalate(signal: &ToolResultSignal) -> bool {- signal.tests_passed- && (signal.recent_write_count + signal.recent_edit_count) >= 1- && signal.severity <= 0.0-}--/// Decide a turn's tier from its signal.-///-/// The rules run in order; the first that fires wins:-///-/// 1. **Escalate** — a hard reason to go strong (critical error / compaction).-/// 2. **De-escalate** — a hard reason to go cheap (a settled turn).-/// 3. **Scorer** — no hard reason, so weigh the two axes; if confident, follow it.-/// 4. **Fall open** — not confident: hand to the classifier, else the default.-///-/// Rules 1 and 2 are the two hard shortcuts that skip the scorer — one always-/// escalates, one always de-escalates. **Escalate is checked first**, so a-/// critical error still wins on a turn whose tests also happened to pass.-///-/// Deterministic and pure: the async classifier lives in the caller, so rule 4-/// returns [`PickOutcome::ConsultClassifier`] instead of calling it here. The-/// `no_signal` case (no tool activity yet) is handled one level up.-pub fn pick_tier(- signal: &ToolResultSignal,- mode: PickerMode,- confidence_threshold: f64,-) -> PickOutcome {- // 1. Escalate — a hard reason to go strong, ahead of everything else.- if should_escalate(signal) {- return resolved(Tier::Capable, DecisionSource::Override, 0.0, Some(1.0));- }-- // 2. De-escalate — a hard reason to go cheap (the turn is winding down).- if should_deescalate(signal) {- return resolved(Tier::Efficient, DecisionSource::TestsPassed, 0.0, None);- }-- // 3. Scorer — no hard reason either way, so weigh error vs production. If- // confident enough, follow the sign: positive → strong, negative → cheap.- let scored = score_signal(signal);- if scored.confidence >= confidence_threshold {- let tier = if scored.score > 0.0 {- Tier::Capable- } else {- Tier::Efficient- };- return resolved(- tier,- DecisionSource::Dimensions,- scored.score,- Some(scored.confidence),- );- }-- // 4. Fall open — the signals didn't corroborate enough to be sure. Hand off- // to the caller's classifier; with none, land on the picker's default.- PickOutcome::ConsultClassifier {- score: scored.score,- confidence: scored.confidence,- default_tier: mode.default_tier(),- }-}--/// Build a resolved outcome (a decision made without the classifier).-fn resolved(- tier: Tier,- source: DecisionSource,- score: f64,- confidence: Option<f64>,-) -> PickOutcome {- PickOutcome::Resolved {- tier,- source,- score,- confidence,- }-}--fn ratio(numerator: u32, denominator: u32) -> f64 {- if denominator == 0 {- 0.0- } else {- f64::from(numerator) / f64::from(denominator)- }-}--#[cfg(test)]-mod tests {- use super::*;- use crate::dimension_collector::extract_tool_signals;- use serde_json::json;- use switchyard_core::ChatRequest;-- fn signal_from(messages: serde_json::Value) -> ToolResultSignal {- let request = ChatRequest::openai_chat(json!({"model": "m", "messages": messages}));- extract_tool_signals(&request)- }-- #[test]- fn critical_severity_overrides_to_capable() {- let mut signal = signal_from(json!([{"role": "user", "content": "hi"}]));- signal.severity = SEVERITY_CRITICAL;- match pick_tier(&signal, PickerMode::EfficientFirst, 0.5) {- PickOutcome::Resolved { tier, source, .. } => {- assert_eq!(tier, Tier::Capable);- assert_eq!(source, DecisionSource::Override);- }- other => panic!("expected override, got {other:?}"),- }- }-- #[test]- fn compaction_overrides_to_capable() {- let mut signal = signal_from(json!([{"role": "user", "content": "hi"}]));- signal.compacted = true;- assert!(matches!(- pick_tier(&signal, PickerMode::EfficientFirst, 0.5),- PickOutcome::Resolved {- tier: Tier::Capable,- source: DecisionSource::Override,- ..- }- ));- }-- #[test]- fn one_signal_scores_below_half() {- // A single full wrong signal ≈ 0.46 confidence — just under 0.5.- let mut signal = signal_from(json!([{"role": "user", "content": "hi"}]));- signal.severity = HARD_SEVERITY as f32;- let scored = score_signal(&signal);- assert!(scored.score > 0.0);- assert!(- scored.confidence < 0.5,- "one signal should not clear 0.5: {scored:?}"- );- }-- #[test]- fn quiet_signal_falls_open_to_default() {- let signal = signal_from(json!([{"role": "user", "content": "hi"}]));- match pick_tier(&signal, PickerMode::EfficientFirst, 0.5) {- PickOutcome::ConsultClassifier { default_tier, .. } => {- assert_eq!(default_tier, Tier::Efficient);- }- other => panic!("expected consult-classifier, got {other:?}"),- }- }-}+//! The scoring and tier-selection logic lives in [`switchyard_libsy::stage_router`].+//! Its input, a [`ToolResultSignal`][crate::dimension_collector::ToolResultSignal],+//! is already libsy's `ToolSignals`, so no request adaptation is needed here — this+//! module simply re-exports the API so the crate's processors decide a turn's tier+//! through the same implementation the libsy profile uses.++pub use switchyard_libsy::stage_router::{+ dimensions_from_signal, pick_tier, score_signal, CodingAgentDimensions, DecisionSource,+ PickOutcome, PickerMode, ScoreResult, StageClassifier, Tier,+};