feat(routing): allow classifier target failover to be disabled

Signed-off-by: Todd Fisher <todd.fisher@gmail.com>

Author: taf2

crates/libsy/src/algorithms/fall_through.rs

@@ -13,8 +13,9 @@
 //! private state value across turns with the same session ID. Requests without a session ID use
 //! unretained per-run state.
 //!
-//! The selected target is offered first, followed by every other configured target. The consumer
-//! may fall through that ordered candidate list when a model call fails.
+//! By default, the selected target is offered first, followed by every other configured target.
+//! The consumer may fall through that ordered candidate list when a model call fails. Callers may
+//! disable target failover when a routing decision must remain authoritative.
 
 use std::{
     collections::{BTreeSet, HashMap},
@@ -97,6 +98,7 @@ pub struct FallThrough<S = ()> {
     classifiers: Vec<Arc<dyn Classifier<S>>>,
     targets: Vec<ModelId>,
     target_modalities: Option<TargetModalities>,
+    target_failover: bool,
     session_states: Option<Arc<SessionStates<S>>>,
     cleanup_started: Once,
 }
@@ -111,6 +113,7 @@ impl FallThrough<()> {
             classifiers: Vec::new(),
             targets,
             target_modalities: None,
+            target_failover: true,
             session_states: None,
             cleanup_started: Once::new(),
         }
@@ -130,6 +133,7 @@ where
             classifiers: Vec::new(),
             targets,
             target_modalities: None,
+            target_failover: true,
             session_states: Some(Arc::new(Mutex::new(HashMap::new()))),
             cleanup_started: Once::new(),
         }
@@ -165,6 +169,12 @@ where
         self
     }
 
+    /// Controls whether a failed selected target may fall through to another route target.
+    pub fn with_target_failover(mut self, enabled: bool) -> Self {
+        self.target_failover = enabled;
+        self
+    }
+
     /// Executes the processor/classifier/target-call sequence for wrappers and the trait entrypoint.
     pub(crate) async fn execute(&self, driver: Driver, request: Request) -> Result<Response> {
         self.start_cleanup_task();
@@ -232,6 +242,9 @@ where
 
     /// The selected target first, then every other configured target as a fallback candidate.
     fn candidates(&self, target: &ModelId, eligible: Option<&[ModelId]>) -> Vec<ModelId> {
+        if !self.target_failover {
+            return vec![target.clone()];
+        }
         let candidates = eligible.unwrap_or(&self.targets);
         std::iter::once(target.clone())
             .chain(
@@ -802,6 +815,27 @@ mod tests {
         Err(test_error("expected a CallModel step"))
     }
 
+    #[tokio::test]
+    async fn target_failover_can_be_disabled() -> Result<()> {
+        use futures::StreamExt;
+
+        let router = Arc::new(
+            FallThrough::<()>::new(target_set(&["weak", "mid", "strong"]))
+                .with_target_failover(false)
+                .with_classifier(fixed(vec![score("mid", 0.9)])),
+        );
+        let stream = router.run_stream(request());
+        tokio::pin!(stream);
+        while let Some(step) = stream.next().await {
+            if let crate::Step::CallModel(call) = step? {
+                assert_eq!(call.models, target_set(&["mid"]));
+                assert_eq!(call.request.llm_request.model.as_deref(), Some("mid"));
+                return Ok(());
+            }
+        }
+        Err(test_error("expected a CallModel step"))
+    }
+
     #[tokio::test]
     async fn argmax_picks_the_highest_confidence_target() -> Result<()> {
         let router = FallThrough::<()>::new(target_set(&["strong", "weak"]))

crates/libsy/src/algorithms/llm_class.rs

@@ -705,6 +705,12 @@ impl LlmTaskClassifier {
         self
     }
 
+    /// Controls whether a failed selected target may fall through to another classifier target.
+    pub fn with_target_failover(mut self, enabled: bool) -> Self {
+        self.route = self.route.with_target_failover(enabled);
+        self
+    }
+
     fn build_capability(
         judge_target: ModelId,
         efficient_target: ModelId,

crates/switchyard-server/src/config.rs

@@ -468,6 +468,8 @@ enum RouteConfig {
         tool_calling: Option<bool>,
         #[serde(default)]
         reasoning: Option<bool>,
+        #[serde(default = "enabled_by_default")]
+        target_failover: bool,
         classifier_target: String,
         #[serde(default)]
         mode: Option<ClassifierMode>,
@@ -968,7 +970,9 @@ fn build_algorithm(
             Ok(Arc::new(algorithm))
         }
         RouteConfig::LlmClassifier {
-            classifier_target, ..
+            classifier_target,
+            target_failover,
+            ..
         } => {
             let classifier = resolve_target_model_id(route_name, classifier_target, targets)?;
             let mode = config.classifier_mode(route_name)?;
@@ -1044,6 +1048,7 @@ fn build_algorithm(
             .map_err(|error| {
                 ServerError::new(format!("llm_classifier route {route_name}: {error}"))
             })?;
+            algorithm = algorithm.with_target_failover(*target_failover);
             if let Some(target_modalities) = target_modalities {
                 algorithm = algorithm.with_target_modalities(target_modalities);
             }
@@ -1111,6 +1116,10 @@ fn default_classifier_max_output_tokens() -> u64 {
     TaskClassifierConfig::default().max_output_tokens
 }
 
+const fn enabled_by_default() -> bool {
+    true
+}
+
 /// Keys each configured system prompt by the target it belongs to.
 fn tier_prompts(
     capable: &str,

crates/switchyard-server/tests/server.rs

@@ -113,7 +113,10 @@ async fn upstream_chat(
 
     let model = body["model"].as_str().unwrap_or("unknown").to_string();
     let prompt = body["messages"][0]["content"].as_str().unwrap_or("");
-    if (model == "model/weak" && prompt == "unavailable") || prompt == "all-unavailable" {
+    if (model == "model/weak" && prompt == "unavailable")
+        || (model == "model/premium" && prompt == "premium-unavailable")
+        || prompt == "all-unavailable"
+    {
         return (
             StatusCode::SERVICE_UNAVAILABLE,
             Json(json!({"error": {"message": "upstream is unavailable"}})),
@@ -1086,6 +1089,7 @@ mode = "custom"
 classifier_target = "classifier"
 targets = ["weak", "middle", "strong", "premium"]
 default_target = "strong"
+target_failover = false
 prompt = "CUSTOM MULTI TARGET"
 response_schema = '''
 {{
@@ -1137,6 +1141,32 @@ selector = "/decision/target"
         );
     }
 
+    let previous_call_count = upstream.calls.lock().await.len();
+    let response = send(
+        &app,
+        "POST",
+        "/v1/chat/completions",
+        Some(json!({
+            "model": "switchyard/custom",
+            "messages": [{"role": "user", "content": "premium-unavailable"}]
+        })),
+    )
+    .await?;
+    assert_eq!(response.status, StatusCode::SERVICE_UNAVAILABLE);
+    let calls = upstream.calls.lock().await;
+    let outage_models = calls[previous_call_count..]
+        .iter()
+        .map(|call| call["model"].as_str().unwrap_or(""))
+        .collect::<Vec<_>>();
+    assert_eq!(outage_models.first(), Some(&"model/classifier"));
+    assert!(outage_models.len() > 1);
+    assert!(
+        outage_models[1..]
+            .iter()
+            .all(|model| *model == "model/premium")
+    );
+    drop(calls);
+
     let calls = upstream.calls.lock().await;
     let judge_call = calls
         .iter()

docs/reference/toml_schema.md

@@ -169,6 +169,7 @@ Runs one of three judge-backed modes: `capability`, `escalation`, or `custom`.
 |---|:---:|---|---|
 | `mode` | No | `capability` | Classifier behavior. Set it explicitly for new configurations. |
 | `classifier_target` | Yes | — | Target the judge is called through. Not a routing destination. |
+| `target_failover` | No | `true` | When false, a failed selected completion target returns its error instead of trying another route target. |
 | `max_output_tokens` | No | `4096` | Maximum completion tokens for the judge verdict. Must be at least `1`. |
 | `response_format_type` | No | `json_schema` | Structured-output mode for capability and escalation judges. Use `json_object` when the provider does not support JSON Schema; Switchyard adds the schema to the prompt and validates the verdict locally. Custom mode always uses its configured JSON Schema. |