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

[grahamking]

Replaces the crate-wide BoxErr alias with two typed enums in a new error.rs: LibsyError and DriverError.

Previously we returned Box<dyn Error ..> which makes it difficult for the caller to identify what happened, and handle different errors differently.

Now we return LibsyError based on thiserror.

This means the tests can also match on the specific error variant, rather than is_err() or a string fragment.

Dependency protocol gives us a Box<dyn Error ..> so we preserve that in one variant of LibsyError. Later that will also get a typed error and we can remove this.

Claude's review:

Verdict: Approve. Clean, mechanical refactor from Box<dyn Error + Send + Sync> to a thiserror-based LibsyError/DriverError. Compiles, lints clean, all tests pass, no behavior regressions. Nothing blocking.

Claude was remarkably complimentary of Sol's work.

Signed-off-by: Graham King grahamk@nvidia.com
Assisted-by: Codex:GPT 5.6 Sol medium

Summary by CodeRabbit

• New Features

  • Added a unified, structured error-handling system for routing, driver, client, and algorithm operations.
  • Exposed consistent result and error types across the library and server integrations.
  • Added clearer error details for missing targets, invalid confidence values, timeouts, stream failures, and client-call issues.

• Documentation

  • Updated examples and API guidance to reflect the new structured error results.

[grahamking]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

[coderabbitai]

Walkthrough

The pull request introduces a typed LibsyError/DriverError result model, updates libsy APIs and algorithms to use it, migrates examples and tests, preserves observability behavior, and adapts server-side client error mapping.

Changes

Typed error contract

Layer / File(s)	Summary
Public error types and documentation crates/libsy/src/error.rs, crates/libsy/src/lib.rs, crates/libsy/Cargo.toml, crates/libsy/README.md	Adds exported LibsyError, DriverError, and Result types, the thiserror dependency, and documentation for the typed API contract.

Core execution and driver plumbing

Layer / File(s)	Summary
Core orchestration results crates/libsy/src/core/algorithm.rs, crates/libsy/src/core/classifier.rs, crates/libsy/src/core/processor.rs	Changes orchestration, classification, processing, streaming, target lookup, cancellation, and aggregation paths to return typed results and specific error variants.
Driver promise and stream errors crates/libsy/src/core/driver.rs	Replaces boxed driver failures with structured timeout, stream, lock, response, and type-mismatch errors.

Algorithm implementations and examples

Layer / File(s)	Summary
Built-in and ensemble algorithms crates/libsy/src/algorithms/*, crates/libsy/examples/ensemble.rs	Updates algorithm implementations and tests to use Result, including typed no-target, abstention, mismatch, and external failures.
Research and streaming examples crates/libsy/examples/research_agent*.rs, crates/libsy/examples/streaming_agent.rs	Maps aggregation and stream-read failures through LibsyError while retaining the existing example flows.

Observability and server integration

Layer / File(s)	Summary
Telemetry and server error mapping crates/libsy/src/observability.rs, crates/libsy/tests/observability.rs, crates/switchyard-server/src/lib.rs	Updates observability result signatures and tests, and maps LibsyError::ClientCall sources to existing server responses.

Estimated code review effort: 4 (Complex) | ~45 minutes

Poem

I’m a rabbit with typed errors bright,
Hopping through results day and night.
Boxes melt away, variants bloom,
Streams carry meaning through every room.
“No targets!” says the hare with cheer—
Libsy now speaks crystal clear.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: introducing libsy's dedicated LibsyError type.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

crates/libsy/src/error.rs (1)

49-56: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Redundant #[source] alongside #[from].

#[from] already implies #[source] on the same field, so the explicit #[source] here is unnecessary.

♻️ Optional cleanup

     AlgorithmTask {
         /// Tokio task failure, including panic and unexpected cancellation details.
         #[from]
-        #[source]
         source: tokio::task::JoinError,
     },

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@crates/libsy/src/error.rs` around lines 49 - 56, Remove the redundant
#[source] attribute from the source field in the AlgorithmTask error variant,
leaving #[from] to provide the error source behavior.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@crates/libsy/src/error.rs`:
- Around line 49-56: Remove the redundant #[source] attribute from the source
field in the AlgorithmTask error variant, leaving #[from] to provide the error
source behavior.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: e377c9a7-c62d-4828-8f7a-a943e509e386

📥 Commits

Reviewing files that changed from the base of the PR and between d4c37dc and 7ab7702.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock, !Cargo.lock

📒 Files selected for processing (20)

• crates/libsy/Cargo.toml
• crates/libsy/README.md
• crates/libsy/examples/ensemble.rs
• crates/libsy/examples/research_agent.rs
• crates/libsy/examples/research_agent_core.rs
• crates/libsy/examples/streaming_agent.rs
• crates/libsy/src/algorithms/fall_through.rs
• crates/libsy/src/algorithms/llm_class.rs
• crates/libsy/src/algorithms/noop.rs
• crates/libsy/src/algorithms/rand.rs
• crates/libsy/src/algorithms/subagent_override.rs
• crates/libsy/src/core/algorithm.rs
• crates/libsy/src/core/classifier.rs
• crates/libsy/src/core/driver.rs
• crates/libsy/src/core/processor.rs
• crates/libsy/src/error.rs
• crates/libsy/src/lib.rs
• crates/libsy/src/observability.rs
• crates/libsy/tests/observability.rs
• crates/switchyard-server/src/lib.rs