fix(routing): preserve modality routing invariants

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

Author: taf2

crates/libsy/src/algorithms/fall_through.rs

@@ -284,7 +284,13 @@ where
                 eligible_targets = ?eligible,
                 "computed modality-compatible targets"
             );
-            if let [target] = eligible.as_slice() {
+            let needs_scoring = self
+                .classifiers
+                .iter()
+                .any(|classifier| classifier.needs_single_eligible_scoring());
+            if let [target] = eligible.as_slice()
+                && !needs_scoring
+            {
                 tracing::info!(
                     target = %target,
                     required_modalities = ?required,

crates/libsy/src/algorithms/rand.rs

@@ -98,10 +98,7 @@ impl RandomClassifier {
     }
 
     /// Samples from compatible targets using their original relative weights.
-    fn select_eligible_target(
-        &self,
-        eligible_targets: &BTreeSet<ModelId>,
-    ) -> Result<Option<ModelId>> {
+    fn select_eligible_target(&self, eligible_targets: &BTreeSet<ModelId>) -> Result<ModelId> {
         let eligible = self
             .targets
             .iter()
@@ -113,13 +110,15 @@ impl RandomClassifier {
             .map(|(_, weight)| **weight)
             .collect::<Vec<_>>();
         if !weights.iter().any(|weight| *weight > 0.0) {
-            return Ok(None);
+            return Err(LibsyError::AlgorithmError {
+                message: "no modality-compatible random target has a positive weight".to_string(),
+            });
         }
         let distribution =
             WeightedIndex::new(weights).map_err(|error| invalid_weights(error.to_string()))?;
         let mut rng = self.rng.lock();
         let index = distribution.sample(&mut *rng);
-        Ok(Some(eligible[index].0.clone()))
+        Ok(eligible[index].0.clone())
     }
 }
 
@@ -134,6 +133,10 @@ impl<S> Classifier<S> for RandomClassifier
 where
     S: Send + 'static,
 {
+    fn needs_single_eligible_scoring(&self) -> bool {
+        true
+    }
+
     async fn score(
         &self,
         _state: &mut S,
@@ -156,15 +159,13 @@ where
         _driver: Option<&Driver>,
         eligible_targets: &BTreeSet<ModelId>,
     ) -> Result<(Classification, Option<Response>)> {
-        let scores = self
-            .select_eligible_target(eligible_targets)?
-            .map(|target| Score {
+        Ok((
+            Classification::Scores(vec![Score {
                 confidence: 1.0,
-                target,
-            })
-            .into_iter()
-            .collect();
-        Ok((Classification::Scores(scores), None))
+                target: self.select_eligible_target(eligible_targets)?,
+            }]),
+            None,
+        ))
     }
 }
 
@@ -447,6 +448,28 @@ mod tests {
         Ok(())
     }
 
+    #[tokio::test]
+    async fn rejects_a_zero_weight_only_compatible_target() -> Result<()> {
+        // Modality filtering must not re-enable a target disabled by a zero weight.
+        let router: Arc<dyn Algorithm> = Arc::new(
+            algorithm(&["text", "vision"], Some(vec![1.0, 0.0]), Some(42))?.with_target_modalities(
+                target_modalities(&[
+                    ("text", &[InputModality::Text]),
+                    ("vision", &[InputModality::Text, InputModality::Image]),
+                ]),
+            ),
+        );
+
+        let error = test_drive(router, image_request(), echo()).await.err();
+
+        assert!(matches!(
+            error,
+            Some(LibsyError::AlgorithmError { message })
+                if message == "no modality-compatible random target has a positive weight"
+        ));
+        Ok(())
+    }
+
     #[tokio::test]
     async fn affinity_reuses_the_initial_random_selection() -> Result<()> {
         let names = ["a/model", "b/model"];
@@ -502,7 +525,7 @@ mod tests {
         let affinity = Arc::new(AffinityRouter::new());
         let random = Arc::new(RandomClassifier::new(
             target_set(&names),
-            Some(vec![1.0, 0.0]),
+            Some(vec![100.0, 1.0]),
             Some(42),
         )?);
         let algorithm: Arc<dyn Algorithm> = Arc::new(

crates/libsy/src/core/classifier.rs

@@ -92,6 +92,11 @@ pub trait Classifier<S = ()>: Send + Sync {
         None
     }
 
+    /// Whether this classifier must score when modality filtering leaves one eligible target.
+    fn needs_single_eligible_scoring(&self) -> bool {
+        false
+    }
+
     /// Score the classifier's targets given the current state and request.
     ///
     /// When present, `driver` lets a classifier offload model calls. It is `None`

crates/switchyard-server/src/config.rs

@@ -174,6 +174,14 @@ impl ServerConfig {
                 .map(|modalities| modalities.iter().copied().collect::<BTreeSet<_>>())
                 .ok_or_else(|| ServerError::new("validated target modalities were missing"))?;
             advertised.extend(modalities.iter().copied());
+            if let Some(existing) = target_modalities.get(&target.id)
+                && existing != &modalities
+            {
+                return Err(ServerError::new(format!(
+                    "route {route_name} maps model id {} to conflicting input_modalities",
+                    target.id
+                )));
+            }
             target_modalities.insert(target.id.clone(), modalities);
         }
         Ok((Some(target_modalities), advertised.into_iter().collect()))
@@ -1319,6 +1327,62 @@ target = "weak"
         );
     }
 
+    #[test]
+    fn duplicate_model_ids_require_matching_route_modalities() {
+        const DUPLICATE_MODEL_CONFIG: &str = r#"
+schema_version = 1
+
+[llm_clients.primary]
+format = "openai_chat"
+base_url = "https://example.test/v1"
+
+[targets.first]
+id = "shared/model"
+llm_client = "primary"
+input_modalities = ["text", "image"]
+
+[targets.second]
+id = "shared/model"
+llm_client = "primary"
+input_modalities = ["image", "text"]
+
+[routes.shared]
+id = "switchyard/shared"
+type = "random"
+targets = ["first", "second"]
+"#;
+
+        // Repeated declarations for one model id may differ in ordering, but not content.
+        let config: ServerConfig =
+            toml::from_str(DUPLICATE_MODEL_CONFIG).expect("test config should parse");
+        let route = config
+            .routes
+            .get("shared")
+            .expect("test route should exist");
+        let (target_modalities, advertised) = config
+            .route_modalities("shared", route)
+            .expect("matching declarations should be accepted");
+        assert_eq!(
+            target_modalities
+                .expect("target modalities should be declared")
+                .get(&ModelId::from("shared/model")),
+            Some(&BTreeSet::from(
+                [InputModality::Text, InputModality::Image,]
+            ))
+        );
+        assert_eq!(advertised, [InputModality::Text, InputModality::Image]);
+
+        let conflicting = DUPLICATE_MODEL_CONFIG.replace(
+            "input_modalities = [\"image\", \"text\"]",
+            "input_modalities = [\"text\"]",
+        );
+        assert!(
+            error_message(&conflicting).contains(
+                "route shared maps model id shared/model to conflicting input_modalities"
+            )
+        );
+    }
+
     #[test]
     fn judge_modality_declarations_require_text_but_are_optional() -> ServerResult<()> {
         // Undeclared judge capabilities retain the legacy behavior.

crates/switchyard-server/tests/server.rs

@@ -2069,7 +2069,7 @@ input_modalities = ["text", "image"]
 id = "switchyard/multimodal"
 type = "random"
 targets = ["text", "vision"]
-weights = [1, 0]
+weights = [1, 1]
 "#,
         base_url = upstream.base_url,
     ))?;

switchyard/cli/launchers/codex_cli_launcher.py

@@ -177,10 +177,18 @@ def _run_codex_with_switchyard(
             )
             return 1
         use_openai_auth = caller_auth == "openai"
+        modalities_by_model = {display_model: input_modalities}
+        for entry_model, _display, _description in codex_model_catalog:
+            if entry_model in modalities_by_model:
+                continue
+            try:
+                modalities_by_model[entry_model] = server.input_modalities(entry_model)
+            except ValueError:
+                continue
         model_catalog_json = _write_codex_model_catalog(
             codex_bin,
             codex_model_catalog,
-            input_modalities_by_model={display_model: input_modalities},
+            input_modalities_by_model=modalities_by_model,
         )
         command = _codex_command(
             codex_bin,

switchyard/cli/launchers/codex_model_catalog.py

@@ -121,11 +121,7 @@ def _build_codex_model_catalog(
         model["supported_in_api"] = True
         model["availability_nux"] = None
         model["upgrade"] = None
-        modalities = (
-            input_modalities_by_model.get(model_id, ("text",))
-            if input_modalities_by_model is not None
-            else ("text",)
-        )
+        modalities = (input_modalities_by_model or {}).get(model_id, ("text",))
         model["input_modalities"] = list(modalities)
         models.append(model)
     return {"models": models}

tests/test_launchers.py

@@ -153,6 +153,79 @@ def test_codex_catalog_uses_route_modalities_and_defaults_undeclared_to_text(
     assert undeclared["models"][0]["input_modalities"] == ["text"]
 
 
+def test_codex_launcher_discovers_modalities_for_every_catalog_entry(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    import switchyard.cli.launchers.codex_cli_launcher as launcher
+
+    class FakeServer:
+        port = 4321
+        stats = object()
+
+        def __init__(self) -> None:
+            self.queried_models: list[str] = []
+            self.closed = False
+
+        def caller_auth_kind(self, model: str) -> str | None:
+            assert model == "switchyard/text"
+            return None
+
+        def input_modalities(self, model: str) -> list[str]:
+            self.queried_models.append(model)
+            return {
+                "switchyard/text": ["text"],
+                "switchyard/vision": ["text", "image"],
+            }[model]
+
+        def close(self) -> None:
+            self.closed = True
+
+    server = FakeServer()
+    captured_modalities: dict[str, list[str]] = {}
+
+    def write_catalog(
+        _codex_bin: str,
+        _entries: object,
+        input_modalities_by_model: dict[str, list[str]] | None = None,
+    ) -> None:
+        captured_modalities.update(input_modalities_by_model or {})
+
+    monkeypatch.setattr(launcher, "_find_codex_binary", lambda: "codex")
+    monkeypatch.setattr(launcher, "silence_launch_loggers", lambda **_kwargs: None)
+    monkeypatch.setattr(
+        launcher,
+        "configure_debug_file_logging",
+        lambda **_kwargs: tmp_path / "switchyard.log",
+    )
+    monkeypatch.setattr(launcher, "_start_native_server", lambda _config: server)
+    monkeypatch.setattr(launcher, "_write_codex_model_catalog", write_catalog)
+    monkeypatch.setattr(launcher, "_wait_ready", lambda _port: True)
+    monkeypatch.setattr(launcher, "print_ready_banner", lambda **_kwargs: None)
+    monkeypatch.setattr(launcher, "stdin_is_tty", lambda: False)
+    monkeypatch.setattr(launcher, "_supervise_codex", lambda _command, _env: 0)
+    monkeypatch.setattr(launcher, "print_session_summary", lambda _stats: None)
+    monkeypatch.setattr(launcher, "_remove_codex_model_catalog", lambda _path: None)
+
+    result = launcher._run_codex_with_switchyard(
+        tmp_path / "routes.toml",
+        display_model="switchyard/text",
+        codex_args=[],
+        codex_model_catalog=[
+            ("switchyard/text", "Text", "Text route"),
+            ("switchyard/vision", "Vision", "Vision route"),
+        ],
+    )
+
+    assert result == 0
+    assert server.queried_models == ["switchyard/text", "switchyard/vision"]
+    assert captured_modalities == {
+        "switchyard/text": ["text"],
+        "switchyard/vision": ["text", "image"],
+    }
+    assert server.closed
+
+
 def test_native_server_exposes_route_derived_modalities(tmp_path: Path) -> None:
     config = tmp_path / "modalities.toml"
     config.write_text(