llm_fallback_router/lib.rs
1//! # llm-fallback-router
2//!
3//! Multi-provider failover for LLM calls.
4//!
5//! You want Anthropic. You also don't want a 503 from Anthropic to break a
6//! production agent. [`Router`] takes an ordered list of providers and falls
7//! through on retryable errors.
8//!
9//! ```no_run
10//! use llm_fallback_router::{Router, Provider, RetryHint};
11//!
12//! #[derive(Debug)]
13//! enum MyError {
14//! RateLimit,
15//! BadAuth,
16//! }
17//!
18//! impl std::fmt::Display for MyError {
19//! fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
20//! write!(f, "{self:?}")
21//! }
22//! }
23//! impl std::error::Error for MyError {}
24//! impl RetryHint for MyError {
25//! fn is_retryable(&self) -> bool {
26//! matches!(self, MyError::RateLimit)
27//! }
28//! }
29//!
30//! fn anthropic_call(_req: &String) -> Result<String, MyError> { Err(MyError::RateLimit) }
31//! fn openai_call(req: &String) -> Result<String, MyError> { Ok(format!("ok: {req}")) }
32//!
33//! let router = Router::<String, String, MyError>::new(vec![
34//! Provider::new("anthropic", anthropic_call),
35//! Provider::new("openai", openai_call),
36//! ]).unwrap();
37//!
38//! let result = router.complete(&"hi".to_string()).unwrap();
39//! assert_eq!(result.provider, "openai");
40//! assert_eq!(result.tries, 2);
41//! ```
42//!
43//! ## Design: trait vs closure for `is_retryable`
44//!
45//! Rust does not have Python-style runtime exception class inspection. To
46//! keep `default_is_retryable` ergonomic without forcing every caller to
47//! plug in a closure, this crate exposes a [`RetryHint`] trait that user
48//! error types implement. [`default_is_retryable`] dispatches through it.
49//!
50//! If you'd rather not implement a trait (e.g. you're wrapping a third-party
51//! error type), supply a closure via [`Router::with_retry_predicate`] or
52//! [`Provider::with_retry_predicate`]; the closure wins over the default.
53//!
54//! [`default_is_retryable_status`] and [`default_is_retryable_by_name`] are
55//! exposed as standalone helpers so a custom [`RetryHint`] impl (or a
56//! closure) can reuse the same status-code list and class-name keywords as
57//! the Python sibling.
58
59#![deny(missing_docs)]
60
61mod attempt;
62mod retryable;
63mod router;
64
65pub use attempt::{Attempt, RouteResult};
66pub use retryable::{
67 default_is_retryable, default_is_retryable_by_name, default_is_retryable_status, RetryHint,
68};
69pub use router::{Provider, RouteError, Router};