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

fix(routing): select composite stage policy from the classified tier (#1009)

ryan-lempkaf3baf4397aa0
diff --git a/crates/libsy/src/algorithms/stage.rs b/crates/libsy/src/algorithms/stage.rs
index cc565f61f..361025bd5 100644
--- a/crates/libsy/src/algorithms/stage.rs
+++ b/crates/libsy/src/algorithms/stage.rs
@@ -135,6 +135,8 @@ pub struct StageRouterConfig {
pub mode: PickerMode,
/// How much corroboration a decisive pick needs, in `[0.0, 1.0]`.
pub confidence_threshold: f64,
+ /// Threshold after an outer classifier selects capable-first. Defaults to `0.0`.
+ pub capable_first_threshold: f64,
/// Trailing tool results the signals are computed over. `None` uses
/// [`DEFAULT_RECENT_WINDOW`].
pub recent_window: Option<usize>,
@@ -162,6 +164,7 @@ impl StageRouterConfig {
Self {
mode,
confidence_threshold,
+ capable_first_threshold: 0.0,
recent_window: None,
tool_semantics: ToolSemantics::default(),
capable_hold_turns: 2,
@@ -210,19 +213,22 @@ impl Algorithm for StageRouter {
/// Wires the cascade the wrapper drives. Exposed so a composition above can
/// stack a prelude onto it.
pub(crate) fn build_stage_route(config: StageRouterConfig) -> Result<FallThrough<State>> {
- if !(0.0..=1.0).contains(&config.confidence_threshold) {
- return Err(LibsyError::AlgorithmError {
- message: format!(
- "confidence_threshold must be between 0 and 1, got {}",
- config.confidence_threshold
- ),
- });
+ for (name, threshold) in [
+ ("confidence_threshold", config.confidence_threshold),
+ ("capable_first_threshold", config.capable_first_threshold),
+ ] {
+ if !(0.0..=1.0).contains(&threshold) {
+ return Err(LibsyError::AlgorithmError {
+ message: format!("{name} must be between 0 and 1, got {threshold}"),
+ });
+ }
}
config.tool_semantics.validate()?;
let default_tier = config.mode.default_tier();
let fall_open = FallOpen { default_tier };
let mut classifier = StageClassifier::new(config.mode, config.confidence_threshold)
+ .with_capable_first_threshold(config.capable_first_threshold)
.with_capable_hold_turns(config.capable_hold_turns);
if let Some(notes) = config.handoff_notes {
classifier = classifier.with_handoff_notes(notes);
diff --git a/crates/libsy/src/algorithms/util/stage.rs b/crates/libsy/src/algorithms/util/stage.rs
index 67fc0acc8..3453a7f9f 100644
--- a/crates/libsy/src/algorithms/util/stage.rs
+++ b/crates/libsy/src/algorithms/util/stage.rs
@@ -537,6 +537,7 @@ impl HandoffNoteConfig {
pub struct StageClassifier {
mode: PickerMode,
confidence_threshold: f64,
+ capable_first_threshold: f64,
capable_hold_turns: u32,
handoff_notes: Option<HandoffNoteConfig>,
}
@@ -548,11 +549,18 @@ impl StageClassifier {
Self {
mode,
confidence_threshold,
+ capable_first_threshold: 0.0,
capable_hold_turns: 2,
handoff_notes: None,
}
}
+ /// Threshold used when an outer classifier selects capable-first.
+ pub fn with_capable_first_threshold(mut self, threshold: f64) -> Self {
+ self.capable_first_threshold = threshold;
+ self
+ }
+
/// Keep the capable tier for this many requests after an escalation. A
/// clean passing test clears the hold early. Set to zero to disable.
pub fn with_capable_hold_turns(mut self, turns: u32) -> Self {
@@ -639,10 +647,15 @@ impl Classifier<State> for StageClassifier {
if clean_test_pass {
state.extra.remove(&capable_hold_key);
}
+ let (mode, threshold) = match fall_open_tier(state) {
+ Some(Tier::Capable) => (PickerMode::CapableFirst, self.capable_first_threshold),
+ Some(Tier::Efficient) => (PickerMode::EfficientFirst, self.confidence_threshold),
+ None => (self.mode, self.confidence_threshold),
+ };
let outcome = if !clean_test_pass && Self::consume_capable_hold(state, &capable_hold_key) {
resolved(Tier::Capable, DecisionSource::CapableHold, 0.5, Some(1.0))
} else {
- pick_tier(&signal, self.mode, self.confidence_threshold)
+ pick_tier(&signal, mode, threshold)
};
record_score_metrics(&signal, &outcome);
match outcome {
@@ -685,7 +698,7 @@ impl Classifier<State> for StageClassifier {
(DecisionSource::Dimensions, Some(confidence)) => serde_json::json!({
"source": source.as_str(),
"confidence": confidence,
- "threshold": self.confidence_threshold,
+ "threshold": threshold,
}),
_ => serde_json::json!({"source": source.as_str()}),
};
@@ -991,6 +1004,32 @@ mod tests {
}
}
+ #[tokio::test]
+ async fn classified_tier_controls_the_stage_threshold() -> Result<()> {
+ let mut state = state_with(ToolSignals {
+ severity: 0.3,
+ recent_edit_count: 1,
+ tool_result_count: 1,
+ ..Default::default()
+ });
+ for (tier, threshold, expected) in [
+ (Tier::Capable, 0.0, Some(ModelId::from("weak"))),
+ (Tier::Efficient, 0.0, None),
+ (Tier::Capable, 0.5, None),
+ ] {
+ set_fall_open(&mut state, tier);
+ let (classification, _) = StageClassifier::new(PickerMode::EfficientFirst, 0.5)
+ .with_capable_first_threshold(threshold)
+ .score(&mut state, &mut Request::default(), &driver())
+ .await?;
+ assert_eq!(
+ classification.argmax(false)?.map(|score| score.target),
+ expected
+ );
+ }
+ Ok(())
+ }
+
#[tokio::test]
async fn classifier_defaults_without_tool_signals() -> Result<()> {
// No tool activity yet — nothing to score, so the signals have no opinion
diff --git a/crates/switchyard-runner/src/algorithm.rs b/crates/switchyard-runner/src/algorithm.rs
index 646b37a43..c83e9ee76 100644
--- a/crates/switchyard-runner/src/algorithm.rs
+++ b/crates/switchyard-runner/src/algorithm.rs
@@ -578,7 +578,11 @@ pub struct StageTierConfig {
/// The efficient tier.
pub efficient_target: String,
/// How much agreement a decisive pick needs, from 0 to 1.
- pub confidence_threshold: f64,
+ #[serde(default, alias = "efficient_first_threshold")]
+ pub confidence_threshold: Option<f64>,
+ /// Threshold after an outer classifier selects capable-first. Defaults to `0.0`.
+ #[serde(default)]
+ pub capable_first_threshold: f64,
/// How many trailing tool results the signals are scored over.
#[serde(default)]
pub recent_turn_window: Option<usize>,
@@ -1467,7 +1471,13 @@ fn build_algorithm(
"stage_router route {route_name} uses picker \"capable_first\", which is experimental: published thresholds and routing results all come from \"efficient_first\", so there is no calibrated confidence_threshold for it and no measured accuracy or cost. Use \"efficient_first\" unless you are running your own calibration."
);
}
- let mut config = StageRouterConfig::new(*picker, *confidence_threshold);
+ let threshold = confidence_threshold.ok_or_else(|| {
+ AlgorithmConfigError::new(format!(
+ "stage_router route {route_name}: confidence_threshold is required"
+ ))
+ })?;
+ let mut config = StageRouterConfig::new(*picker, threshold);
+ config.capable_first_threshold = tiers.capable_first_threshold;
config.recent_window = *recent_turn_window;
if let Some(turns) = capable_hold_turns {
config.capable_hold_turns = *turns;
@@ -1508,8 +1518,11 @@ fn build_algorithm(
stage,
subagents,
} => {
- let mut stage_config =
- StageRouterConfig::new(PickerMode::EfficientFirst, stage.confidence_threshold);
+ let mut stage_config = StageRouterConfig::new(
+ PickerMode::EfficientFirst,
+ stage.confidence_threshold.unwrap_or(0.5),
+ );
+ stage_config.capable_first_threshold = stage.capable_first_threshold;
stage_config.recent_window = stage.recent_turn_window;
if let Some(turns) = stage.capable_hold_turns {
stage_config.capable_hold_turns = turns;
diff --git a/docs/reference/toml_schema.md b/docs/reference/toml_schema.md
index dd0ca0765..50e9258be 100644
--- a/docs/reference/toml_schema.md
+++ b/docs/reference/toml_schema.md
@@ -385,7 +385,8 @@ one manually.
### `composite`
Composes other algorithms, letting one set another's
-configuration. Today a classifier sets the tier a stage router falls open to when its own signals are not confident, leaving its scoring and escalation logic untouched. See
+configuration. Today a classifier selects the stage router's starting tier and
+confidence threshold. Tool signals still drive escalation and recovery. See
[Composite Routing](../routing_algorithms/composite_routing.md).
| Key | Required | Default | Meaning |
@@ -403,7 +404,8 @@ configuration. Today a classifier sets the tier a stage router falls open to whe
| `classifier.max_output_tokens` | No | `4096` | Maximum completion tokens for the judge verdict. Must be at least `1`. |
| `stage.capable_target` | Yes | — | Capable tier. |
| `stage.efficient_target` | Yes | — | Efficient tier. |
-| `stage.confidence_threshold` | Yes | — | Corroboration a decisive signal needs. In `[0, 1]`. |
+| `stage.efficient_first_threshold` | No | `0.5` | Signal confidence required after an Efficient classification. In `[0, 1]`. Also accepts `confidence_threshold`. |
+| `stage.capable_first_threshold` | No | `0.0` | Signal confidence required after a Capable classification. In `[0, 1]`. |
| `stage.recent_turn_window` | No | `3` | Trailing tool results the signals are computed over. |
| `stage.capable_hold_turns` | No | `2` | Requests kept on the capable tier after escalation. A clean test pass clears the hold early; `0` disables it. |
| `stage.tool_semantics.observe` | No | `[]` | Additional exact ASCII case-insensitive tool names that count as observation. |
diff --git a/docs/routing_algorithms/composite_routing.md b/docs/routing_algorithms/composite_routing.md
index aeab7e976..210736f8e 100644
--- a/docs/routing_algorithms/composite_routing.md
+++ b/docs/routing_algorithms/composite_routing.md
@@ -7,9 +7,13 @@ fit the same route type.
## What exists today
-One pairing: a classifier sets the tier a stage router falls open to when
-its own signals are not confident. The stage router's `picker` mode is unchanged,
-and so is how it scores signals, escalates, and de-escalates. Both algorithms and the
+One pairing: a classifier selects the stage router's starting policy.
+An efficient classification selects efficient-first with `efficient_first_threshold`
+(default `0.5`).
+A capable classification selects capable-first with `capable_first_threshold`
+(default `0.0`). Both thresholds are configurable from `0.0` to `1.0`.
+Tool signals can still change the tier
+during execution. Both algorithms and the
relationship between them are fixed, and the configuration below names them
directly rather than composing arbitrary algorithms.
@@ -36,7 +40,8 @@ classify_trigger = "user_turn"
[routes.switchyard.stage]
capable_target = "strong"
efficient_target = "weak"
-confidence_threshold = 0.5
+efficient_first_threshold = 0.5
+capable_first_threshold = 0.0
[routes.switchyard.stage.tool_semantics]
observe = ["lookup_customer"]
@@ -50,6 +55,7 @@ new = ["send_message"]
whenever the user speaks, `new_session` picks once and holds it.
`[routes.switchyard.stage]` takes the stage settings, but accepts neither `picker`
nor a second `classifier`. The outer classifier supplies the default tier.
+`confidence_threshold` remains an alias for `efficient_first_threshold`.
Custom `tool_semantics` remain stage-local and have the same additive behavior as
on a standalone stage route.