Skip to content

Switchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.

Rust

chore(libsy): Give libsy its own error type LibsyError (#129)

Graham King1bafb9b51ece
diff --git a/Cargo.lock b/Cargo.lock
index 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.toml
index 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.md
index 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)`.
+
## Observability
libsy 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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 @@ where
ctx: 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 @@ where
futures::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 @@ where
self: 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 @@ where
error = 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.rs
index 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.rs
index 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 configurable
const 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>
where
REQ: 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<()>
where
INFO: 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<()>
where
T: 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.rs
index 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.rs
new file mode 100644
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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 {