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, ONNX Runtime,
5//! mistral.rs) to remote API services (OpenAI, Gemini, Anthropic, Cohere, Mistral,
6//! Voyage AI, Vertex AI, Azure OpenAI), and raw ONNX graphs.
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. The retrieval surface adds
20//! [`SparseEmbeddingModel`](traits::SparseEmbeddingModel),
21//! [`MultiVectorEmbeddingModel`](traits::MultiVectorEmbeddingModel), and
22//! [`HybridEmbeddingModel`](traits::HybridEmbeddingModel) (single forward pass
23//! over a multi-output graph), and the multimodal extension surface adds
24//! [`ImageEmbeddingModel`](traits::ImageEmbeddingModel),
25//! [`AudioEmbeddingModel`](traits::AudioEmbeddingModel),
26//! [`MultimodalEmbeddingModel`](traits::MultimodalEmbeddingModel),
27//! [`NlpModel`](traits::NlpModel),
28//! [`DocumentExtractionModel`](traits::DocumentExtractionModel),
29//! [`TranscriptionModel`](traits::TranscriptionModel), and
30//! [`OcrModel`](traits::OcrModel) — resolved via the matching methods on
31//! [`ModelRuntime`](runtime::ModelRuntime) (`sparse_embedder`,
32//! `multi_vector_embedder`, `hybrid_embedder`, `image_embedder`,
33//! `multimodal_embedder`, `nlp_model`, `document_extractor`, `transcriber`,
34//! `ocr_model`). `local/onnx` implements the sparse / multi-vector / hybrid /
35//! image / NLP / OCR tasks and `remote/cohere` + `remote/gemini` implement
36//! multimodal embedding; `audio_embedder` has no bundled provider yet.
37//!
38//! # Quick start
39//!
40//! ```rust,no_run
41//! use uni_xervo::api::{ModelAliasSpec, ModelTask};
42//! use uni_xervo::runtime::ModelRuntime;
43//! # #[cfg(feature = "provider-candle")]
44//! use uni_xervo::provider::candle::LocalCandleProvider;
45//!
46//! # #[cfg(feature = "provider-candle")]
47//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
48//! let spec = ModelAliasSpec {
49//! alias: "embed/local".into(),
50//! task: ModelTask::Embed,
51//! provider_id: "local/candle".into(),
52//! model_id: "sentence-transformers/all-MiniLM-L6-v2".into(),
53//! revision: None,
54//! warmup: Default::default(),
55//! required: true,
56//! timeout: None,
57//! load_timeout: None,
58//! retry: None,
59//! options: serde_json::Value::Null,
60//! };
61//!
62//! let runtime = ModelRuntime::builder()
63//! .register_provider(LocalCandleProvider::new())
64//! .catalog(vec![spec])
65//! .build()
66//! .await?;
67//!
68//! let model = runtime.embedding("embed/local").await?;
69//! let embeddings = model.embed(&["Hello, world!"]).await?;
70//! println!("dim: {}", embeddings.vectors[0].len());
71//! # Ok(())
72//! # }
73//! ```
74
75pub mod api;
76pub mod cache;
77// Shared document-VLM output parsers, used by any provider that runs such a
78// model (`local/onnx`, `local/mistralrs`).
79#[cfg(any(
80 feature = "provider-onnx",
81 feature = "provider-onnx-dynamic",
82 feature = "provider-mistralrs"
83))]
84mod doc_parse;
85pub mod error;
86mod options_validation;
87pub mod prelude;
88pub mod provider;
89pub mod reliability;
90pub mod runtime;
91pub mod score;
92pub mod traits;
93
94#[cfg(test)]
95mod mock;