uni_xervo/lib.rs
1//! Unified Rust runtime for local and remote embedding, reranking, and generation models.
2//!
3//! Uni-Xervo provides a single, provider-agnostic API for loading and running ML models
4//! across a wide range of backends — from local inference engines (Candle, FastEmbed,
5//! mistral.rs) to remote API services (OpenAI, Gemini, Anthropic, Cohere, Mistral,
6//! Voyage AI, Vertex AI, Azure OpenAI).
7//!
8//! # Key concepts
9//!
10//! - **[`ModelRuntime`](runtime::ModelRuntime)** — the central runtime that owns providers
11//! and manages a catalog of model aliases.
12//! - **[`ModelAliasSpec`](api::ModelAliasSpec)** — a declarative specification that maps a
13//! human-readable alias (e.g. `"embed/default"`) to a concrete provider + model pair.
14//! - **Providers** — pluggable backends that implement [`ModelProvider`](traits::ModelProvider).
15//! Each provider advertises the tasks it supports and knows how to load models.
16//! - **Traits** — [`EmbeddingModel`](traits::EmbeddingModel),
17//! [`RerankerModel`](traits::RerankerModel), and
18//! [`GeneratorModel`](traits::GeneratorModel) are the task-specific interfaces returned
19//! by the runtime.
20//!
21//! # Quick start
22//!
23//! ```rust,no_run
24//! use uni_xervo::api::{ModelAliasSpec, ModelTask};
25//! use uni_xervo::runtime::ModelRuntime;
26//! # #[cfg(feature = "provider-candle")]
27//! use uni_xervo::provider::candle::LocalCandleProvider;
28//!
29//! # #[cfg(feature = "provider-candle")]
30//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
31//! let spec = ModelAliasSpec {
32//! alias: "embed/local".into(),
33//! task: ModelTask::Embed,
34//! provider_id: "local/candle".into(),
35//! model_id: "sentence-transformers/all-MiniLM-L6-v2".into(),
36//! revision: None,
37//! warmup: Default::default(),
38//! required: true,
39//! timeout: None,
40//! load_timeout: None,
41//! retry: None,
42//! options: serde_json::Value::Null,
43//! };
44//!
45//! let runtime = ModelRuntime::builder()
46//! .register_provider(LocalCandleProvider::new())
47//! .catalog(vec![spec])
48//! .build()
49//! .await?;
50//!
51//! let model = runtime.embedding("embed/local").await?;
52//! let embeddings = model.embed(vec!["Hello, world!"]).await?;
53//! # Ok(())
54//! # }
55//! ```
56
57pub mod api;
58pub mod cache;
59pub mod error;
60mod options_validation;
61pub mod provider;
62pub mod reliability;
63pub mod runtime;
64pub mod traits;
65
66#[cfg(test)]
67mod mock;