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
chore(libsy): Give libsy its own error type LibsyError (#129)
Graham King1bafb9b51ece
diff --git a/Cargo.lock b/Cargo.lockindex 5ffeee1e5..225aae1d8 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -1790,6 +1790,7 @@ dependencies = ["serde_json","switchyard-llm-client","switchyard-protocol",+ "thiserror","tokio","tokio-stream","tracing",diff --git a/crates/libsy/Cargo.toml b/crates/libsy/Cargo.tomlindex cc911d405..a1dc2b604 100644--- a/crates/libsy/Cargo.toml+++ b/crates/libsy/Cargo.toml@@ -20,6 +20,7 @@ futures = "0.3"opentelemetry = { version = "0.32", default-features = false, features = ["metrics"] }rand = "0.8"switchyard-protocol = { path = "../protocol" }+thiserror = "2"tokio = { version = "1", features = ["full"] }tokio-stream = "0.1"tracing = { version = "0.1", default-features = false, features = ["std", "attributes"] }diff --git a/crates/libsy/README.md b/crates/libsy/README.mdindex 60013aac6..19ec68e8a 100644--- a/crates/libsy/README.md+++ b/crates/libsy/README.md@@ -204,9 +204,9 @@ pub trait Algorithm: Send + Sync + 'static {// `self: Arc<Self>` (not `&mut`): one algorithm serves requests concurrently — use// interior mutability for state. Offload calls/decisions on `driver`.async fn create_run_task(self: Arc<Self>, ctx: Context, driver: Driver, request: Request)- -> Result<Response, Box<dyn Error + Send + Sync>>;+ -> switchyard_libsy::Result<Response>;async fn process_signals(self: Arc<Self>, signals: Signals)- -> Result<(), Box<dyn Error + Send + Sync>>;+ -> switchyard_libsy::Result<()>;// provided: run(ctx, request) -> (trace, response), run_stream(ctx, request) -> Stream<Step>}@@ -227,7 +227,7 @@ impl Algorithm for LlmClassifier {fn name(&self) -> &str { "llm_classifier" }async fn create_run_task(self: Arc<Self>, ctx: Context, driver: Driver, request: Request)- -> Result<Response, Box<dyn Error + Send + Sync>> {+ -> switchyard_libsy::Result<Response> {// Thread `ctx` into every offloaded call and decision — it carries the request's// cross-cutting state (correlation ids, budgets) for observers downstream.@@ -249,10 +249,24 @@ impl Algorithm for LlmClassifier {driver.call_llm_target(ctx, &routed, routed_req, route_decision).await}- async fn process_signals(self: Arc<Self>, _s: Signals) -> Result<(), Box<dyn Error + Send + Sync>> { Ok(()) }+ async fn process_signals(self: Arc<Self>, _s: Signals) -> switchyard_libsy::Result<()> { Ok(()) }}```+## Errors++All libsy-owned APIs return [`switchyard_libsy::Result<T>`], whose error is+`LibsyError`. Callers can match routing failures (`TargetNotFound`, `NoTargets`,+`MissingClient`), algorithm-specific failures (`AlgorithmError`), driver failures,+algorithm task failures, incomplete runs, and client-call failures without inspecting error+strings.++`RoutedLlmClient` is owned by `switchyard-protocol` and still returns a boxed error.+When [`Algorithm::run`] serves a target, libsy preserves that error as the source of+`LibsyError::ClientCall`. Custom algorithms, classifiers, and processors that need to+surface their own error types can preserve them with+`LibsyError::external("operation", error)`.+## Observabilitylibsy instruments every algorithm at the core — the `Decision` hook plus the offload@@ -309,4 +323,4 @@ agents live in [`examples`](examples/) folder.- **`Signals` events** — `process_signals` / `Signals` exist but carry nothing yet.- **`Context` fields** — carries the algorithm telemetry label today; correlation ids, budgets, and deadlines still to come.-- **Config-driven construction**, **typed errors** (vs `Box<dyn Error>`), **weighted random**.+- **Config-driven construction**, **weighted random**.diff --git a/crates/libsy/examples/ensemble.rs b/crates/libsy/examples/ensemble.rsindex c82f8b8df..6a0a68bf1 100644--- a/crates/libsy/examples/ensemble.rs+++ b/crates/libsy/examples/ensemble.rs@@ -19,14 +19,13 @@//! so this state is per-session.use std::collections::BTreeMap;-use std::error::Error;use std::sync::{Arc, Mutex};use async_trait::async_trait;use switchyard_libsy::{- Algorithm, Context, Decision, Driver, LlmTarget, LlmTargetSet, Request, Response,- RoutedLlmClient,+ Algorithm, Context, Decision, Driver, LibsyError, LlmTarget, LlmTargetSet, Request, Response,+ Result, RoutedLlmClient,};use switchyard_llm_client::{Backend, HttpBackendConfig, ModelConfig, TranslatingLlmClient};use switchyard_protocol::{completion_text, prompt_text, text_request};@@ -38,6 +37,10 @@ const CANDIDATE_MODELS: [&str; 3] = [];const JUDGE_MODEL: &str = "nvidia/deepseek-ai/deepseek-v4-flash";+fn ensemble_error(message: &'static str) -> LibsyError {+ LibsyError::external("ensemble", std::io::Error::other(message))+}+/// Which step of the ensemble flow produced a decision.#[derive(Clone, Copy, Debug, PartialEq, Eq)]pub enum EnsemblePhase {@@ -140,11 +143,11 @@ impl EnsembleOrchAlgo {/// The lock is taken and dropped here, never across an `await`. Under/// concurrency two requests may both commit; they pick the same model from/// the same tally (with a stable tie-break), so the result is identical.- fn resolve_committed(&self) -> Result<Option<String>, Box<dyn Error + Send + Sync>> {+ fn resolve_committed(&self) -> Result<Option<String>> {let mut state = self.state.lock()- .map_err(|_| "ensemble state lock poisoned")?;+ .map_err(|_| ensemble_error("state lock poisoned"))?;if let Some(model) = &state.committed {return Ok(Some(model.clone()));}@@ -160,14 +163,8 @@ impl EnsembleOrchAlgo {/// The candidate with the most judge-wins, breaking ties toward the earlier/// candidate (stable and deterministic). Errors only if there are no/// candidates configured.- fn pick_best(- &self,- wins: &BTreeMap<String, u64>,- ) -> Result<String, Box<dyn Error + Send + Sync>> {- let mut best = self- .candidate_models- .first()- .ok_or("no candidate models configured")?;+ fn pick_best(&self, wins: &BTreeMap<String, u64>) -> Result<String> {+ let mut best = self.candidate_models.first().ok_or(LibsyError::NoTargets)?;let mut best_wins = wins.get(best).copied().unwrap_or(0);for model in &self.candidate_models[1..] {let w = wins.get(model).copied().unwrap_or(0);@@ -186,7 +183,7 @@ impl EnsembleOrchAlgo {ctx: Context,request: Request,model: String,- ) -> Result<(Vec<Arc<dyn Decision>>, Response), Box<dyn Error + Send + Sync>> {+ ) -> Result<(Vec<Arc<dyn Decision>>, Response)> {let target = self.target_set.get_target(&model)?;let decision: Arc<dyn Decision> = Arc::new(EnsembleDecision {reasoning: format!(@@ -219,7 +216,7 @@ impl EnsembleOrchAlgo {driver: &Driver,ctx: Context,request: Request,- ) -> Result<(Vec<Arc<dyn Decision>>, Response), Box<dyn Error + Send + Sync>> {+ ) -> Result<(Vec<Arc<dyn Decision>>, Response)> {let user_prompt = prompt_text(&request.llm_request);// The agent's inbound name rides through every sub-call unchanged; the model// each call hits is carried by its decision, not stamped onto the request.@@ -265,7 +262,7 @@ impl EnsembleOrchAlgo {}}if survivors.is_empty() {- return Err("all ensemble candidates failed".into());+ return Err(ensemble_error("all candidate calls failed"));}// Pick the winner: judge only when there is a real choice to make.@@ -273,7 +270,7 @@ impl EnsembleOrchAlgo {let (model, response) = survivors.into_iter().next()- .ok_or("survivor unexpectedly missing")?;+ .ok_or_else(|| ensemble_error("survivor unexpectedly missing"))?;(model, response, None)} else {let judge_prompt = build_judge_prompt(&user_prompt, &survivors);@@ -303,7 +300,7 @@ impl EnsembleOrchAlgo {let (model, response) = survivors.into_iter().nth(choice)- .ok_or("judge choice out of range")?;+ .ok_or_else(|| ensemble_error("judge choice out of range"))?;(model, response, Some(judge_decision))};@@ -313,7 +310,7 @@ impl EnsembleOrchAlgo {let mut state = self.state.lock()- .map_err(|_| "ensemble state lock poisoned")?;+ .map_err(|_| ensemble_error("state lock poisoned"))?;*state.wins.entry(winner_model.clone()).or_insert(0) += 1;state.turns += 1;}@@ -390,7 +387,7 @@ impl Algorithm for EnsembleOrchAlgo {ctx: Context,driver: Driver,request: Request,- ) -> Result<Response, Box<dyn Error + Send + Sync>> {+ ) -> Result<Response> {// Fast path: exploration is over — route straight to the committed model;// otherwise run a full ensemble turn. Both return a decision trace plus the// final response.@@ -410,11 +407,14 @@ impl Algorithm for EnsembleOrchAlgo {}#[tokio::main(flavor = "current_thread")]-async fn main() -> Result<(), Box<dyn Error + Send + Sync>> {+async fn main() -> Result<()> {let backend = HttpBackendConfig {base_url: std::env::var("NVIDIA_BASE_URL").unwrap_or_else(|_| "https://inference-api.nvidia.com/v1".to_string()),- api_key: Some(std::env::var("NVIDIA_API_KEY")?),+ api_key: Some(+ std::env::var("NVIDIA_API_KEY")+ .map_err(|error| LibsyError::external("reading NVIDIA_API_KEY", error))?,+ ),extra_headers: BTreeMap::new(),};let models: Vec<_> = CANDIDATE_MODELS@@ -423,7 +423,10 @@ async fn main() -> Result<(), Box<dyn Error + Send + Sync>> {.chain(std::iter::once(JUDGE_MODEL)).map(|model| ModelConfig::new(model, Backend::OpenAiChat(backend.clone()), None)).collect();- let client = Arc::new(TranslatingLlmClient::new(&models)?) as Arc<dyn RoutedLlmClient>;+ let client = Arc::new(+ TranslatingLlmClient::new(&models)+ .map_err(|error| LibsyError::external("building LLM client", error))?,+ ) as Arc<dyn RoutedLlmClient>;let targets = LlmTargetSet::new(CANDIDATE_MODELS.iter()@@ -453,7 +456,13 @@ async fn main() -> Result<(), Box<dyn Error + Send + Sync>> {let (_, response) = algorithm.run(Context::default(), request).await?;println!("{}",- completion_text(&response.llm_response.into_agg().await?)+ completion_text(+ &response+ .llm_response+ .into_agg()+ .await+ .map_err(|error| LibsyError::external_boxed("aggregating response", error))?,+ ));Ok(())}@@ -482,7 +491,7 @@ mod tests {_ctx: Context,request: Request,decision: Arc<dyn Decision>,- ) -> Result<Response, Box<dyn Error + Send + Sync>> {+ ) -> std::result::Result<Response, Box<dyn std::error::Error + Send + Sync>> {let name = decision.selected_model().to_string();self.calls.lock()@@ -583,17 +592,19 @@ mod tests {Arc::new(algo)}- fn as_ensemble(- d: &Arc<dyn Decision>,- ) -> Result<&EnsembleDecision, Box<dyn Error + Send + Sync>> {+ fn as_ensemble(d: &Arc<dyn Decision>) -> Result<&EnsembleDecision> {d.as_any().downcast_ref::<EnsembleDecision>()- .ok_or_else(|| "expected an EnsembleDecision".into())+ .ok_or_else(|| {+ switchyard_libsy::DriverError::TypeMismatch {+ expected: "EnsembleDecision",+ }+ .into()+ })}#[tokio::test]- async fn exploration_turn_fans_out_judges_and_returns_the_winner(- ) -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn exploration_turn_fans_out_judges_and_returns_the_winner() -> Result<()> {// Judge prefers b/model; it should win and be returned.let (algo, calls) = algo(&["a/model", "b/model"], "judge/haiku", "b/model", 100);let (trace, response) = orch(algo)@@ -609,7 +620,9 @@ mod tests {);// Both candidates and the judge were called.- let calls = calls.lock().map_err(|_| "lock poisoned")?;+ let calls = calls+ .lock()+ .map_err(|_| ensemble_error("test call-log lock poisoned"))?;assert!(calls.contains(&"a/model".to_string()));assert!(calls.contains(&"b/model".to_string()));assert!(calls.contains(&"judge/haiku".to_string()));@@ -625,8 +638,7 @@ mod tests {}#[tokio::test]- async fn commits_to_the_winningest_model_after_exploration(- ) -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn commits_to_the_winningest_model_after_exploration() -> Result<()> {// Judge always prefers b/model over 2 exploration turns, so the algo// commits to b/model even though a/model is listed first.let (algo, calls) = algo(&["a/model", "b/model"], "judge/haiku", "b/model", 2);@@ -637,7 +649,7 @@ mod tests {orch.clone().run(Context::default(), request("t2")).await?;let judge_calls_after_exploration = calls.lock()- .map_err(|_| "lock poisoned")?+ .map_err(|_| ensemble_error("test call-log lock poisoned"))?.iter().filter(|c| *c == "judge/haiku").count();@@ -659,7 +671,9 @@ mod tests {assert_eq!(decision.phase, EnsemblePhase::Committed);assert_eq!(decision.selected_model, "b/model");- let calls = calls.lock().map_err(|_| "lock poisoned")?;+ let calls = calls+ .lock()+ .map_err(|_| ensemble_error("test call-log lock poisoned"))?;// Judge was not called again on the committed turn.assert_eq!(calls.iter().filter(|c| *c == "judge/haiku").count(), 2);// a/model was called only on the two exploration turns, not the third.@@ -668,7 +682,7 @@ mod tests {}#[tokio::test]- async fn single_candidate_skips_the_judge() -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn single_candidate_skips_the_judge() -> Result<()> {let (algo, calls) = algo(&["only/model"], "judge/haiku", "only/model", 100);let (trace, response) = orch(algo).run(Context::default(), request("hi")).await?;assert_eq!(@@ -682,7 +696,7 @@ mod tests {// No judge call for a lone candidate.assert!(!calls.lock()- .map_err(|_| "lock poisoned")?+ .map_err(|_| ensemble_error("test call-log lock poisoned"))?.contains(&"judge/haiku".to_string()));// Trace: [candidate, winner] — no judge entry.assert_eq!(trace.len(), 2);@@ -691,7 +705,7 @@ mod tests {}#[tokio::test]- async fn zero_exploration_turns_never_commits() -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn zero_exploration_turns_never_commits() -> Result<()> {// exploration_turns == 0 keeps ensembling forever.let (algo, calls) = algo(&["a/model", "b/model"], "judge/haiku", "b/model", 0);let orch = orch(algo);@@ -707,7 +721,7 @@ mod tests {assert_eq!(calls.lock()- .map_err(|_| "lock poisoned")?+ .map_err(|_| ensemble_error("test call-log lock poisoned"))?.iter().filter(|c| *c == "judge/haiku").count(),@@ -717,7 +731,7 @@ mod tests {}#[tokio::test]- async fn all_candidates_failing_errors() -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn all_candidates_failing_errors() -> Result<()> {/// Client whose every call fails.struct FailingClient;#[async_trait]@@ -727,7 +741,8 @@ mod tests {_ctx: Context,_request: Request,_decision: Arc<dyn Decision>,- ) -> Result<Response, Box<dyn Error + Send + Sync>> {+ ) -> std::result::Result<Response, Box<dyn std::error::Error + Send + Sync>>+ {Err("upstream down".into())}}@@ -754,7 +769,7 @@ mod tests {}#[tokio::test]- async fn process_signals_is_a_noop() -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn process_signals_is_a_noop() -> Result<()> {let (algo, _) = algo(&["a/model"], "judge/haiku", "a/model", 1);Arc::new(algo).process_signals(Signals {}).await?;Ok(())@@ -771,7 +786,7 @@ mod tests {}#[tokio::test(flavor = "multi_thread", worker_threads = 4)]- async fn two_sessions_process_in_parallel() -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn two_sessions_process_in_parallel() -> Result<()> {use std::time::Duration;use tokio::sync::Barrier;@@ -794,7 +809,8 @@ mod tests {_ctx: Context,request: Request,decision: Arc<dyn Decision>,- ) -> Result<Response, Box<dyn Error + Send + Sync>> {+ ) -> std::result::Result<Response, Box<dyn std::error::Error + Send + Sync>>+ {let name = decision.selected_model().to_string();let completion = if name == self.judge_model {// Judge runs after the barrier releases; it must not wait.@@ -853,16 +869,19 @@ mod tests {let handle_b = run(session_b, "from B");// The timeout converts a serialization deadlock into a failure, not a hang.- let completion_a = tokio::time::timeout(Duration::from_secs(5), handle_a).await???;- let completion_b = tokio::time::timeout(Duration::from_secs(5), handle_b).await???;+ let completion_a = tokio::time::timeout(Duration::from_secs(5), handle_a)+ .await+ .map_err(|error| LibsyError::external("waiting for session A", error))???;+ let completion_b = tokio::time::timeout(Duration::from_secs(5), handle_b)+ .await+ .map_err(|error| LibsyError::external("waiting for session B", error))???;assert_eq!(completion_a, "answer from a/model");assert_eq!(completion_b, "answer from a/model");Ok(())}#[tokio::test(flavor = "multi_thread", worker_threads = 4)]- async fn two_parallel_sessions_keep_independent_state(- ) -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn two_parallel_sessions_keep_independent_state() -> Result<()> {// Two sessions run concurrently with judges that prefer different models:// session A prefers a/model, session B prefers b/model. Each explores for// two turns then commits; because the win tally is per-session, they must@@ -891,8 +910,8 @@ mod tests {.last().and_then(|d| d.as_any().downcast_ref::<EnsembleDecision>()).map(|d| d.phase)- .ok_or("missing final decision")?;- Ok::<(String, EnsemblePhase), Box<dyn Error + Send + Sync>>((+ .ok_or_else(|| ensemble_error("missing final decision"))?;+ Ok::<(String, EnsemblePhase), LibsyError>((response.llm_response.as_agg()diff --git a/crates/libsy/examples/research_agent.rs b/crates/libsy/examples/research_agent.rsindex f3fd2f873..40a6a87f9 100644--- a/crates/libsy/examples/research_agent.rs+++ b/crates/libsy/examples/research_agent.rs@@ -11,14 +11,13 @@//! `Algorithm::run_stream`. Run with://! cargo run -p libsy --example research_agent-use std::error::Error;use std::sync::Arc;use async_trait::async_trait;use switchyard_libsy::algorithms::LlmClassifier;use switchyard_libsy::{- Algorithm, Context, Decision, LlmResponse, LlmTarget, LlmTargetSet, Request, Response,- RoutedLlmClient,+ Algorithm, Context, Decision, LibsyError, LlmResponse, LlmTarget, LlmTargetSet, Request,+ Response, Result, RoutedLlmClient,};use switchyard_protocol::{completion_text, text_request, text_response};@@ -36,7 +35,7 @@ impl RoutedLlmClient for StubClient {_ctx: Context,_request: Request,decision: Arc<dyn Decision>,- ) -> Result<Response, Box<dyn Error + Send + Sync>> {+ ) -> std::result::Result<Response, Box<dyn std::error::Error + Send + Sync>> {// The model to call is the routed decision's selection, not the inbound name.let model = decision.selected_model().to_string();println!(" -> model call: {model}");@@ -72,7 +71,7 @@ impl ResearchAgent {vec![format!("look up: {question}")]}- async fn run(&self, question: &str) -> Result<String, Box<dyn Error + Send + Sync>> {+ async fn run(&self, question: &str) -> Result<String> {let mut notes = Vec::new();for step in self.plan(question) {let request = Request {@@ -82,14 +81,19 @@ impl ResearchAgent {};let (_trace, response) = self.algo.clone().run(Context::default(), request).await?;- notes.push(completion_text(&response.llm_response.into_agg().await?));+ let aggregate = response+ .llm_response+ .into_agg()+ .await+ .map_err(|error| LibsyError::external_boxed("aggregating response", error))?;+ notes.push(completion_text(&aggregate));}Ok(notes.join("\n"))}}#[tokio::main(flavor = "current_thread")]-async fn main() -> Result<(), Box<dyn Error + Send + Sync>> {+async fn main() -> Result<()> {// Configure routing once: an LLM classifier over three named targets. Swapping// in `Random` needs no change to the agent.let algo: Arc<dyn Algorithm> =diff --git a/crates/libsy/examples/research_agent_core.rs b/crates/libsy/examples/research_agent_core.rsindex 64e2dbac8..ad8833e49 100644--- a/crates/libsy/examples/research_agent_core.rs+++ b/crates/libsy/examples/research_agent_core.rs@@ -9,12 +9,12 @@//! The classifier's two steps show up as two `model call:` lines. Run with://! cargo run -p libsy --example research_agent_core-use std::error::Error;use std::sync::Arc;use switchyard_libsy::algorithms::LlmClassifier;use switchyard_libsy::{- Algorithm, Context, Decision, LlmResponse, LlmTarget, LlmTargetSet, Request, Response, Step,+ Algorithm, Context, Decision, LibsyError, LlmResponse, LlmTarget, LlmTargetSet, Request,+ Response, Result, Step,};use switchyard_protocol::{completion_text, text_request, text_response};use tokio_stream::StreamExt;@@ -58,7 +58,7 @@ impl ResearchAgent {vec![format!("look up: {question}")]}- async fn run(&mut self, question: &str) -> Result<String, Box<dyn Error + Send + Sync>> {+ async fn run(&mut self, question: &str) -> Result<String> {let mut notes = Vec::new();for step in self.plan(question) {let request = Request {@@ -78,7 +78,11 @@ impl ResearchAgent {// Decisions stream in as the algorithm makes them.Step::Decision(decision) => print_decision(decision.as_ref()),Step::ReturnToAgent(response) => {- notes.push(completion_text(&response.llm_response.into_agg().await?));+ let aggregate =+ response.llm_response.into_agg().await.map_err(|error| {+ LibsyError::external_boxed("aggregating response", error)+ })?;+ notes.push(completion_text(&aggregate));}}}@@ -97,7 +101,7 @@ fn print_decision(decision: &dyn Decision) {}#[tokio::main(flavor = "current_thread")]-async fn main() -> Result<(), Box<dyn Error + Send + Sync>> {+async fn main() -> Result<()> {let algo: Arc<dyn Algorithm> =Arc::new(LlmClassifier::new(CLASSIFIER, STRONG, WEAK, 0.5, targets()));diff --git a/crates/libsy/examples/streaming_agent.rs b/crates/libsy/examples/streaming_agent.rsindex 7038a33e2..08884e72a 100644--- a/crates/libsy/examples/streaming_agent.rs+++ b/crates/libsy/examples/streaming_agent.rs@@ -12,15 +12,14 @@//! answer. Run with://! cargo run -p libsy --example streaming_agent-use std::error::Error;use std::io::Write;use std::sync::Arc;use futures::StreamExt;use switchyard_libsy::algorithms::Random;use switchyard_libsy::{- Algorithm, Context, LlmResponse, LlmResponseChunk, LlmResponseStream, LlmTarget, LlmTargetSet,- Request, Response, Step,+ Algorithm, Context, LibsyError, LlmResponse, LlmResponseChunk, LlmResponseStream, LlmTarget,+ LlmTargetSet, Request, Response, Result, Step,};use switchyard_protocol::{completion_text, text_request};@@ -50,7 +49,7 @@ fn streaming_response(model: &str, tokens: &[&str]) -> Response {}#[tokio::main(flavor = "current_thread")]-async fn main() -> Result<(), Box<dyn Error + Send + Sync>> {+async fn main() -> Result<()> {// One client-less target -> its call is offloaded for us to serve.let targets = LlmTargetSet::new(vec![LlmTarget {semantic_name: "stream/model".to_string(),@@ -86,7 +85,10 @@ async fn main() -> Result<(), Box<dyn Error + Send + Sync>> {LlmResponse::Stream(mut chunks) => {print!("agent sees: ");while let Some(chunk) = chunks.next().await {- if let LlmResponseChunk::TextDelta { text, .. } = chunk? {+ let chunk = chunk.map_err(|error| {+ LibsyError::external_boxed("reading response stream", error)+ })?;+ if let LlmResponseChunk::TextDelta { text, .. } = chunk {print!("{text}");std::io::stdout().flush().ok();}diff --git a/crates/libsy/src/algorithms/fall_through.rs b/crates/libsy/src/algorithms/fall_through.rsindex 49ae385a6..b163e2141 100644--- a/crates/libsy/src/algorithms/fall_through.rs+++ b/crates/libsy/src/algorithms/fall_through.rs@@ -20,10 +20,9 @@ use std::sync::Arc;use async_trait::async_trait;use crate::core::{Classifier, Event, Processor, Score, SharedState};-use crate::{Algorithm, Context, Decision, Driver, LlmTargetSet, Request, Response};--/// Boxed, thread-safe error type used across the SDK.-type BoxErr = Box<dyn std::error::Error + Send + Sync>;+use crate::{+ Algorithm, Context, Decision, Driver, LibsyError, LlmTargetSet, Request, Response, Result,+};/// The decision a fall-through run produces: the selected model plus a human-readable reason.pub struct FallThroughDecision {@@ -88,7 +87,7 @@ impl Algorithm<SharedState> for FallThrough {ctx: Context<SharedState>,driver: Driver,request: Request,- ) -> Result<Response, BoxErr> {+ ) -> Result<Response> {// Hold the session state (carried in the threaded context) for the whole// request→decision fold, so a turn's fact accumulation is atomic and concurrent// turns of the same session serialize on it.@@ -114,7 +113,9 @@ impl Algorithm<SharedState> for FallThrough {}}let Some(winner) = winner else {- return Err("fall-through: every classifier abstained".into());+ return Err(LibsyError::AlgorithmError {+ message: "every classifier abstained".to_string(),+ });};// 3. Resolve the target and publish the decision.@@ -153,6 +154,14 @@ mod tests {use crate::{LlmResponse, LlmTarget, RoutedLlmClient};+ #[derive(Debug, thiserror::Error)]+ #[error("{0}")]+ struct TestError(&'static str);++ fn test_error(message: &'static str) -> LibsyError {+ LibsyError::external("test", TestError(message))+ }+// --- fixtures ----------------------------------------------------------------------/// A client that echoes the routed model name back as the completion.@@ -165,7 +174,7 @@ mod tests {_ctx: Context,_request: Request,decision: Arc<dyn Decision>,- ) -> Result<Response, BoxErr> {+ ) -> std::result::Result<Response, Box<dyn std::error::Error + Send + Sync>> {Ok(Response {llm_response: LlmResponse::Agg(text_response(None,@@ -199,7 +208,7 @@ mod tests {_state: &mut State,_request: &Request,_driver: Option<&Driver>,- ) -> Result<Classification, BoxErr> {+ ) -> Result<Classification> {Ok(Classification::Scores(self.0.iter()@@ -243,25 +252,28 @@ mod tests {async fn run_turn(router: &Arc<FallThrough>,ctx: Context<SharedState>,- ) -> Result<(String, Vec<Arc<dyn Decision>>), BoxErr> {+ ) -> Result<(String, Vec<Arc<dyn Decision>>)> {let (trace, response) = router.clone().run(ctx, request()).await?;let text = response.llm_response.into_agg().await- .map(|agg| completion_text(&agg))?;+ .map(|agg| completion_text(&agg))+ .map_err(|error| {+ LibsyError::external_boxed("aggregating fall-through response", error)+ })?;Ok((text, trace))}/// Drives a fresh router through one turn on a fresh session.- async fn run(router: FallThrough) -> Result<(String, Vec<Arc<dyn Decision>>), BoxErr> {+ async fn run(router: FallThrough) -> Result<(String, Vec<Arc<dyn Decision>>)> {run_turn(&Arc::new(router), Context::default()).await}// --- tests -------------------------------------------------------------------------#[tokio::test]- async fn argmax_picks_the_highest_confidence_target() -> Result<(), BoxErr> {+ async fn argmax_picks_the_highest_confidence_target() -> Result<()> {let router = FallThrough::new(target_set(&["strong", "weak"])).with_classifier(fixed(vec![score("weak", 0.2), score("strong", 0.9)]));let (model, trace) = run(router).await?;@@ -272,7 +284,7 @@ mod tests {}#[tokio::test]- async fn falls_through_the_first_abstaining_classifier() -> Result<(), BoxErr> {+ async fn falls_through_the_first_abstaining_classifier() -> Result<()> {// First classifier abstains (empty); the second decides.let router = FallThrough::new(target_set(&["strong", "weak"])).with_classifier(fixed(vec![]))@@ -283,7 +295,7 @@ mod tests {}#[tokio::test]- async fn first_deciding_classifier_wins_the_cascade() -> Result<(), BoxErr> {+ async fn first_deciding_classifier_wins_the_cascade() -> Result<()> {// The first classifier decides; the second is never consulted.let router = FallThrough::new(target_set(&["strong", "weak"])).with_classifier(fixed(vec![score("strong", 0.6)]))@@ -294,15 +306,22 @@ mod tests {}#[tokio::test]- async fn all_abstaining_is_an_error() -> Result<(), BoxErr> {+ async fn all_abstaining_is_an_error() -> Result<()> {let router =FallThrough::new(target_set(&["strong", "weak"])).with_classifier(fixed(vec![]));- assert!(run(router).await.is_err());+ let error = run(router)+ .await+ .err()+ .ok_or_else(|| test_error("expected classifiers to abstain"))?;+ assert!(matches!(+ error,+ LibsyError::AlgorithmError { message } if message == "every classifier abstained"+ ));Ok(())}#[tokio::test]- async fn classifiers_receive_the_per_request_driver() -> Result<(), BoxErr> {+ async fn classifiers_receive_the_per_request_driver() -> Result<()> {// A classifier that only decides when handed a driver — proving the cascade offers// the per-request driver to every classifier (driver-backed ones need it).struct NeedsDriver;@@ -314,10 +333,10 @@ mod tests {_state: &mut State,_request: &Request,driver: Option<&Driver>,- ) -> Result<Classification, BoxErr> {+ ) -> Result<Classification> {match driver {Some(_) => Ok(Classification::Scores(vec![score("strong", 1.0)])),- None => Err("expected a driver".into()),+ None => Err(test_error("expected a driver")),}}}@@ -330,7 +349,7 @@ mod tests {}#[tokio::test]- async fn processor_observes_request_and_decision() -> Result<(), BoxErr> {+ async fn processor_observes_request_and_decision() -> Result<()> {use std::sync::Mutex;// Records which event kinds it saw, proving the request-then-decision replay.@@ -338,13 +357,16 @@ mod tests {#[async_trait]impl Processor for RecordingProcessor {- async fn process(&self, _state: &mut State, event: Event<'_>) -> Result<(), BoxErr> {+ async fn process(&self, _state: &mut State, event: Event<'_>) -> Result<()> {let kind = match event {Event::Request(_) => "request",Event::Decision(_) => "decision",_ => "other",};- self.0.lock().map_err(|_| "lock poisoned")?.push(kind);+ self.0+ .lock()+ .map_err(|_| test_error("lock poisoned"))?+ .push(kind);Ok(())}}@@ -356,20 +378,20 @@ mod tests {run(router).await?;assert_eq!(- *seen.lock().map_err(|_| "lock poisoned")?,+ *seen.lock().map_err(|_| test_error("lock poisoned"))?,vec!["request", "decision"]);Ok(())}#[tokio::test]- async fn state_persists_across_turns() -> Result<(), BoxErr> {+ async fn state_persists_across_turns() -> Result<()> {// Increments the session turn count on every request.struct CountingProcessor;#[async_trait]impl Processor for CountingProcessor {- async fn process(&self, state: &mut State, event: Event<'_>) -> Result<(), BoxErr> {+ async fn process(&self, state: &mut State, event: Event<'_>) -> Result<()> {if let Event::Request(_) = event {state.turn_count += 1;}@@ -388,7 +410,7 @@ mod tests {state: &mut State,_request: &Request,_driver: Option<&Driver>,- ) -> Result<Classification, BoxErr> {+ ) -> Result<Classification> {let target = if state.turn_count >= 2 {"strong"} else {diff --git a/crates/libsy/src/algorithms/llm_class.rs b/crates/libsy/src/algorithms/llm_class.rsindex 14bf43db6..fccb9d601 100644--- a/crates/libsy/src/algorithms/llm_class.rs+++ b/crates/libsy/src/algorithms/llm_class.rs@@ -10,12 +10,11 @@//! routed strong/weak target. The multi-step nature is invisible to the caller —//! it is the algorithm's own control flow.-use std::error::Error;use std::sync::Arc;use async_trait::async_trait;-use crate::{Algorithm, Context, Decision, Driver, LlmTargetSet, Request, Response};+use crate::{Algorithm, Context, Decision, Driver, LlmTargetSet, Request, Response, Result};use switchyard_protocol::{completion_text, LlmRequest, Message, Role};/// The system prompt tells the classifier what to do@@ -148,7 +147,7 @@ impl Algorithm for LlmClassifier {ctx: Context,driver: Driver,request: Request,- ) -> Result<Response, Box<dyn Error + Send + Sync>> {+ ) -> Result<Response> {// The agent's inbound name rides through unchanged on every sub-call; the// model each sub-call actually hits is carried by its decision instead.let inbound = request.llm_request.model.clone();@@ -239,7 +238,7 @@ mod tests {_ctx: Context,request: Request,decision: Arc<dyn Decision>,- ) -> Result<Response, Box<dyn Error + Send + Sync>> {+ ) -> std::result::Result<Response, Box<dyn std::error::Error + Send + Sync>> {let name = decision.selected_model().to_string();let completion = if name == self.classifier_model {self.score.clone()@@ -295,17 +294,19 @@ mod tests {}/// Downcast a trace entry to the concrete classifier decision.- fn as_classifier(- d: &Arc<dyn Decision>,- ) -> Result<&ClassifierDecision, Box<dyn Error + Send + Sync>> {+ fn as_classifier(d: &Arc<dyn Decision>) -> Result<&ClassifierDecision> {d.as_any().downcast_ref::<ClassifierDecision>()- .ok_or_else(|| "expected a ClassifierDecision".into())+ .ok_or_else(|| {+ crate::DriverError::TypeMismatch {+ expected: "ClassifierDecision",+ }+ .into()+ })}#[tokio::test]- async fn score_at_or_above_threshold_routes_strong() -> Result<(), Box<dyn Error + Send + Sync>>- {+ async fn score_at_or_above_threshold_routes_strong() -> Result<()> {let (algo, _) = algo(0.5, "0.9");let (trace, response) = orch(algo).run(Context::default(), request("solve this proof"))@@ -328,7 +329,7 @@ mod tests {}#[tokio::test]- async fn score_below_threshold_routes_weak() -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn score_below_threshold_routes_weak() -> Result<()> {let (algo, _) = algo(0.5, "0.2");let (trace, response) = orch(algo).run(Context::default(), request("say hello"))@@ -348,8 +349,7 @@ mod tests {}#[tokio::test]- async fn score_exactly_at_threshold_routes_strong() -> Result<(), Box<dyn Error + Send + Sync>>- {+ async fn score_exactly_at_threshold_routes_strong() -> Result<()> {let (algo, _) = algo(0.5, "0.5");let (_, response) = orch(algo).run(Context::default(), request("borderline"))@@ -366,7 +366,7 @@ mod tests {}#[tokio::test]- async fn unparseable_score_defaults_to_strong() -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn unparseable_score_defaults_to_strong() -> Result<()> {let (algo, _) = algo(0.5, "not-a-number");let (trace, response) = orch(algo).run(Context::default(), request("hi")).await?;assert_eq!(diff --git a/crates/libsy/src/algorithms/noop.rs b/crates/libsy/src/algorithms/noop.rsindex aeddb1e3c..389a1e72a 100644--- a/crates/libsy/src/algorithms/noop.rs+++ b/crates/libsy/src/algorithms/noop.rs@@ -4,13 +4,13 @@//! No-op router. Always returns a hard coded response. Does not route to a backend.//! For testing.-use std::{error::Error, sync::Arc};+use std::sync::Arc;use switchyard_protocol::{AggLlmResponse, ContentBlock, LlmResponse, Request, Response, ResponseOutput, Role, StopReason,};-use crate::{Algorithm, Context, Decision, Driver};+use crate::{Algorithm, Context, Decision, Driver, Result};/// A routing algorithm that does not route. It returns a hard-coded response.pub struct Noop {}@@ -44,7 +44,7 @@ impl Algorithm for Noop {ctx: Context,driver: Driver,request: Request,- ) -> Result<Response, Box<dyn Error + Send + Sync>> {+ ) -> Result<Response> {let model = request.requested_model().unwrap_or("switchyard/noop")@@ -81,7 +81,7 @@ mod tests {use super::*;#[tokio::test]- async fn test_noop_algo() -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn test_noop_algo() -> Result<()> {const TEST_MODEL: &str = "test_noop_algo";let request = Request {llm_request: LlmRequest {diff --git a/crates/libsy/src/algorithms/rand.rs b/crates/libsy/src/algorithms/rand.rsindex a23690b8b..2b2566578 100644--- a/crates/libsy/src/algorithms/rand.rs+++ b/crates/libsy/src/algorithms/rand.rs@@ -8,13 +8,14 @@//! shape: one `driver.call_llm_target` inside `create_run_task`. Weighted selection//! can be layered on later; the set defines the candidates.-use std::error::Error;use std::sync::Arc;use async_trait::async_trait;use rand::seq::SliceRandom;-use crate::{Algorithm, Context, Decision, Driver, LlmTargetSet, Request, Response};+use crate::{+ Algorithm, Context, Decision, Driver, LibsyError, LlmTargetSet, Request, Response, Result,+};/// Decision produced by [`Random`]: which target was chosen and why.pub struct RandomDecision {@@ -64,14 +65,14 @@ impl Algorithm for Random {ctx: Context,driver: Driver,request: Request,- ) -> Result<Response, Box<dyn Error + Send + Sync>> {+ ) -> Result<Response> {// Scope the non-Send ThreadRng before the await so the future remains Send.let target = {let mut rng = rand::thread_rng();self.target_set.targets().choose(&mut rng)- .ok_or("no targets available")?+ .ok_or(LibsyError::NoTargets)?.clone()};@@ -107,7 +108,7 @@ mod tests {_ctx: Context,_request: Request,decision: Arc<dyn Decision>,- ) -> Result<Response, Box<dyn Error + Send + Sync>> {+ ) -> std::result::Result<Response, Box<dyn std::error::Error + Send + Sync>> {Ok(Response {llm_response: LlmResponse::Agg(text_response(None, decision.selected_model())),metadata: None,@@ -140,8 +141,7 @@ mod tests {}#[tokio::test]- async fn single_target_is_always_selected_and_called(- ) -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn single_target_is_always_selected_and_called() -> Result<()> {let algorithm = shared_algorithm(&["only/model"]);let (trace, response) = algorithm.run(Context::default(), request()).await?;@@ -159,8 +159,7 @@ mod tests {}#[tokio::test]- async fn selected_target_is_in_the_set_and_matches_the_trace(- ) -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn selected_target_is_in_the_set_and_matches_the_trace() -> Result<()> {let names = ["a/model", "b/model", "c/model"];let algorithm = shared_algorithm(&names);@@ -181,8 +180,7 @@ mod tests {}#[tokio::test]- async fn selection_covers_all_targets_over_many_runs(- ) -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn selection_covers_all_targets_over_many_runs() -> Result<()> {let algorithm = shared_algorithm(&["a/model", "b/model"]);let mut seen = HashSet::new();@@ -209,11 +207,12 @@ mod tests {#[tokio::test]async fn empty_target_set_errors() {let algorithm = shared_algorithm(&[]);- assert!(algorithm.run(Context::default(), request()).await.is_err());+ let error = algorithm.run(Context::default(), request()).await.err();+ assert!(matches!(error, Some(LibsyError::NoTargets)));}#[tokio::test]- async fn process_signals_is_a_noop() -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn process_signals_is_a_noop() -> Result<()> {Arc::new(algorithm(&["only/model"])).process_signals(Signals {}).await?;@@ -221,7 +220,7 @@ mod tests {}#[tokio::test]- async fn decision_is_inspectable_and_downcasts() -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn decision_is_inspectable_and_downcasts() -> Result<()> {let algorithm = shared_algorithm(&["only/model"]);let (trace, _) = algorithm.run(Context::default(), request()).await?;let decision = &trace[0];@@ -234,7 +233,11 @@ mod tests {let concrete = decision.as_any().downcast_ref::<RandomDecision>()- .ok_or("expected a RandomDecision")?;+ .ok_or_else(|| {+ LibsyError::from(crate::DriverError::TypeMismatch {+ expected: "RandomDecision",+ })+ })?;assert_eq!(concrete.selected_model, "only/model");Ok(())}diff --git a/crates/libsy/src/algorithms/subagent_override.rs b/crates/libsy/src/algorithms/subagent_override.rsindex feca43fb6..96336baf0 100644--- a/crates/libsy/src/algorithms/subagent_override.rs+++ b/crates/libsy/src/algorithms/subagent_override.rs@@ -12,12 +12,11 @@//! failure surfaces as a normal target error rather than re-entering the//! wrapped algorithm.-use std::error::Error;use std::sync::Arc;use async_trait::async_trait;-use crate::{Algorithm, Context, Decision, Driver, LlmTarget, Metadata, Request, Response};+use crate::{Algorithm, Context, Decision, Driver, LlmTarget, Metadata, Request, Response, Result};/// Decision produced by [`SubagentOverride`] when it routes to the worker target.pub struct SubagentDecision {@@ -68,7 +67,7 @@ impl Algorithm for SubagentOverride {ctx: Context,driver: Driver,request: Request,- ) -> Result<Response, Box<dyn Error + Send + Sync>> {+ ) -> Result<Response> {let is_subagent_work = request.metadata.as_ref()@@ -111,7 +110,7 @@ mod tests {_ctx: Context,_request: Request,decision: Arc<dyn Decision>,- ) -> Result<Response, Box<dyn Error + Send + Sync>> {+ ) -> std::result::Result<Response, Box<dyn std::error::Error + Send + Sync>> {Ok(Response {llm_response: LlmResponse::Agg(text_response(None, decision.selected_model())),metadata: None,@@ -149,9 +148,7 @@ mod tests {Arc::new(SubagentOverride::new(inner, target("worker")))}- async fn selected_model(- headers: &[(&str, &str)],- ) -> Result<String, Box<dyn Error + Send + Sync>> {+ async fn selected_model(headers: &[(&str, &str)]) -> Result<String> {let (trace, response) = algorithm().run(Context::default(), request(headers)).await?;@@ -168,15 +165,13 @@ mod tests {}#[tokio::test]- async fn requests_without_metadata_delegate_to_the_wrapped_algorithm(- ) -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn requests_without_metadata_delegate_to_the_wrapped_algorithm() -> Result<()> {assert_eq!(selected_model(&[]).await?, "orchestrator");Ok(())}#[tokio::test]- async fn subagent_work_is_routed_to_the_worker_target(- ) -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn subagent_work_is_routed_to_the_worker_target() -> Result<()> {// Claude Code child-agent lineage.let claude = &[("x-claude-code-session-id", "root"),@@ -197,8 +192,7 @@ mod tests {}#[tokio::test]- async fn harness_maintenance_turns_stay_on_the_wrapped_algorithm(- ) -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn harness_maintenance_turns_stay_on_the_wrapped_algorithm() -> Result<()> {assert_eq!(selected_model(&[("x-openai-subagent", "compact")]).await?,"orchestrator"diff --git a/crates/libsy/src/core/algorithm.rs b/crates/libsy/src/core/algorithm.rsindex b54623d44..11af2748c 100644--- a/crates/libsy/src/core/algorithm.rs+++ b/crates/libsy/src/core/algorithm.rs@@ -5,7 +5,7 @@//! routing/optimization algorithm implements, and the offload channel it makes model//! calls and publishes [`Decision`]s over. See the crate root for the narrative model.-use std::{error::Error, pin::Pin, sync::Arc, time::Instant};+use std::{pin::Pin, sync::Arc, time::Instant};use async_trait::async_trait;use futures::{Stream, StreamExt};@@ -21,15 +21,12 @@ pub use switchyard_protocol::{};use super::driver::{DriverRequest, DriverStep, TypeErasedDriver};-use crate::observability;--/// Shorthand for the crate's boxed, thread-safe error type.-type BoxErr = Box<dyn Error + Send + Sync>;+use crate::{observability, DriverError, LibsyError, Result};/// A boxed, `Send` stream of [`Step`]s — the output of/// [`Algorithm::run_stream`]. Boxed so the trait method that produces it keeps/// `Arc<dyn Algorithm>` object-safe.-pub type StepStream = Pin<Box<dyn Stream<Item = Result<Step, BoxErr>> + Send>>;+pub type StepStream = Pin<Box<dyn Stream<Item = Result<Step>> + Send>>;/// A request paired with the routing [`Decision`] that produced it — the offload/// payload a host reads (via [`CallLlmRequest::get_routed`]) to serve the call.@@ -100,7 +97,7 @@ impl CallLlmRequest {/// Fulfill the promise with the caller's model-call result. Pass `Err(..)` to/// propagate a failed model call back to the algorithm. Consumes the promise: it/// can only be fulfilled once.- pub fn respond(self, result: Result<Response, BoxErr>) -> Result<(), BoxErr> {+ pub fn respond(self, result: Result<Response>) -> Result<()> {self.inner.respond::<Response>(result)}}@@ -148,7 +145,7 @@ impl Driver {reasoning_tokens = tracing::field::Empty,))]- pub async fn call_llm(&self, routed: RoutedRequest) -> Result<Response, BoxErr> {+ pub async fn call_llm(&self, routed: RoutedRequest) -> Result<Response> {let algorithm = observability::algorithm_label(&routed.ctx).to_string();let selected_model = routed.decision.selected_model().to_string();let started = Instant::now();@@ -177,7 +174,7 @@ impl Driver {target: &LlmTarget,request: Request,decision: Arc<dyn Decision>,- ) -> Result<Response, BoxErr> {+ ) -> Result<Response> {self.call_llm(RoutedRequest {request,decision,@@ -190,7 +187,7 @@ impl Driver {/// Publish a routing [`Decision`] as a [`Step::Decision`] on the stream./// Each successfully published decision is counted and logged with its/// reasoning; a decision the stream never accepted is not recorded.- pub async fn info(&self, ctx: Context, decision: Arc<dyn Decision>) -> Result<(), BoxErr> {+ pub async fn info(&self, ctx: Context, decision: Arc<dyn Decision>) -> Result<()> {self.driver.info(ctx.clone(), decision.clone()).await?;observability::record_decision(&ctx, decision.as_ref());Ok(())@@ -199,11 +196,7 @@ impl Driver {/// Emit the terminal step: [`Step::ReturnToAgent`] on `Ok`, or an `Err` stream/// item on failure. Internal: called once by [`run_stream`](Algorithm::run_stream)/// when the algorithm finishes.- pub(crate) async fn finish(- &self,- ctx: Context,- result: Result<Response, BoxErr>,- ) -> Result<(), BoxErr> {+ pub(crate) async fn finish(&self, ctx: Context, result: Result<Response>) -> Result<()> {match result {Ok(response) => self.driver.done(ctx, response).await,Err(err) => self.driver.fail(ctx, err).await,@@ -213,17 +206,27 @@ impl Driver {/// Transform the raw driver stream into a stream of [`Step`]s. Internal: the/// consumer stream is taken (once) by [`run_stream`](Algorithm::run_stream). A/// payload that does not match the expected type for its step becomes an `Err` item.- pub(crate) fn stream(&self) -> impl Stream<Item = Result<Step, BoxErr>> {+ pub(crate) fn stream(&self) -> impl Stream<Item = Result<Step>> {self.driver.stream().map(|item| match item? {DriverStep::Request(req) => Ok(Step::CallLlm(Box::new(CallLlmRequest::new(req)))),DriverStep::Info(payload) => payload.downcast::<Arc<dyn Decision>>().map(|decision| Step::Decision(*decision))- .map_err(|_| "driver: info payload was not a Decision".into()),+ .map_err(|_| {+ DriverError::TypeMismatch {+ expected: "Arc<dyn Decision>",+ }+ .into()+ }),DriverStep::Done(payload) => payload.downcast::<Response>().map(Step::ReturnToAgent)- .map_err(|_| "driver: done payload was not a Response".into()),+ .map_err(|_| {+ DriverError::TypeMismatch {+ expected: "Response",+ }+ .into()+ }),})}}@@ -291,12 +294,14 @@ impl LlmTargetSet {}/// Look up a target by name; errors if no target has that name.- pub fn get_target(&self, name: &str) -> Result<LlmTarget, Box<dyn Error + Send + Sync>> {+ pub fn get_target(&self, name: &str) -> Result<LlmTarget> {self.targets.iter().find(|t| t.semantic_name == name).cloned()- .ok_or(format!("Target {} not found", name).into())+ .ok_or_else(|| LibsyError::TargetNotFound {+ target: name.to_string(),+ })}}@@ -333,16 +338,13 @@ wherectx: Context<S>,driver: Driver,request: Request,- ) -> Result<Response, Box<dyn Error + Send + Sync>>;+ ) -> Result<Response>;/// Feed the algorithm agentic-stack events (tool results, budgets, etc.). The/// reference algorithms ignore signals; a stateful algorithm updates its own/// (interior-mutable) state. Takes `self: Arc<Self>` like the other run methods.#[allow(unused_variables)]- async fn process_signals(- self: Arc<Self>,- signals: Signals,- ) -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn process_signals(self: Arc<Self>, signals: Signals) -> Result<()> {Ok(())}@@ -385,7 +387,7 @@ wherefutures::stream::once(async move {let result = match handle.await {Ok(response) => response,- Err(e) => Err(format!("Algorithm task panicked: {e}").into()),+ Err(source) => Err(LibsyError::AlgorithmTask { source }),};finish_driver.finish(finish_ctx, result).await})@@ -406,7 +408,7 @@ whereself: Arc<Self>,ctx: Context<S>,request: Request,- ) -> Result<(Vec<Arc<dyn Decision>>, Response), Box<dyn Error + Send + Sync>> {+ ) -> Result<(Vec<Arc<dyn Decision>>, Response)> {// Serve one offloaded call with its target's default client. A failed *model*// call is forwarded to the algorithm via `respond`; this errors only on an// infrastructure failure (no default client, or the promise was dropped).@@ -423,17 +425,20 @@ whereerror = tracing::field::Empty,))]- async fn serve(call: CallLlmRequest) -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn serve(call: CallLlmRequest) -> Result<()> {let routed = call.get_routed().clone();- let client = routed.default_client.clone().ok_or_else(|| {- format!(- "run: target '{}' has no client to serve the call",- routed.decision.selected_model()- )- })?;+ let target = routed.decision.selected_model().to_string();+ let client =+ routed+ .default_client+ .clone()+ .ok_or_else(|| LibsyError::MissingClient {+ target: target.clone(),+ })?;let result = client.call(routed.ctx, routed.request, routed.decision)- .await;+ .await+ .map_err(|source| LibsyError::client_call(target, source));observability::record_client_call(&result);call.respond(result)}@@ -468,7 +473,7 @@ where}final_response.map(|response| (trace, response))- .ok_or_else(|| "run: stream ended without a final response".into())+ .ok_or(LibsyError::MissingFinalResponse)}}@@ -478,6 +483,14 @@ mod tests {use futures::StreamExt;use switchyard_protocol::{completion_text, text_request, text_response};+ #[derive(Debug, thiserror::Error)]+ #[error("{0}")]+ struct TestError(&'static str);++ fn test_error(message: &'static str) -> LibsyError {+ LibsyError::external("test", TestError(message))+ }+/// Mock client that echoes back the target name it was called with.struct EchoClient;@@ -488,7 +501,7 @@ mod tests {_ctx: Context,_request: Request,decision: Arc<dyn Decision>,- ) -> Result<Response, Box<dyn Error + Send + Sync>> {+ ) -> std::result::Result<Response, Box<dyn std::error::Error + Send + Sync>> {// Echo back the model the algorithm routed to (the decision's selection).Ok(Response {llm_response: LlmResponse::Agg(text_response(@@ -533,12 +546,12 @@ mod tests {ctx: Context,driver: Driver,request: Request,- ) -> Result<Response, Box<dyn Error + Send + Sync>> {+ ) -> Result<Response> {let target = self.target_set.targets().first()- .ok_or("no targets")?+ .ok_or(LibsyError::NoTargets)?.clone();let decision: Arc<dyn Decision> = Arc::new(TestDecision {model: target.semantic_name.clone(),@@ -575,6 +588,15 @@ mod tests {LlmTargetSet::new(targets)}+ #[test]+ fn target_lookup_returns_the_missing_target() {+ let error = target_set(&[]).get_target("missing").err();+ assert!(matches!(+ error,+ Some(LibsyError::TargetNotFound { target }) if target == "missing"+ ));+ }+/// Client that serves a call as a token stream — its `call` returns/// [`LlmResponse::Stream`] replaying `chunks` in order (as `Ok` items).struct StreamingClient {@@ -588,7 +610,7 @@ mod tests {_ctx: Context,_request: Request,_decision: Arc<dyn Decision>,- ) -> Result<Response, Box<dyn Error + Send + Sync>> {+ ) -> std::result::Result<Response, Box<dyn std::error::Error + Send + Sync>> {let stream = futures::stream::iter(self.chunks.clone().into_iter().map(Ok)).boxed();Ok(Response {llm_response: LlmResponse::Stream(stream),@@ -607,8 +629,7 @@ mod tests {}#[tokio::test]- async fn run_returns_a_streamed_response_the_caller_aggregates(- ) -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn run_returns_a_streamed_response_the_caller_aggregates() -> Result<()> {// A streaming client -> its chunks flow through the promise and `ReturnToAgent`,// and `run` returns the live stream untouched for the caller to fold.let orch = streaming_orch(vec![@@ -630,7 +651,10 @@ mod tests {]);let (trace, response) = orch.run(Context::default(), request()).await?;// `run` handed back the live stream; the caller folds it to a buffered aggregate.- let agg = response.llm_response.into_agg().await?;+ let agg =+ response.llm_response.into_agg().await.map_err(|error| {+ LibsyError::external_boxed("aggregating response stream", error)+ })?;assert_eq!(completion_text(&agg), "hello");assert_eq!(agg.model.as_deref(), Some("stream/model"));assert_eq!(trace.len(), 1);@@ -638,8 +662,7 @@ mod tests {}#[tokio::test]- async fn aggregating_a_streamed_response_propagates_a_mid_stream_error(- ) -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn aggregating_a_streamed_response_propagates_a_mid_stream_error() -> Result<()> {// `run` succeeds and returns the stream; the in-band `Error` chunk surfaces only// when the caller aggregates it.let orch = streaming_orch(vec![@@ -653,7 +676,7 @@ mod tests {]);let (_, response) = orch.run(Context::default(), request()).await?;match response.llm_response.into_agg().await {- Ok(_) => Err("expected a mid-stream error, got an aggregate".into()),+ Ok(_) => Err(test_error("expected a mid-stream error, got an aggregate")),Err(err) => {assert!(err.to_string().contains("upstream exploded"));Ok(())@@ -662,8 +685,7 @@ mod tests {}#[tokio::test]- async fn run_offloads_via_promise_then_returns_to_agent(- ) -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn run_offloads_via_promise_then_returns_to_agent() -> Result<()> {// A client-less target -> its call is offloaded via a promise the// orchestrator surfaces as a `CallLlm` step for us to fulfill.let stream =@@ -704,15 +726,14 @@ mod tests {assert!(saw_call, "expected a CallLlm step before ReturnToAgent");assert_eq!(- final_completion.ok_or("no ReturnToAgent step")?,+ final_completion.ok_or_else(|| test_error("no ReturnToAgent step"))?,"fulfilled");Ok(())}#[tokio::test]- async fn client_backed_target_offloads_with_a_default_client(- ) -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn client_backed_target_offloads_with_a_default_client() -> Result<()> {// Every call now offloads to the stream; a client-backed target rides its// client along as `default_client` so the consumer can serve it by default.let stream =@@ -727,10 +748,12 @@ mod tests {let client = routed.default_client.clone()- .ok_or("expected a default client")?;+ .ok_or_else(|| test_error("expected a default client"))?;+ let target = routed.decision.selected_model().to_string();let result = client.call(routed.ctx, routed.request, routed.decision)- .await;+ .await+ .map_err(|error| LibsyError::client_call(target, error));call.respond(result)?;}Step::Decision(_) => {}@@ -747,13 +770,15 @@ mod tests {}// EchoClient echoes the model name back as the completion.- assert_eq!(final_completion.ok_or("no ReturnToAgent")?, "direct/model");+ assert_eq!(+ final_completion.ok_or_else(|| test_error("no ReturnToAgent"))?,+ "direct/model"+ );Ok(())}#[tokio::test]- async fn run_returns_the_response_when_all_targets_have_clients(- ) -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn run_returns_the_response_when_all_targets_have_clients() -> Result<()> {// Every target has a client, so run serves every call via the// default client and returns the trace + final response.let (trace, response) = orch(target_set(&[("direct/model", true)]))@@ -773,18 +798,23 @@ mod tests {}#[tokio::test]- async fn run_errors_when_a_target_lacks_a_client() -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn run_errors_when_a_target_lacks_a_client() -> Result<()> {// A client-less target has no default client to serve its offloaded call, so// driving it to completion errors.- assert!(orch(target_set(&[("offload/model", false)]))+ let error = orch(target_set(&[("offload/model", false)])).run(Context::default(), request()).await- .is_err());+ .err()+ .ok_or_else(|| test_error("expected a missing-client error"))?;+ assert!(matches!(+ error,+ LibsyError::MissingClient { target } if target == "offload/model"+ ));Ok(())}#[tokio::test(flavor = "multi_thread", worker_threads = 12)]- async fn requests_are_processed_in_parallel() -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn requests_are_processed_in_parallel() -> Result<()> {use std::time::Duration;use tokio::sync::Barrier;@@ -806,7 +836,8 @@ mod tests {_ctx: Context,_request: Request,decision: Arc<dyn Decision>,- ) -> Result<Response, Box<dyn Error + Send + Sync>> {+ ) -> std::result::Result<Response, Box<dyn std::error::Error + Send + Sync>>+ {self.barrier.wait().await;Ok(Response {llm_response: LlmResponse::Agg(text_response(@@ -846,15 +877,17 @@ mod tests {for handle in handles {// The timeout turns a serialization deadlock into a failure, not a hang.- let completion = tokio::time::timeout(Duration::from_secs(5), handle).await???;+ let completion = tokio::time::timeout(Duration::from_secs(5), handle)+ .await+ .map_err(|error| LibsyError::external("waiting for test task", error))?+ .map_err(|source| LibsyError::AlgorithmTask { source })??;assert_eq!(completion, "m");}Ok(())}#[tokio::test]- async fn offload_error_propagates_back_to_the_algorithm(- ) -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn offload_error_propagates_back_to_the_algorithm() -> Result<()> {// A client-less target offloads its call; we fulfill the promise with an// Err, which must flow back through `call_llm_target` into the algorithm and// out as an error step — not a response.@@ -866,11 +899,13 @@ mod tests {while let Some(step) = stream.next().await {match step {Ok(Step::CallLlm(call)) => {- call.respond(Err("upstream model call failed".into()))?;+ call.respond(Err(test_error("upstream model call failed")))?;}Ok(Step::Decision(_)) => {}Ok(Step::ReturnToAgent(..)) => {- return Err("expected the offload error to propagate, got a response".into());+ return Err(test_error(+ "expected the offload error to propagate, got a response",+ ));}Err(err) => {// The algorithm's `call_llm_target` saw the error via the promise.@@ -885,8 +920,7 @@ mod tests {}#[tokio::test]- async fn dropping_the_stream_cancels_the_algorithm_task(- ) -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn dropping_the_stream_cancels_the_algorithm_task() -> Result<()> {use std::sync::atomic::{AtomicBool, Ordering};use std::time::Duration;use tokio::sync::mpsc;@@ -916,7 +950,7 @@ mod tests {_ctx: Context,_driver: Driver,_request: Request,- ) -> Result<Response, Box<dyn Error + Send + Sync>> {+ ) -> Result<Response> {let _guard = DropGuard(self.dropped.clone());let _ = self.started.send(());// Await forever without ever touching the driver.@@ -933,7 +967,10 @@ mod tests {});let stream = algo.run_stream(Context::default(), request());- started_rx.recv().await.ok_or("task never started")?;+ started_rx+ .recv()+ .await+ .ok_or_else(|| test_error("task never started"))?;drop(stream);tokio::time::sleep(Duration::from_millis(100)).await;@@ -945,8 +982,7 @@ mod tests {}#[tokio::test]- async fn create_run_task_panic_surfaces_as_a_stream_error(- ) -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn create_run_task_panic_surfaces_as_a_stream_error() -> Result<()> {// An algorithm whose task panics must surface an `Err` step to the stream// consumer, not abort the process from an unobserved detached task.struct Panicky;@@ -962,7 +998,7 @@ mod tests {_ctx: Context,_driver: Driver,_request: Request,- ) -> Result<Response, Box<dyn Error + Send + Sync>> {+ ) -> Result<Response> {panic!("boom");}}@@ -975,10 +1011,10 @@ mod tests {while let Some(step) = stream.next().await {match step {Err(err) => {- assert!(err.to_string().contains("panicked"));+ assert!(matches!(err, LibsyError::AlgorithmTask { .. }));saw_error = true;}- Ok(_) => return Err("expected the panic to surface as an error step".into()),+ Ok(_) => return Err(test_error("expected the panic to surface as an error step")),}}@@ -987,8 +1023,7 @@ mod tests {}#[tokio::test]- async fn run_returns_an_error_when_the_algorithm_task_panics(- ) -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn run_returns_an_error_when_the_algorithm_task_panics() -> Result<()> {// The panic surfaces as an `Err` step inside `run_stream`; `run` propagates it// via `?`, so the caller gets an `Err` rather than a hang or a silent panic.struct Panicky;@@ -1004,24 +1039,25 @@ mod tests {_ctx: Context,_driver: Driver,_request: Request,- ) -> Result<Response, Box<dyn Error + Send + Sync>> {+ ) -> Result<Response> {panic!("boom");}}let algo: Arc<dyn Algorithm> = Arc::new(Panicky);match algo.run(Context::default(), request()).await {- Ok(_) => Err("expected run to surface the algorithm panic as an error".into()),+ Ok(_) => Err(test_error(+ "expected run to surface the algorithm panic as an error",+ )),Err(err) => {- assert!(err.to_string().contains("panicked"));+ assert!(matches!(err, LibsyError::AlgorithmTask { .. }));Ok(())}}}#[tokio::test]- async fn cancelling_run_cancels_the_algorithm_task() -> Result<(), Box<dyn Error + Send + Sync>>- {+ async fn cancelling_run_cancels_the_algorithm_task() -> Result<()> {use std::sync::atomic::{AtomicBool, Ordering};use std::time::Duration;use tokio::sync::mpsc;@@ -1051,7 +1087,7 @@ mod tests {_ctx: Context,_driver: Driver,_request: Request,- ) -> Result<Response, Box<dyn Error + Send + Sync>> {+ ) -> Result<Response> {let _guard = DropGuard(self.dropped.clone());let _ = self.started.send(());// Hang forever without ever touching the driver, so only cancellation@@ -1071,7 +1107,10 @@ mod tests {// Drive `run` on its own task, wait until the algorithm task is up, then cancel// `run` — dropping its future (and the `run_stream` stream it holds).let run_task = tokio::spawn(async move { algo.run(Context::default(), request()).await });- started_rx.recv().await.ok_or("task never started")?;+ started_rx+ .recv()+ .await+ .ok_or_else(|| test_error("task never started"))?;run_task.abort();tokio::time::sleep(Duration::from_millis(100)).await;@@ -1099,7 +1138,7 @@ mod tests {_ctx: Context,_request: Request,decision: Arc<dyn Decision>,- ) -> Result<Response, Box<dyn Error + Send + Sync>> {+ ) -> std::result::Result<Response, Box<dyn std::error::Error + Send + Sync>> {self.started.notify_one();match self.delay {Some(delay) => tokio::time::sleep(delay).await,@@ -1128,7 +1167,7 @@ mod tests {_ctx: Context,_request: Request,decision: Arc<dyn Decision>,- ) -> Result<Response, Box<dyn Error + Send + Sync>> {+ ) -> std::result::Result<Response, Box<dyn std::error::Error + Send + Sync>> {self.gate.notified().await;Ok(Response {llm_response: LlmResponse::Agg(text_response(@@ -1158,7 +1197,7 @@ mod tests {ctx: Context,driver: Driver,request: Request,- ) -> Result<Response, Box<dyn Error + Send + Sync>> {+ ) -> Result<Response> {let dec_w: Arc<dyn Decision> = Arc::new(TestDecision {model: self.winner.semantic_name.clone(),});@@ -1196,8 +1235,7 @@ mod tests {}#[tokio::test]- async fn run_returns_the_winner_without_a_late_loser_overwriting_it(- ) -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn run_returns_the_winner_without_a_late_loser_overwriting_it() -> Result<()> {// The loser responds 50ms after the winner has already won. `run` must return the// winner, not the loser's `respond`-to-a-dropped-receiver error.let (_trace, response) = hedge(Some(std::time::Duration::from_millis(50)))@@ -1215,14 +1253,13 @@ mod tests {}#[tokio::test]- async fn run_returns_the_winner_without_hanging_on_a_pending_loser(- ) -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn run_returns_the_winner_without_hanging_on_a_pending_loser() -> Result<()> {// The loser never resolves. `run` must return the winner promptly, not hang// waiting for the in-flight loser.let run = hedge(None).run(Context::default(), request());let (_trace, response) = tokio::time::timeout(std::time::Duration::from_secs(1), run).await- .map_err(|_| "run hung waiting for a pending loser")??;+ .map_err(|error| LibsyError::external("waiting for pending loser", error))??;assert_eq!(response.llm_response@@ -1235,8 +1272,7 @@ mod tests {}#[tokio::test]- async fn run_surfaces_a_terminal_error_with_many_calls_in_flight(- ) -> Result<(), Box<dyn Error + Send + Sync>> {+ async fn run_surfaces_a_terminal_error_with_many_calls_in_flight() -> Result<()> {use std::sync::atomic::{AtomicUsize, Ordering};// A large fan-out (10 matched the old, now-removed concurrency cap). The terminal@@ -1257,7 +1293,8 @@ mod tests {_ctx: Context,_request: Request,_decision: Arc<dyn Decision>,- ) -> Result<Response, Box<dyn Error + Send + Sync>> {+ ) -> std::result::Result<Response, Box<dyn std::error::Error + Send + Sync>>+ {if self.started.fetch_add(1, Ordering::SeqCst) + 1 == self.n {self.all_started.notify_one();}@@ -1285,7 +1322,7 @@ mod tests {ctx: Context,driver: Driver,request: Request,- ) -> Result<Response, Box<dyn Error + Send + Sync>> {+ ) -> Result<Response> {let offloads = futures::future::join_all((0..self.n).map(|i| {let decision: Arc<dyn Decision> = Arc::new(TestDecision {model: format!("m{i}"),@@ -1293,9 +1330,9 @@ mod tests {driver.call_llm_target(ctx.clone(), &self.target, request.clone(), decision)}));tokio::select! {- _ = offloads => Err("offloads unexpectedly completed".into()),+ _ = offloads => Err(test_error("offloads unexpectedly completed")),_ = self.all_started.notified() => {- Err("terminal error while calls pending".into())+ Err(test_error("terminal error while calls pending"))}}}@@ -1321,9 +1358,11 @@ mod tests {let run = algo.run(Context::default(), request());let result = tokio::time::timeout(std::time::Duration::from_millis(500), run).await- .map_err(|_| "run hung: terminal error not surfaced with the cap full")?;+ .map_err(|error| {+ LibsyError::external("waiting for terminal error with full call cap", error)+ })?;match result {- Ok(_) => Err("expected the terminal error, got a response".into()),+ Ok(_) => Err(test_error("expected the terminal error, got a response")),Err(err) => {assert!(err.to_string()diff --git a/crates/libsy/src/core/classifier.rs b/crates/libsy/src/core/classifier.rsindex 2097885ea..26c72ea4a 100644--- a/crates/libsy/src/core/classifier.rs+++ b/crates/libsy/src/core/classifier.rs@@ -1,7 +1,7 @@// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.// SPDX-License-Identifier: Apache-2.0-use crate::{Driver, State};+use crate::{Driver, LibsyError, Result, State};use async_trait::async_trait;use switchyard_protocol::Request;@@ -14,8 +14,6 @@ pub struct Score {pub target: String,}-type BoxErr = Box<dyn std::error::Error + Send + Sync>;-/// A classifier's verdict for a request: a set of target [`Score`]s, flagged by how/// confident the classifier is that they are decisive.pub enum Classification {@@ -32,7 +30,7 @@ impl Classification {/// An [`Ambiguous`](Self::Ambiguous) classification also yields `None` unless/// `ignore_ambiguous` is set, in which case it falls back to the plain argmax./// Errors if any confidence is `NaN` (an unorderable score the caller should surface).- pub fn argmax(&self, ignore_ambiguous: bool) -> Result<Option<Score>, BoxErr> {+ pub fn argmax(&self, ignore_ambiguous: bool) -> Result<Option<Score>> {match self {Classification::Scores(scores) => argmax(scores),Classification::Ambiguous(scores) => {@@ -49,11 +47,16 @@ impl Classification {/// The highest-confidence score, or `None` when the set is empty (the classifier abstained)./// Ties keep the first. Errors on a `NaN` confidence,/// which has no defined ordering.-fn argmax(scores: &[Score]) -> Result<Option<Score>, BoxErr> {+fn argmax(scores: &[Score]) -> Result<Option<Score>> {let mut best: Option<&Score> = None;for score in scores.iter() {if score.confidence.is_nan() {- return Err(format!("argmax: NaN confidence for target '{}'", score.target).into());+ return Err(LibsyError::AlgorithmError {+ message: format!(+ "classifier returned NaN confidence for target {:?}",+ score.target+ ),+ });}match best {Some(cur_best) if score.confidence > cur_best.confidence => best = Some(score),@@ -74,7 +77,7 @@ pub trait Classifier: Send + Sync {state: &mut State,request: &Request,driver: Option<&Driver>,- ) -> Result<Classification, BoxErr>;+ ) -> Result<Classification>;}#[cfg(test)]@@ -92,7 +95,7 @@ mod tests {}#[test]- fn argmax_picks_the_highest_confidence_score() -> Result<(), BoxErr> {+ fn argmax_picks_the_highest_confidence_score() -> Result<()> {let scores = vec![score("weak", 0.2), score("strong", 0.9), score("mid", 0.5)];let best = Classification::Scores(scores).argmax(false)?;assert_eq!(best, Some(score("strong", 0.9)));@@ -100,7 +103,7 @@ mod tests {}#[test]- fn argmax_breaks_ties_by_cascade_order() -> Result<(), BoxErr> {+ fn argmax_breaks_ties_by_cascade_order() -> Result<()> {// Equal confidence: the earlier target in cascade order wins the tie.let scores = vec![score("first", 0.7), score("second", 0.7)];let best = Classification::Scores(scores).argmax(false)?;@@ -109,7 +112,7 @@ mod tests {}#[test]- fn argmax_on_an_empty_set_abstains() -> Result<(), BoxErr> {+ fn argmax_on_an_empty_set_abstains() -> Result<()> {// No scores means the classifier abstained — no choice to make.assert_eq!(Classification::Scores(vec![]).argmax(false)?, None);assert_eq!(Classification::Ambiguous(vec![]).argmax(true)?, None);@@ -120,15 +123,21 @@ mod tests {fn argmax_errors_on_nan_confidence() {// A NaN confidence has no defined ordering — surface it rather than guess.let scores = vec![score("weak", 0.3), score("strong", f64::NAN)];- assert!(Classification::Scores(scores).argmax(false).is_err());+ assert!(matches!(+ Classification::Scores(scores).argmax(false),+ Err(LibsyError::AlgorithmError { message })+ if message == "classifier returned NaN confidence for target \"strong\""+ ));// A lone NaN errors too, even with nothing to compare it against.- assert!(Classification::Scores(vec![score("only", f64::NAN)])- .argmax(false)- .is_err());+ assert!(matches!(+ Classification::Scores(vec![score("only", f64::NAN)]).argmax(false),+ Err(LibsyError::AlgorithmError { message })+ if message == "classifier returned NaN confidence for target \"only\""+ ));}#[test]- fn ambiguous_without_ignore_makes_no_choice() -> Result<(), BoxErr> {+ fn ambiguous_without_ignore_makes_no_choice() -> Result<()> {// Ambiguous means "don't pick" unless the caller opts to ignore ambiguity.let scores = vec![score("strong", 0.9)];assert_eq!(Classification::Ambiguous(scores).argmax(false)?, None);@@ -136,7 +145,7 @@ mod tests {}#[test]- fn ambiguous_with_ignore_falls_back_to_argmax() -> Result<(), BoxErr> {+ fn ambiguous_with_ignore_falls_back_to_argmax() -> Result<()> {let scores = vec![score("weak", 0.3), score("strong", 0.8)];let best = Classification::Ambiguous(scores).argmax(true)?;assert_eq!(best, Some(score("strong", 0.8)));@@ -144,7 +153,7 @@ mod tests {}#[test]- fn scores_variant_ignores_the_ambiguous_flag() -> Result<(), BoxErr> {+ fn scores_variant_ignores_the_ambiguous_flag() -> Result<()> {// A definitive classification always yields its argmax, regardless of the flag.let scores = vec![score("a", 0.4), score("b", 0.6)];let with_ignore = Classification::Scores(scores.clone()).argmax(true)?;@@ -164,7 +173,7 @@ mod tests {state: &mut State,request: &Request,_driver: Option<&Driver>,- ) -> Result<Classification, BoxErr> {+ ) -> Result<Classification> {// Stash a marker in `extra` to prove state is threaded mutably.state.extra.insert("ran".to_string(), StateValue::Count(1));let target = request.requested_model().unwrap_or("auto").to_string();@@ -176,7 +185,7 @@ mod tests {}#[tokio::test]- async fn classifier_reads_request_and_mutates_state() -> Result<(), BoxErr> {+ async fn classifier_reads_request_and_mutates_state() -> Result<()> {let mut state = State::default();let request = Request {llm_request: text_request(Some("strong".to_string()), "hi"),diff --git a/crates/libsy/src/core/driver.rs b/crates/libsy/src/core/driver.rsindex ef57a3fa1..3ad94de2b 100644--- a/crates/libsy/src/core/driver.rs+++ b/crates/libsy/src/core/driver.rs@@ -49,20 +49,18 @@use std::{any::Any,- error::Error,sync::{Arc, Mutex},};-use crate::Context;+use crate::{Context, DriverError, LibsyError, Result};use futures::{Stream, StreamExt};use tokio::sync::{mpsc, oneshot};use tokio::time::{timeout, Duration};use tokio_stream::wrappers::ReceiverStream;-type BoxErr = Box<dyn Error + Send + Sync>;type BoxAny = Box<dyn Any + Send>;-type StepResult = Result<DriverStep, BoxErr>;+type StepResult = Result<DriverStep>;// TODO make request timeout configurableconst FULFILL_REQUEST_TIMEOUT: Duration = Duration::from_secs(10);@@ -87,27 +85,30 @@ pub enum DriverStep {pub struct DriverRequest {request: BoxAny,// Fulfilled exactly once — `respond` consumes `self` to send, so no `Option`.- tx: oneshot::Sender<Result<BoxAny, BoxErr>>,+ tx: oneshot::Sender<Result<BoxAny>>,}impl DriverRequest {/// Borrow the request payload as `REQ`. Errors if the producer enqueued a/// different type than the consumer expected.- pub fn request<REQ: Any>(&self) -> Result<&REQ, BoxErr> {- self.request- .downcast_ref::<REQ>()- .ok_or_else(|| "driver: request type mismatch".into())+ pub fn request<REQ: Any>(&self) -> Result<&REQ> {+ self.request.downcast_ref::<REQ>().ok_or_else(|| {+ DriverError::TypeMismatch {+ expected: std::any::type_name::<REQ>(),+ }+ .into()+ })}/// Fulfill the promise with a typed response, or an `Err` to propagate a failure/// back to the producer. Consumes `self`: a promise is fulfilled exactly once.- pub fn respond<RES: Any + Send>(self, res: Result<RES, BoxErr>) -> Result<(), BoxErr> {+ pub fn respond<RES: Any + Send>(self, res: Result<RES>) -> Result<()> {// Erase the response so the single stream item type can carry any RES; the// producer downcasts it back in `fulfill_request`.- let boxed: Result<BoxAny, BoxErr> = res.map(|r| Box::new(r) as BoxAny);+ let boxed: Result<BoxAny> = res.map(|r| Box::new(r) as BoxAny);self.tx.send(boxed)- .map_err(|_| "driver: response receiver dropped".into())+ .map_err(|_| DriverError::ResponseDropped.into())}}@@ -143,30 +144,30 @@ impl TypeErasedDriver {}}- fn ensure_started(&self) -> Result<(), BoxErr> {+ fn ensure_started(&self) -> Result<()> {let guard = self.inner.step_rx.lock()- .map_err(|_| "driver: lock poisoned")?;+ .map_err(|_| DriverError::LockPoisoned)?;if guard.is_none() {Ok(())} else {- Err("get this driver's stream with driver.stream() before calling this method".into())+ Err(DriverError::NotStarted.into())}}/// Enqueue `req` as a [`DriverStep::Request`], await the consumer's response, and/// downcast it to `RES`. Errors if the stream is closed, the promise is dropped/// unfulfilled, the consumer responded with `Err`, or the response was not a `RES`.- pub async fn fulfill_request<REQ, RES>(&self, _ctx: Context, req: REQ) -> Result<RES, BoxErr>+ pub async fn fulfill_request<REQ, RES>(&self, _ctx: Context, req: REQ) -> Result<RES>whereREQ: Any + Send + 'static,RES: Any + Send + 'static,{self.ensure_started()?;- let (tx, rx) = oneshot::channel::<Result<BoxAny, BoxErr>>();+ let (tx, rx) = oneshot::channel::<Result<BoxAny>>();let promise = DriverRequest {request: Box::new(req),tx,@@ -175,24 +176,28 @@ impl TypeErasedDriver {.step_tx.send(Ok(DriverStep::Request(promise))).await- .map_err(|_| "driver: stream closed")?;+ .map_err(|_| DriverError::StreamClosed)?;// Outer error: the promise was dropped without a response. Inner error: the// consumer fulfilled it with an explicit `Err` — propagate it as-is.let response = timeout(FULFILL_REQUEST_TIMEOUT, rx).await- .map_err(|_| "driver: response timed out")?- .map_err(|_| "driver: error receiving response")??;- response- .downcast::<RES>()- .map(|boxed| *boxed)- .map_err(|_| "driver: response type mismatch".into())+ .map_err(|_| DriverError::ResponseTimedOut {+ timeout: FULFILL_REQUEST_TIMEOUT,+ })?+ .map_err(|_| DriverError::ResponseDropped)??;+ response.downcast::<RES>().map(|boxed| *boxed).map_err(|_| {+ DriverError::TypeMismatch {+ expected: std::any::type_name::<RES>(),+ }+ .into()+ })}/// Push a fire-and-forget [`DriverStep::Info`] payload; there is no promise to/// await for a response. Awaits channel capacity (the consumer pacing the stream)/// and errors only if the stream is closed.- pub async fn info<INFO>(&self, _ctx: Context, info: INFO) -> Result<(), BoxErr>+ pub async fn info<INFO>(&self, _ctx: Context, info: INFO) -> Result<()>whereINFO: Any + Send + 'static,{@@ -202,14 +207,14 @@ impl TypeErasedDriver {.step_tx.send(Ok(DriverStep::Info(Box::new(info)))).await- .map_err(|_| "driver: stream closed".into())+ .map_err(|_| DriverError::StreamClosed.into())}/// Emit the terminal [`DriverStep::Done`] with a final payload. Does not close the/// stream (that happens when every `TypeErasedDriver` clone drops); the consumer treats it/// as the last meaningful step. Awaits channel capacity and errors only if the/// stream is closed.- pub async fn done<T>(&self, _ctx: Context, payload: T) -> Result<(), BoxErr>+ pub async fn done<T>(&self, _ctx: Context, payload: T) -> Result<()>whereT: Any + Send + 'static,{@@ -219,37 +224,35 @@ impl TypeErasedDriver {.step_tx.send(Ok(DriverStep::Done(Box::new(payload)))).await- .map_err(|_| "driver: stream closed".into())+ .map_err(|_| DriverError::StreamClosed.into())}/// Terminate the stream with an error item — the producer-side way to surface a/// failure to the consumer (mirrors how the crate's `run_stream` yields an `Err`/// step). Awaits channel capacity and errors only if the stream is/// already closed.- pub async fn fail(&self, _ctx: Context, err: BoxErr) -> Result<(), BoxErr> {+ pub async fn fail(&self, _ctx: Context, err: LibsyError) -> Result<()> {self.ensure_started()?;self.inner.step_tx.send(Err(err)).await- .map_err(|_| "driver: stream closed".into())+ .map_err(|_| DriverError::StreamClosed.into())}/// Take the single consumer stream of [`DriverStep`]s. Callable once: a second/// call yields a one-item stream carrying an `Err`, since the receiver is gone.- pub fn stream(&self) -> impl Stream<Item = Result<DriverStep, BoxErr>> {- // Take the receiver out; `None` means already taken (or the lock was poisoned).- let taken = match self.inner.step_rx.lock() {- Ok(mut guard) => guard.take(),- Err(_) => None,+ pub fn stream(&self) -> impl Stream<Item = Result<DriverStep>> {+ let receiver = match self.inner.step_rx.lock() {+ Ok(mut guard) => guard+ .take()+ .ok_or_else(|| LibsyError::from(DriverError::StreamAlreadyTaken)),+ Err(_) => Err(DriverError::LockPoisoned.into()),};- match taken {- Some(rx) => ReceiverStream::new(rx).left_stream(),- None => futures::stream::once(async {- Err::<DriverStep, BoxErr>("driver: stream already taken".into())- })- .right_stream(),+ match receiver {+ Ok(rx) => ReceiverStream::new(rx).left_stream(),+ Err(error) => futures::stream::once(async move { Err(error) }).right_stream(),}}}@@ -265,8 +268,16 @@ mod tests {use super::*;use futures::StreamExt;+ #[derive(Debug, thiserror::Error)]+ #[error("{0}")]+ struct TestError(&'static str);++ fn test_error(message: &'static str) -> LibsyError {+ LibsyError::external("test", TestError(message))+ }+#[tokio::test]- async fn fulfill_request_round_trips_typed_values() -> Result<(), BoxErr> {+ async fn fulfill_request_round_trips_typed_values() -> Result<()> {let driver = TypeErasedDriver::new();let stream = driver.stream();@@ -279,13 +290,13 @@ mod tests {});tokio::pin!(stream);- match stream.next().await.ok_or("no step")?? {+ match stream.next().await.ok_or(DriverError::StreamClosed)?? {DriverStep::Request(promise) => {let req = *promise.request::<u32>()?;assert_eq!(req, 7);promise.respond::<String>(Ok(format!("got {req}")))?;}- _ => return Err("expected a Request step".into()),+ _ => return Err(test_error("expected a Request step")),}assert_eq!(handle.await??, "got 7");@@ -293,24 +304,26 @@ mod tests {}#[tokio::test]- async fn info_pushes_a_typed_payload() -> Result<(), BoxErr> {+ async fn info_pushes_a_typed_payload() -> Result<()> {let driver = TypeErasedDriver::new();let stream = driver.stream();driver.info(Context::default(), 42u64).await?;tokio::pin!(stream);- match stream.next().await.ok_or("no step")?? {+ match stream.next().await.ok_or(DriverError::StreamClosed)?? {DriverStep::Info(payload) => {- let value = payload.downcast::<u64>().map_err(|_| "wrong info type")?;+ let value = payload+ .downcast::<u64>()+ .map_err(|_| LibsyError::from(DriverError::TypeMismatch { expected: "u64" }))?;assert_eq!(*value, 42);}- _ => return Err("expected an Info step".into()),+ _ => return Err(test_error("expected an Info step")),}Ok(())}#[tokio::test]- async fn done_emits_the_terminal_payload() -> Result<(), BoxErr> {+ async fn done_emits_the_terminal_payload() -> Result<()> {let driver = TypeErasedDriver::new();let stream = driver.stream();driver@@ -318,20 +331,20 @@ mod tests {.await?;tokio::pin!(stream);- match stream.next().await.ok_or("no step")?? {+ match stream.next().await.ok_or(DriverError::StreamClosed)?? {DriverStep::Done(payload) => {- let value = payload- .downcast::<String>()- .map_err(|_| "wrong done type")?;+ let value = payload.downcast::<String>().map_err(|_| {+ LibsyError::from(DriverError::TypeMismatch { expected: "String" })+ })?;assert_eq!(*value, "finished");}- _ => return Err("expected a Done step".into()),+ _ => return Err(test_error("expected a Done step")),}Ok(())}#[tokio::test]- async fn respond_error_propagates_to_the_producer() -> Result<(), BoxErr> {+ async fn respond_error_propagates_to_the_producer() -> Result<()> {let driver = TypeErasedDriver::new();let stream = driver.stream();@@ -343,15 +356,15 @@ mod tests {});tokio::pin!(stream);- match stream.next().await.ok_or("no step")?? {+ match stream.next().await.ok_or(DriverError::StreamClosed)?? {DriverStep::Request(promise) => {- promise.respond::<u32>(Err("upstream failed".into()))?;+ promise.respond::<u32>(Err(test_error("upstream failed")))?;}- _ => return Err("expected a Request step".into()),+ _ => return Err(test_error("expected a Request step")),}match handle.await? {- Ok(_) => Err("expected the error to propagate".into()),+ Ok(_) => Err(test_error("expected the error to propagate")),Err(err) => {assert!(err.to_string().contains("upstream failed"));Ok(())@@ -360,7 +373,7 @@ mod tests {}#[tokio::test]- async fn response_type_mismatch_errors() -> Result<(), BoxErr> {+ async fn response_type_mismatch_errors() -> Result<()> {let driver = TypeErasedDriver::new();let stream = driver.stream();@@ -373,25 +386,29 @@ mod tests {});tokio::pin!(stream);- match stream.next().await.ok_or("no step")?? {+ match stream.next().await.ok_or(DriverError::StreamClosed)?? {DriverStep::Request(promise) => {// But the consumer responds with a u32.promise.respond::<u32>(Ok(99u32))?;}- _ => return Err("expected a Request step".into()),+ _ => return Err(test_error("expected a Request step")),}match handle.await? {- Ok(_) => Err("expected a response type mismatch".into()),+ Ok(_) => Err(test_error("expected a response type mismatch")),Err(err) => {- assert!(err.to_string().contains("response type mismatch"));+ assert!(matches!(+ err,+ LibsyError::Driver(DriverError::TypeMismatch { expected })+ if expected == std::any::type_name::<String>()+ ));Ok(())}}}#[tokio::test]- async fn request_downcast_to_wrong_type_errors() -> Result<(), BoxErr> {+ async fn request_downcast_to_wrong_type_errors() -> Result<()> {let driver = TypeErasedDriver::new();let stream = driver.stream();@@ -403,13 +420,13 @@ mod tests {});tokio::pin!(stream);- match stream.next().await.ok_or("no step")?? {+ match stream.next().await.ok_or(DriverError::StreamClosed)?? {DriverStep::Request(promise) => {assert!(promise.request::<String>().is_err());// Unblock the producer so its task can finish.promise.respond::<u32>(Ok(5u32))?;}- _ => return Err("expected a Request step".into()),+ _ => return Err(test_error("expected a Request step")),}assert_eq!(handle.await??, 5);@@ -417,7 +434,7 @@ mod tests {}#[tokio::test]- async fn closed_stream_errors_on_send() -> Result<(), BoxErr> {+ async fn closed_stream_errors_on_send() -> Result<()> {let driver = TypeErasedDriver::new();// Drop the consumer stream (and its receiver) before producing anything.drop(driver.stream());@@ -432,7 +449,7 @@ mod tests {}#[tokio::test]- async fn promise_dropped_without_response_errors() -> Result<(), BoxErr> {+ async fn promise_dropped_without_response_errors() -> Result<()> {let driver = TypeErasedDriver::new();let stream = driver.stream();@@ -444,10 +461,10 @@ mod tests {});tokio::pin!(stream);- match stream.next().await.ok_or("no step")?? {+ match stream.next().await.ok_or(DriverError::StreamClosed)?? {// Drop the promise without responding.DriverStep::Request(_promise) => {}- _ => return Err("expected a Request step".into()),+ _ => return Err(test_error("expected a Request step")),}assert!(handle.await?.is_err());@@ -455,7 +472,7 @@ mod tests {}#[tokio::test(flavor = "multi_thread", worker_threads = 4)]- async fn concurrent_producers_do_not_cross_responses() -> Result<(), BoxErr> {+ async fn concurrent_producers_do_not_cross_responses() -> Result<()> {const N: usize = 8;let driver = TypeErasedDriver::new();let stream = driver.stream();@@ -478,13 +495,13 @@ mod tests {tokio::pin!(stream);let mut served = 0;while served < N {- match stream.next().await.ok_or("stream ended early")?? {+ match stream.next().await.ok_or(DriverError::StreamClosed)?? {DriverStep::Request(promise) => {let req = *promise.request::<usize>()?;promise.respond::<usize>(Ok(req * 10))?;served += 1;}- _ => return Err("expected a Request step".into()),+ _ => return Err(test_error("expected a Request step")),}}@@ -496,39 +513,41 @@ mod tests {}#[tokio::test]- async fn stream_taken_twice_yields_an_error_item() -> Result<(), BoxErr> {+ async fn stream_taken_twice_yields_an_error_item() -> Result<()> {let driver = TypeErasedDriver::new();let _first = driver.stream();let second = driver.stream();tokio::pin!(second);- match second.next().await.ok_or("expected an item")? {+ match second.next().await.ok_or(DriverError::StreamClosed)? {Err(err) => {assert!(err.to_string().contains("already taken"));Ok(())}- Ok(_) => Err("expected an error item".into()),+ Ok(_) => Err(test_error("expected an error item")),}}#[tokio::test]- async fn fail_surfaces_an_error_item_on_the_stream() -> Result<(), BoxErr> {+ async fn fail_surfaces_an_error_item_on_the_stream() -> Result<()> {let driver = TypeErasedDriver::new();let stream = driver.stream();- driver.fail(Context::default(), "kaboom".into()).await?;+ driver+ .fail(Context::default(), test_error("kaboom"))+ .await?;tokio::pin!(stream);- match stream.next().await.ok_or("no item")? {+ match stream.next().await.ok_or(DriverError::StreamClosed)? {Err(err) => {assert!(err.to_string().contains("kaboom"));Ok(())}- Ok(_) => Err("expected an error item".into()),+ Ok(_) => Err(test_error("expected an error item")),}}#[tokio::test]- async fn dropping_the_stream_terminates_the_producer() -> Result<(), BoxErr> {+ async fn dropping_the_stream_terminates_the_producer() -> Result<()> {let driver = TypeErasedDriver::new();// Box::pin so the stream is owned here and `drop` actually drops the receiver.// (`tokio::pin!` would rebind to a `Pin<&mut _>`, making `drop` a no-op.)@@ -547,9 +566,9 @@ mod tests {// Pace two steps, then terminate by dropping the stream.for _ in 0..2 {- match stream.next().await.ok_or("stream ended early")?? {+ match stream.next().await.ok_or(DriverError::StreamClosed)?? {DriverStep::Info(_) => {}- _ => return Err("expected an Info step".into()),+ _ => return Err(test_error("expected an Info step")),}}drop(stream);@@ -561,17 +580,18 @@ mod tests {}#[test]- fn ensure_started_requires_the_stream_be_taken_first() -> Result<(), BoxErr> {+ fn ensure_started_requires_the_stream_be_taken_first() -> Result<()> {let driver = TypeErasedDriver::new();// Before the consumer takes the stream, the receiver is still present, so producing// is refused — with a message that points at the fix.match driver.ensure_started() {- Ok(()) => return Err("expected ensure_started to reject an untaken stream".into()),- Err(err) => assert!(- err.to_string().contains("driver.stream()"),- "error should point at driver.stream(), got: {err}"- ),+ Ok(()) => {+ return Err(test_error(+ "expected ensure_started to reject an untaken stream",+ ))+ }+ Err(err) => assert!(matches!(err, LibsyError::Driver(DriverError::NotStarted))),}// Taking the stream claims the receiver (`Some` -> `None`), so the driver is started.diff --git a/crates/libsy/src/core/processor.rs b/crates/libsy/src/core/processor.rsindex 3fbd317ef..4147f4b22 100644--- a/crates/libsy/src/core/processor.rs+++ b/crates/libsy/src/core/processor.rs@@ -1,7 +1,7 @@// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.// SPDX-License-Identifier: Apache-2.0-use crate::State;+use crate::{Result, State};use async_trait::async_trait;use switchyard_protocol::{AggLlmResponse, Decision, Request, Signals};@@ -19,13 +19,11 @@ pub enum Event<'a> {ModelResponse(&'a AggLlmResponse),}-type BoxErr = Box<dyn std::error::Error + Send + Sync>;-/// Collects events as the algorithm runs and mutates [`State`]#[async_trait]pub trait Processor: Send + Sync {/// Process an event, accumulating facts into `state`.- async fn process(&self, state: &mut State, event: Event<'_>) -> Result<(), BoxErr>;+ async fn process(&self, state: &mut State, event: Event<'_>) -> Result<()>;}#[cfg(test)]@@ -58,7 +56,7 @@ mod tests {#[async_trait]impl Processor for CountingProcessor {- async fn process(&self, state: &mut State, event: Event<'_>) -> Result<(), BoxErr> {+ async fn process(&self, state: &mut State, event: Event<'_>) -> Result<()> {let entry = state.extra.entry(event_key(&event).to_string())@@ -94,7 +92,7 @@ mod tests {}#[tokio::test]- async fn processor_tallies_each_event_variant_into_state() -> Result<(), BoxErr> {+ async fn processor_tallies_each_event_variant_into_state() -> Result<()> {let processor = CountingProcessor;let mut state = State::default();let req = request();@@ -126,7 +124,7 @@ mod tests {}#[tokio::test]- async fn process_accumulates_state_across_repeated_events() -> Result<(), BoxErr> {+ async fn process_accumulates_state_across_repeated_events() -> Result<()> {let processor = CountingProcessor;let mut state = State::default();let req = request();diff --git a/crates/libsy/src/error.rs b/crates/libsy/src/error.rsnew file mode 100644index 000000000..6282319b8--- /dev/null+++ b/crates/libsy/src/error.rs@@ -0,0 +1,181 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++//! Typed failures surfaced by libsy's orchestration APIs.++use std::{error::Error as StdError, time::Duration};++use thiserror::Error;++/// Result type returned by libsy APIs.+pub type Result<T> = std::result::Result<T, LibsyError>;++/// Failures surfaced while selecting a route, driving an algorithm, or serving a model call.+#[derive(Debug, Error)]+pub enum LibsyError {+ /// A named target was not present in the configured target set.+ #[error("target {target:?} was not found")]+ TargetNotFound {+ /// Missing semantic target name.+ target: String,+ },++ /// Routing was attempted without any configured targets.+ #[error("no routing targets are configured")]+ NoTargets,++ /// An algorithm could not complete for an algorithm-specific reason.+ #[error("{message}")]+ AlgorithmError {+ /// Description of the algorithm failure.+ message: String,+ },++ /// A routed target had no default client for [`crate::Algorithm::run`].+ #[error("target {target:?} has no client to serve the call")]+ MissingClient {+ /// Target that could not be served.+ target: String,+ },++ /// The type-erased offload driver could not complete an operation.+ #[error(transparent)]+ Driver(#[from] DriverError),++ /// The spawned algorithm task failed before returning normally.+ #[error("algorithm task failed: {source}")]+ AlgorithmTask {+ /// Tokio task failure, including panic and unexpected cancellation details.+ #[from]+ source: tokio::task::JoinError,+ },++ /// An algorithm's step stream ended without a terminal response.+ #[error("algorithm run ended without a final response")]+ MissingFinalResponse,++ /// A target's protocol client failed while serving a routed request.+ #[error("client call to target {target:?} failed: {source}")]+ ClientCall {+ /// Target whose client failed.+ target: String,+ /// Error supplied by the protocol-owned client trait.+ #[source]+ source: Box<dyn StdError + Send + Sync>,+ },++ /// A user extension or other foreign operation failed.+ #[error("{operation} failed: {source}")]+ External {+ /// Short description of the operation that failed.+ operation: &'static str,+ /// Original failure.+ #[source]+ source: Box<dyn StdError + Send + Sync>,+ },+}++impl LibsyError {+ /// Wrap an error returned by the protocol-owned client trait.+ pub fn client_call(target: impl Into<String>, source: Box<dyn StdError + Send + Sync>) -> Self {+ Self::ClientCall {+ target: target.into(),+ source,+ }+ }++ /// Preserve a concrete foreign error with a description of the failed operation.+ pub fn external(+ operation: &'static str,+ source: impl StdError + Send + Sync + 'static,+ ) -> Self {+ Self::External {+ operation,+ source: Box::new(source),+ }+ }++ /// Preserve an already boxed foreign error.+ pub fn external_boxed(+ operation: &'static str,+ source: Box<dyn StdError + Send + Sync>,+ ) -> Self {+ Self::External { operation, source }+ }+}++/// Failures in the type-erased promise-over-stream driver.+#[derive(Debug, Error, PartialEq, Eq)]+pub enum DriverError {+ /// A producer operation was attempted before taking the consumer stream.+ #[error("driver stream must be taken before calling producer methods")]+ NotStarted,++ /// The consumer side of the step channel was dropped.+ #[error("driver stream is closed")]+ StreamClosed,++ /// The single-consumer stream had already been taken.+ #[error("driver stream was already taken")]+ StreamAlreadyTaken,++ /// One side of a response promise was dropped before delivery.+ #[error("driver response promise was dropped")]+ ResponseDropped,++ /// A consumer did not fulfill a request before its deadline.+ #[error("driver response timed out after {timeout:?}")]+ ResponseTimedOut {+ /// Maximum time allowed for request fulfillment.+ timeout: Duration,+ },++ /// A type-erased payload did not contain the expected concrete type.+ #[error("driver payload type mismatch: expected {expected}")]+ TypeMismatch {+ /// Human-readable expected payload type or role.+ expected: &'static str,+ },++ /// The driver's receiver lock was poisoned by a panic.+ #[error("driver receiver lock was poisoned")]+ LockPoisoned,+}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn client_call_preserves_target_and_source() {+ let error =+ LibsyError::client_call("strong", Box::new(std::io::Error::other("upstream down")));+ match &error {+ LibsyError::ClientCall { target, source } => {+ assert_eq!(target, "strong");+ assert_eq!(source.to_string(), "upstream down");+ }+ other => panic!("expected ClientCall, got {other:?}"),+ }+ assert_eq!(+ StdError::source(&error).map(ToString::to_string),+ Some("upstream down".to_string())+ );+ }++ #[test]+ fn external_preserves_operation_and_source() {+ let error = LibsyError::external(+ "loading extension",+ std::io::Error::other("bad configuration"),+ );+ assert!(matches!(+ &error,+ LibsyError::External { operation, .. } if *operation == "loading extension"+ ));+ assert_eq!(+ StdError::source(&error).map(ToString::to_string),+ Some("bad configuration".to_string())+ );+ }+}diff --git a/crates/libsy/src/lib.rs b/crates/libsy/src/lib.rsindex 07f959741..947436e11 100644--- a/crates/libsy/src/lib.rs+++ b/crates/libsy/src/lib.rs@@ -80,6 +80,9 @@mod core;pub use core::*;+mod error;+pub use error::{DriverError, LibsyError, Result};+pub mod algorithms;mod observability;diff --git a/crates/libsy/src/observability.rs b/crates/libsy/src/observability.rsindex 3e0ade394..5d7d10ead 100644--- a/crates/libsy/src/observability.rs+++ b/crates/libsy/src/observability.rs@@ -37,10 +37,7 @@ use opentelemetry::metrics::Meter;use opentelemetry::{global, KeyValue};use tracing::Span;-use crate::{Context, Decision, Metadata, Response};--/// Shorthand for the crate's boxed, thread-safe error type.-type BoxErr = Box<dyn std::error::Error + Send + Sync>;+use crate::{Context, Decision, Metadata, Response, Result};/// Instrumentation scope for every libsy meter, span, and log line.const SCOPE: &str = "libsy";@@ -63,7 +60,7 @@ fn meter() -> Meter {}/// `outcome` attribute value for a result: `ok` or `error`.-fn outcome_value<T>(result: &Result<T, BoxErr>) -> &'static str {+fn outcome_value<T>(result: &Result<T>) -> &'static str {if result.is_ok() {"ok"} else {@@ -114,8 +111,8 @@ pub(crate) fn run_span(algorithm: &str, metadata: Option<&Metadata>) -> Span {/// the `libsy.run` span its caller instruments the task with.pub(crate) async fn observe_run<S>(ctx: Context<S>,- run: impl Future<Output = Result<Response, BoxErr>>,-) -> Result<Response, BoxErr> {+ run: impl Future<Output = Result<Response>>,+) -> Result<Response> {let started = Instant::now();let result = run.await;record_run(@@ -130,7 +127,7 @@ pub(crate) async fn observe_run<S>(/// Records the outcome fields on the enclosing `libsy.client_call` span. The/// failure itself is not logged here — it propagates to the algorithm, where/// the `libsy.llm_call` recording logs it once.-pub(crate) fn record_client_call(result: &Result<Response, BoxErr>) {+pub(crate) fn record_client_call(result: &Result<Response>) {let span = Span::current();span.record("outcome", outcome_value(result));if let Err(error) = result {@@ -141,7 +138,7 @@ pub(crate) fn record_client_call(result: &Result<Response, BoxErr>) {/// Records the end of one algorithm run: the run counter and duration/// histogram, the `outcome`/`error` fields on `span`, and a warn log when the/// run failed.-fn record_run(algorithm: &str, duration: Duration, result: &Result<Response, BoxErr>, span: &Span) {+fn record_run(algorithm: &str, duration: Duration, result: &Result<Response>, span: &Span) {let outcome = outcome_value(result);span.record("outcome", outcome);if let Err(error) = result {@@ -169,7 +166,7 @@ pub(crate) fn record_llm_call(algorithm: &str,selected_model: &str,duration: Duration,- result: &Result<Response, BoxErr>,+ result: &Result<Response>,span: &Span,) {let outcome = outcome_value(result);diff --git a/crates/libsy/tests/observability.rs b/crates/libsy/tests/observability.rsindex 56565f7ff..15f30da6e 100644--- a/crates/libsy/tests/observability.rs+++ b/crates/libsy/tests/observability.rs@@ -27,13 +27,21 @@ use tracing_subscriber::registry::LookupSpan;use tracing_subscriber::Layer;use switchyard_libsy::{- AggLlmResponse, Algorithm, Context, Decision, Driver, LlmResponse, LlmTarget, LlmTargetSet,- Metadata, Request, Response, RoutedLlmClient, Step, Usage,+ AggLlmResponse, Algorithm, Context, Decision, Driver, LibsyError, LlmResponse, LlmTarget,+ LlmTargetSet, Metadata, Request, Response, RoutedLlmClient, Step, Usage,};use switchyard_protocol::text_request;type BoxErr = Box<dyn Error + Send + Sync>;+#[derive(Debug, thiserror::Error)]+#[error("{0}")]+struct TestError(&'static str);++fn test_error(message: &'static str) -> LibsyError {+ LibsyError::external("test", TestError(message))+}+/// Locks a mutex, recovering the inner value if a panicking test poisoned it.fn lock<T>(mutex: &Mutex<T>) -> MutexGuard<'_, T> {match mutex.lock() {@@ -303,12 +311,12 @@ impl Algorithm for SingleCallAlgo {ctx: Context,driver: Driver,request: Request,- ) -> Result<Response, BoxErr> {+ ) -> switchyard_libsy::Result<Response> {let target = self.target_set.targets().first()- .ok_or("no targets")?+ .ok_or(LibsyError::NoTargets)?.clone();let decision: Arc<dyn Decision> = Arc::new(StaticDecision {reasoning: format!("picked '{}'", target.semantic_name),@@ -358,7 +366,7 @@ fn find_span(spans: &[SpanRecord], name: &str, field: &str, value: &str) -> Span}#[tokio::test]-async fn successful_run_records_metrics_spans_and_decision_log() -> Result<(), BoxErr> {+async fn successful_run_records_metrics_spans_and_decision_log() -> switchyard_libsy::Result<()> {let (store, exporter, provider) = telemetry();const ALGO: &str = "obs-success-algo";const MODEL: &str = "obs-success-model";@@ -515,7 +523,7 @@ async fn successful_run_records_metrics_spans_and_decision_log() -> Result<(), B}#[tokio::test]-async fn failed_call_records_error_outcome_and_warn_logs() -> Result<(), BoxErr> {+async fn failed_call_records_error_outcome_and_warn_logs() -> switchyard_libsy::Result<()> {let (store, exporter, provider) = telemetry();const ALGO: &str = "obs-failure-algo";const MODEL: &str = "obs-failure-model";@@ -531,11 +539,11 @@ async fn failed_call_records_error_outcome_and_warn_logs() -> Result<(), BoxErr>while let Some(step) = stream.next().await {match step {Ok(Step::CallLlm(call)) => {- call.respond(Err("synthetic upstream failure".into()))?;+ call.respond(Err(test_error("synthetic upstream failure")))?;}Ok(Step::Decision(_)) => {}Ok(Step::ReturnToAgent(_)) => {- return Err("expected the failed call to fail the run".into());+ return Err(test_error("expected the failed call to fail the run"));}Err(_) => saw_error_step = true,}diff --git a/crates/switchyard-server/src/lib.rs b/crates/switchyard-server/src/lib.rsindex 192e9eec5..a466fec72 100644--- a/crates/switchyard-server/src/lib.rs+++ b/crates/switchyard-server/src/lib.rs@@ -21,7 +21,7 @@ use axum::response::{IntoResponse, Response};use axum::routing::{get, post};use axum::{Json, Router};use axum_server::tls_rustls::RustlsConfig;-use libsy::{Algorithm, Context, Decision, Metadata, Request};+use libsy::{Algorithm, Context, Decision, LibsyError, Metadata, Request};use serde_json::{json, Value};use switchyard_llm_client::LlmClientError;use tokio::net::{TcpListener, TcpSocket};@@ -37,8 +37,6 @@ const HEADER_SELECTED_MODEL: &str = "x-model-router-selected-model";const HEADER_RATIONALE: &str = "x-model-router-rationale";const MAX_ROUTING_HEADER_VALUE_LEN: usize = 512;-type BoxError = Box<dyn Error + Send + Sync>;-/// Error returned while configuring or running the server.#[derive(Debug)]pub struct ServerError {@@ -366,8 +364,11 @@ fn sanitize_routing_header_value(value: &str) -> Option<String> {(!value.is_empty()).then(|| value.chars().take(MAX_ROUTING_HEADER_VALUE_LEN).collect())}-fn algorithm_error(error: BoxError) -> Response {- let Some(error) = error.downcast_ref::<LlmClientError>() else {+fn algorithm_error(error: LibsyError) -> Response {+ let LibsyError::ClientCall { source, .. } = &error else {+ return server_error(error.to_string());+ };+ let Some(error) = source.downcast_ref::<LlmClientError>() else {return server_error(error.to_string());};match error {