fix: resolve open OSS QA bugs across libsy, v2 server, CLI, and docs

CHANGELOG.md

@@ -34,9 +34,10 @@ traffic that sits between client applications and LLM backends.
 - **Observability** — Prometheus `/metrics`, a JSON `/v1/stats`
   (`/v1/routing/stats` alias), and per-request cost/token/latency stats. See
   [Metrics Reference](docs/METRICS_REFERENCE.md).
-- **Python library** — `SwitchyardRecipes` (`passthrough_recipe`,
-  `random_routing_recipe`, `stage_router_recipe`, `deterministic_routing_recipe`,
-  …) and typed `ChatRequest` / `ChatResponse` containers for in-process use.
+- **Python library** — `ProfileSwitchyard` driven by typed profile configs
+  (`PassthroughProfileConfig`, `RandomRoutingProfileConfig`,
+  `StageRouterProfileConfig`, …) and typed `ChatRequest` / `ChatResponse`
+  containers for in-process use.
 - **Rust core** (PyO3) — chain execution, the latency-aware router, and the
   tool-result signal collector are implemented in Rust and re-exported to
   Python.

DEVELOPMENT.md

@@ -46,7 +46,7 @@ switchyard/
 │   ├── lib/                       # Core library
 │   │   ├── roles.py               # RequestProcessor, LLMBackend, ResponseProcessor ABCs
 │   │   ├── switchyard.py          # Switchyard chain executor
-│   │   ├── recipes.py             # SwitchyardRecipes (passthrough, random_routing, …)
+│   │   ├── profiles/              # Profile configs/runtimes (passthrough, random_routing, …)
 │   │   ├── proxy_context.py       # ProxyContext — per-request state
 │   │   ├── chat_request/          # Typed request hierarchy
 │   │   ├── chat_response/         # Typed response hierarchy

INSTALLATION.md

@@ -67,7 +67,7 @@ All optional dependencies for complete feature set:
 pip install nemo-switchyard[all]
 ```
 
-Equivalent to: `switchyard[server,cli]`
+Equivalent to: `nemo-switchyard[server,cli,tracing,intake,affinity-redis]`
 
 ### Common Combinations
 
@@ -114,13 +114,13 @@ pip install nemo-switchyard[all]
 Embed Switchyard with minimal overhead:
 
 ```python
-from switchyard import SwitchyardRecipes
+from switchyard import PassthroughProfileConfig, ProfileSwitchyard
 
 # Core library only — no server/CLI dependencies
-switchyard = SwitchyardRecipes.passthrough_recipe(
+switchyard = ProfileSwitchyard(PassthroughProfileConfig(
     api_key="sk-...",
     base_url="https://api.openai.com/v1",
-)
+).build())
 ```
 
 ## Troubleshooting

README.md

@@ -216,7 +216,7 @@ Optional extras:
 ```bash
 pip install "nemo-switchyard[server]"   # FastAPI / Uvicorn HTTP endpoints
 pip install "nemo-switchyard[cli]"      # Interactive CLI launchers (Claude / Codex)
-pip install "nemo-switchyard[all]"      # Server, CLI, and tracing extras
+pip install "nemo-switchyard[all]"      # Server, CLI, tracing, intake, and redis-affinity extras
 ```
 
 See [Installation](INSTALLATION.md) for a full breakdown of what each extra adds.

crates/libsy/Cargo.toml

@@ -16,7 +16,7 @@ async-trait = "0.1"
 serde_json = "1"
 futures = "0.3"
 rand = "0.8"
-switchyard-protocol = { path = "../protocol" }
+switchyard-protocol = { path = "../protocol", version = "0.1.0" }
 tokio = { version = "1", features = ["full"] }
 tokio-stream = "0.1"
 

crates/libsy/src/algorithms/llm_class.rs

@@ -179,16 +179,19 @@ impl Algorithm for LlmClassifier {
                 classify_decision,
             )
             .await?;
-        let score = classify_response
-            .llm_response
-            .as_agg()
-            .map(completion_text)
-            .unwrap_or_default()
+        // Drain a streamed classifier response to its aggregate so a streamed
+        // score is read instead of silently dropped. Keep only a valid
+        // probability in [0.0, 1.0]: NaN, ±inf, and out-of-range values parse
+        // as f64 but are not usable scores, so they collapse to None and fail
+        // open to strong below rather than being treated as a real verdict.
+        let score = completion_text(&classify_response.llm_response.into_agg().await?)
             .trim()
             .parse::<f64>()
-            .ok();
+            .ok()
+            .filter(|s| (0.0..=1.0).contains(s));
 
-        // 2. Route: pick strong/weak. Fail open — an unparseable score routes strong.
+        // 2. Route: pick strong/weak. Fail open — an unparseable or out-of-range
+        //    score routes strong.
         let (tier, model) = match score {
             Some(s) if s >= self.threshold => (ClassifierTier::Strong, self.strong_model.clone()),
             Some(_) => (ClassifierTier::Weak, self.weak_model.clone()),
@@ -215,7 +218,8 @@ impl Algorithm for LlmClassifier {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::{LlmResponse, LlmTarget, Response, RoutedLlmClient};
+    use crate::{LlmResponse, LlmResponseChunk, LlmTarget, Response, RoutedLlmClient};
+    use futures::StreamExt;
     use std::sync::Mutex;
     use switchyard_protocol::text_response;
 
@@ -225,6 +229,9 @@ mod tests {
     struct ScoringClient {
         classifier_model: String,
         score: String,
+        /// When true, the classifier target returns its score as a live stream
+        /// rather than a buffered aggregate, exercising the drain-the-stream path.
+        stream: bool,
         seen: Arc<Mutex<Vec<Request>>>,
     }
 
@@ -237,25 +244,51 @@ mod tests {
             decision: Arc<dyn Decision>,
         ) -> Result<Response, Box<dyn Error + Send + Sync>> {
             let name = decision.selected_model().to_string();
-            let completion = if name == self.classifier_model {
+            let is_classifier = name == self.classifier_model;
+            let completion = if is_classifier {
                 self.score.clone()
             } else {
                 format!("answer from {name}")
             };
             self.seen.lock().map_err(|_| "lock poisoned")?.push(request);
+            // A streaming classifier target emits its score as a live TextDelta
+            // stream; the algorithm must drain it (into_agg) to read the score.
+            let llm_response = if is_classifier && self.stream {
+                let chunks = vec![Ok(LlmResponseChunk::TextDelta {
+                    index: 0,
+                    text: completion,
+                })];
+                LlmResponse::Stream(futures::stream::iter(chunks).boxed())
+            } else {
+                LlmResponse::Agg(text_response(None, completion))
+            };
             Ok(Response {
-                llm_response: LlmResponse::Agg(text_response(None, completion)),
+                llm_response,
                 metadata: None,
             })
         }
     }
 
     /// Build a classifier algo whose three targets share a scoring client.
     fn algo(threshold: f64, score: &str) -> (LlmClassifier, Arc<Mutex<Vec<Request>>>) {
+        build_algo(threshold, score, false)
+    }
+
+    /// Like [`algo`], but the classifier target returns its score as a live stream.
+    fn algo_streaming(threshold: f64, score: &str) -> (LlmClassifier, Arc<Mutex<Vec<Request>>>) {
+        build_algo(threshold, score, true)
+    }
+
+    fn build_algo(
+        threshold: f64,
+        score: &str,
+        stream: bool,
+    ) -> (LlmClassifier, Arc<Mutex<Vec<Request>>>) {
         let seen = Arc::new(Mutex::new(Vec::new()));
         let client = Arc::new(ScoringClient {
             classifier_model: "router/classifier".to_string(),
             score: score.to_string(),
+            stream,
             seen: Arc::clone(&seen),
         }) as Arc<dyn RoutedLlmClient>;
         let target = |name: &str| LlmTarget {
@@ -378,4 +411,49 @@ mod tests {
         assert_eq!(routed.score, None);
         Ok(())
     }
+
+    #[tokio::test]
+    async fn out_of_range_score_defaults_to_strong() -> Result<(), Box<dyn Error + Send + Sync>> {
+        // "NaN" parses as an f64 but is not a usable probability, so it must fail
+        // open to strong rather than be treated as a below-threshold verdict and
+        // silently downgraded to weak (NvBug 6485976).
+        let (algo, _) = algo(0.5, "NaN");
+        let (trace, response) = orch(algo).run(Context::default(), request("hi")).await?;
+        assert_eq!(
+            response
+                .llm_response
+                .as_agg()
+                .map(completion_text)
+                .unwrap_or_default(),
+            "answer from frontier/model"
+        );
+        let routed = as_classifier(&trace[1])?;
+        assert_eq!(routed.tier, Some(ClassifierTier::Strong));
+        assert_eq!(routed.score, None);
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn streamed_score_below_threshold_routes_weak() -> Result<(), Box<dyn Error + Send + Sync>>
+    {
+        // A streaming classifier target must have its score drained and read, not
+        // dropped — otherwise every streamed verdict falls open to strong
+        // regardless of value (NvBug 6485975).
+        let (algo, _) = algo_streaming(0.5, "0.2");
+        let (trace, response) = orch(algo)
+            .run(Context::default(), request("say hello"))
+            .await?;
+        assert_eq!(
+            response
+                .llm_response
+                .as_agg()
+                .map(completion_text)
+                .unwrap_or_default(),
+            "answer from cheap/model"
+        );
+        let routed = as_classifier(&trace[1])?;
+        assert_eq!(routed.tier, Some(ClassifierTier::Weak));
+        assert_eq!(routed.score, Some(0.2));
+        Ok(())
+    }
 }

crates/libsy/src/core/algorithm.rs

@@ -55,7 +55,7 @@ pub struct RoutedRequest {
 
 /// The host-facing half of an offloaded model call, surfaced inside [`Step::CallLlm`].
 ///
-/// Wraps a [`DriverRequest`] whose payload is a [`RoutedRequest`]. The host reads the
+/// Wraps a `DriverRequest` whose payload is a [`RoutedRequest`]. The host reads the
 /// routed request ([`get_routed`](Self::get_routed)) and the decision behind it
 /// ([`get_decision`](Self::get_decision)), performs (or delegates) the model call, and
 /// fulfills it with [`respond`](Self::respond) — unblocking the algorithm's
@@ -196,7 +196,7 @@ impl Default for Driver {
     }
 }
 
-/// One item in the stream returned by [`Driver::stream`] / [`Algorithm::run_stream`].
+/// One item in the stream returned by `Driver::stream` / [`Algorithm::run_stream`].
 pub enum Step {
     /// The algorithm needs this model call performed. The host serves it (optionally
     /// via [`RoutedRequest::default_client`]) and fulfills it with

crates/libsy/src/lib.rs

@@ -56,9 +56,9 @@
 //!
 //! Concrete algorithms live in [`algorithms`]:
 //!
-//! [`algorithms::Random`](crate::algorithms::Random) provides uniform random routing.
+//! [`algorithms::Random`] provides uniform random routing.
 //!
-//! [`algorithms::LlmClassifier`](crate::algorithms::LlmClassifier) classifies
+//! [`algorithms::LlmClassifier`] classifies
 //! with one model, then routes to a strong/weak model depending on the classifier's choice.
 
 mod core;