Struct FallbackChain 

pub struct FallbackChain { /* private fields */ }

Fault-recovery primitives for resilient agent execution. An ordered chain of models for sequential fallback on failure.

When a model request fails, the chain allows easy iteration to the next available model in priority order. This is useful for implementing automatic failover strategies.

Example

use oxi_ai::fallback_chain::FallbackChain;

// From string IDs
let chain = FallbackChain::from_ids(&["openai/gpt-4o", "google/gemini-2.0-flash"])?;

// Direct construction
let models = vec![model1, model2];
let chain = FallbackChain::new(models);

// Find next model after failure
if let Some(next) = chain.next("openai/gpt-4o") {
    // Use next model...
}

Implementations

impl FallbackChain

pub fn new(models: Vec<&'static ModelEntry>) -> FallbackChain

Creates a new fallback chain from an ordered list of models.

Arguments

• models - A vector of model entries in priority order (first = highest priority)

Example

use oxi_ai::model_db::get_model_entry;

let models = vec![
    get_model_entry("openai", "gpt-4o").unwrap(),
    get_model_entry("anthropic", "claude-sonnet-4-20250514").unwrap(),
];
let chain = FallbackChain::new(models);

pub fn from_ids(ids: &[&str]) -> Result<FallbackChain, FallbackChainError>

Creates a fallback chain from “provider/model” ID strings.

Each string must be in the format "provider/model-id", for example:

• "anthropic/claude-sonnet-4-20250514"
• "openai/gpt-4o"
• "google/gemini-2.0-flash"

Arguments

• ids - Slice of strings in "provider/model" format

Errors

Returns a FallbackChainError if any model ID cannot be found in the database.

Example

let chain = FallbackChain::from_ids(&[
    "anthropic/claude-sonnet-4-20250514",
    "openai/gpt-4o",
])?;

pub fn next(&self, current: &str) -> Option<&'static ModelEntry>

Returns the next model in the chain after the current one.

Arguments

• current - The current model ID in "provider/model" format

Returns

• Some(&ModelEntry) - The next model in the chain
• None - If the current model is not in the chain, or it’s the last model

Example

let chain = FallbackChain::from_ids(&["a", "b", "c"])?;

assert_eq!(chain.next("a").map(|m| m.id), Some("b"));
assert_eq!(chain.next("b").map(|m| m.id), Some("c"));
assert_eq!(chain.next("c"), None); // Last in chain
assert_eq!(chain.next("unknown"), None); // Not in chain

pub fn index_of(&self, model_id: &str) -> Option<usize>

Returns the index of a model in the chain.

Arguments

• model_id - The model ID in "provider/model" format

Returns

• Some(usize) - The zero-based position in the chain
• None - If the model is not in the chain

Example

let chain = FallbackChain::from_ids(&["a", "b", "c"])?;

assert_eq!(chain.index_of("a"), Some(0));
assert_eq!(chain.index_of("b"), Some(1));
assert_eq!(chain.index_of("c"), Some(2));
assert_eq!(chain.index_of("unknown"), None);

pub fn iter(&self) -> impl Iterator<Item = &'static ModelEntry>

Returns an iterator over the model entries in the chain.

Example

let chain = FallbackChain::from_ids(&["a", "b", "c"])?;

for model in chain.iter() {
    println!("Model: {} ({})", model.name, model.provider);
}

pub fn is_empty(&self) -> bool

Returns true if the chain contains no models.

Example

let chain = FallbackChain::new(vec![]);
assert!(chain.is_empty());

let chain = FallbackChain::from_ids(&["a"])?;
assert!(!chain.is_empty());

pub fn len(&self) -> usize

Returns the number of models in the chain.

Example

let chain = FallbackChain::from_ids(&["a", "b", "c"])?;
assert_eq!(chain.len(), 3);

pub fn models(&self) -> &[&'static ModelEntry]

Returns a slice of all model entries.

Example

let chain = FallbackChain::from_ids(&["a", "b", "c"])?;
let models: Vec<_> = chain.models();

pub fn names(&self) -> &[String]

Returns the model ID strings that were used to create the chain.

Example

let chain = FallbackChain::from_ids(&["openai/gpt-4o", "anthropic/claude-sonnet-4"])?;
assert_eq!(chain.names(), &["openai/gpt-4o", "anthropic/claude-sonnet-4"]);

pub fn first(&self) -> Option<&'static ModelEntry>

Returns the first model in the chain, if any.

Example

let chain = FallbackChain::from_ids(&["a", "b"])?;
assert_eq!(chain.first().map(|m| m.id), Some("a"));

let empty: FallbackChain = FallbackChain::new(vec![]);
assert_eq!(empty.first(), None);

pub fn last(&self) -> Option<&'static ModelEntry>

Returns the last model in the chain, if any.

Example

let chain = FallbackChain::from_ids(&["a", "b"])?;
assert_eq!(chain.last().map(|m| m.id), Some("b"));

let empty: FallbackChain = FallbackChain::new(vec![]);
assert_eq!(empty.last(), None);

pub fn contains(&self, model_id: &str) -> bool

Checks if the chain contains a specific model.

Arguments

• model_id - The model ID in "provider/model" format

Example

let chain = FallbackChain::from_ids(&["a", "b"])?;
assert!(chain.contains("a"));
assert!(!chain.contains("c"));

pub fn from_inclusive(&self, model_id: &str) -> Option<FallbackChain>

Creates a new chain with models after (and including) the given model.

This is useful for continuing fallback after a model succeeds but you want to track the remaining options.

Arguments

• model_id - The model ID to start from (inclusive)

Returns

• Some(FallbackChain) - The remaining models from the starting point
• None - If the model is not in the chain

Example

let chain = FallbackChain::from_ids(&["a", "b", "c"])?;
let remaining = chain.from_inclusive("b")?;
assert_eq!(remaining.names(), &["b", "c"]);

pub fn from_after(&self, model_id: &str) -> Option<FallbackChain>

Creates a new chain with models after (excluding) the given model.

Arguments

• model_id - The model ID to skip

Returns

• Some(FallbackChain) - The remaining models after the given model
• None - If the model is not in the chain or is the last model

Example

let chain = FallbackChain::from_ids(&["a", "b", "c"])?;
let remaining = chain.from_after("b")?;
assert_eq!(remaining.names(), &["c"]);

Trait Implementations

impl Clone for FallbackChain

fn clone(&self) -> FallbackChain

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for FallbackChain

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for FallbackChain

fn default() -> FallbackChain

Creates a default fallback chain with cheap, reliable models.

The default chain includes models from multiple providers to ensure redundancy and cost efficiency. These are selected based on:

• Low input cost
• Wide context window
• Vision support for versatility

impl PartialEq for FallbackChain

fn eq(&self, other: &FallbackChain) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for FallbackChain