rig_core/
lib.rs

1#![cfg_attr(docsrs, feature(doc_cfg))]
2#![cfg_attr(
3    test,
4    allow(
5        clippy::expect_used,
6        clippy::indexing_slicing,
7        clippy::panic,
8        clippy::unwrap_used,
9        clippy::unreachable
10    )
11)]
12//! Rig is a Rust library for building LLM-powered applications that focuses on ergonomics and modularity.
13//!
14//! # Table of contents
15//! - [High-level features](#high-level-features)
16//! - [Simple Example](#simple-example)
17//! - [Core Concepts](#core-concepts)
18//! - [Integrations](#integrations)
19//!
20//! # High-level features
21//! - Full support for LLM completion and embedding workflows
22//! - Simple but powerful common abstractions over LLM providers (e.g. OpenAI, Cohere) and vector stores (e.g. MongoDB, in-memory)
23//! - Integrate LLMs in your app with minimal boilerplate
24//!
25//! # Simple example
26//! ```no_run
27//! use rig_core::{
28//!     client::{CompletionClient, ProviderClient},
29//!     completion::{AssistantContent, CompletionModel},
30//!     providers::openai,
31//! };
32//!
33//! #[tokio::main]
34//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
35//!     // Create an OpenAI client and completion model.
36//!     // This requires the `OPENAI_API_KEY` environment variable to be set.
37//!     let openai_client = openai::Client::from_env()?;
38//!     let model = openai_client.completion_model(openai::GPT_5_2);
39//!
40//!     let request = model.completion_request("Who are you?").build();
41//!     let response = model.completion(request).await?;
42//!     for item in response.choice {
43//!         if let AssistantContent::Text(text) = item {
44//!             println!("{}", text.text);
45//!         }
46//!     }
47//!
48//!     Ok(())
49//! }
50//! ```
51//! Note: using `#[tokio::main]` requires you enable tokio's `macros` and `rt-multi-thread` features
52//! or just `full` to enable all features (`cargo add tokio --features macros,rt-multi-thread`).
53//!
54//! # Core concepts
55//! ## Completion and embedding models
56//! Rig provides a consistent API for working with LLMs and embeddings. Specifically,
57//! each provider (e.g. OpenAI, Cohere) has a `Client` struct that can be used to initialize completion
58//! and embedding models. These models implement the [CompletionModel](crate::completion::CompletionModel)
59//! and [EmbeddingModel](crate::embeddings::EmbeddingModel) traits respectively, which provide a common,
60//! low-level interface for creating completion and embedding requests and executing them.
61//!
62//! ## Agent runtimes
63//! This crate owns the provider-agnostic model, message, tool, and storage
64//! contracts. The sibling `rig-agent` crate provides the classic builder and
65//! run-loop API.
66//!
67//! ## Vector stores and indexes
68//! Rig provides a common interface for working with vector stores and indexes. Specifically, the library
69//! provides the [VectorStoreIndex](crate::vector_store::VectorStoreIndex)
70//! trait, which can be implemented to define vector stores and indices respectively.
71//! Indexes can be queried directly by applications or runtimes. For active RAG,
72//! expose the index through its blanket [`PortableTool`](crate::tool::PortableTool)
73//! implementation, or through a custom tool, so the model decides when and how
74//! to retrieve. The classic `rig-agent` runtime can also query indexes from
75//! hooks and append the resulting documents to a turn's extra context.
76//!
77//! Indexes can also serve custom architectures that use multiple LLMs or agents.
78//!
79//! ## Conversation memory
80//! Runtimes can load and persist per-conversation history through the
81//! [ConversationMemory](crate::memory::ConversationMemory) trait. The classic
82//! `rig-agent` runtime integrates this portable backend contract.
83//! The default in-process backend
84//! [InMemoryConversationMemory](crate::memory::InMemoryConversationMemory) is suitable
85//! for tests and single-process agents; reusable history-shaping policies (sliding
86//! window, token budget) live in the [`rig-memory`](https://crates.io/crates/rig-memory)
87//! companion crate. See [`examples/agent_with_memory.rs`](https://github.com/0xPlaygrounds/rig/blob/main/examples/agent_with_memory.rs)
88//! for a runnable end-to-end example.
89//!
90//! # Integrations
91//! ## Model Providers
92//! Rig natively supports the following completion and embedding model provider integrations:
93//! - Anthropic
94//! - Azure OpenAI
95//! - ChatGPT and GitHub Copilot auth-backed clients
96//! - Cohere
97//! - DeepSeek
98//! - Gemini
99//! - Groq
100//! - Hugging Face
101//! - Hyperbolic
102//! - Llamafile
103//! - MiniMax
104//! - Mira
105//! - Mistral
106//! - Moonshot
107//! - Ollama
108//! - OpenAI
109//! - OpenRouter
110//! - Perplexity
111//! - Together
112//! - Voyage AI
113//! - xAI
114//! - Xiaomi MiMo
115//! - Z.ai
116//!
117//! You can also implement your own model provider integration by defining types that
118//! implement the [CompletionModel](crate::completion::CompletionModel) and [EmbeddingModel](crate::embeddings::EmbeddingModel) traits.
119//!
120//! Vector stores are available as separate companion-crates:
121//!
122//! - MongoDB: [`rig-mongodb`](https://github.com/0xPlaygrounds/rig/tree/main/crates/rig-mongodb)
123//! - LanceDB: [`rig-lancedb`](https://github.com/0xPlaygrounds/rig/tree/main/crates/rig-lancedb)
124//! - Neo4j: [`rig-neo4j`](https://github.com/0xPlaygrounds/rig/tree/main/crates/rig-neo4j)
125//! - Qdrant: [`rig-qdrant`](https://github.com/0xPlaygrounds/rig/tree/main/crates/rig-qdrant)
126//! - SQLite: [`rig-sqlite`](https://github.com/0xPlaygrounds/rig/tree/main/crates/rig-sqlite)
127//! - SurrealDB: [`rig-surrealdb`](https://github.com/0xPlaygrounds/rig/tree/main/crates/rig-surrealdb)
128//! - Milvus: [`rig-milvus`](https://github.com/0xPlaygrounds/rig/tree/main/crates/rig-milvus)
129//! - ScyllaDB: [`rig-scylladb`](https://github.com/0xPlaygrounds/rig/tree/main/crates/rig-scylladb)
130//! - AWS S3Vectors: [`rig-s3vectors`](https://github.com/0xPlaygrounds/rig/tree/main/crates/rig-s3vectors)
131//! - HelixDB: [`rig-helixdb`](https://github.com/0xPlaygrounds/rig/tree/main/crates/rig-helixdb)
132//! - Cloudflare Vectorize: [`rig-vectorize`](https://github.com/0xPlaygrounds/rig/tree/main/crates/rig-vectorize)
133//!
134//! You can also implement your own vector store integration by defining types that
135//! implement the [VectorStoreIndex](crate::vector_store::VectorStoreIndex) trait.
136//!
137//! The following providers are available as separate companion-crates:
138//!
139//! - AWS Bedrock: [`rig-bedrock`](https://github.com/0xPlaygrounds/rig/tree/main/crates/rig-bedrock)
140//! - Fastembed: [`rig-fastembed`](https://github.com/0xPlaygrounds/rig/tree/main/crates/rig-fastembed)
141//! - Google Gemini gRPC: [`rig-gemini-grpc`](https://github.com/0xPlaygrounds/rig/tree/main/crates/rig-gemini-grpc)
142//! - Google Vertex AI: [`rig-vertexai`](https://github.com/0xPlaygrounds/rig/tree/main/crates/rig-vertexai)
143//!
144
145extern crate self as rig;
146
147#[cfg(feature = "audio")]
148#[cfg_attr(docsrs, doc(cfg(feature = "audio")))]
149pub mod audio_generation;
150pub mod client;
151pub mod completion;
152pub mod embeddings;
153pub mod http_client;
154pub mod id;
155#[cfg(feature = "image")]
156#[cfg_attr(docsrs, doc(cfg(feature = "image")))]
157pub mod image_generation;
158/// Internal JSON helpers shared with sibling runtime crates (e.g. `rig-agent`).
159/// Not part of rig-core's stable public API.
160#[doc(hidden)]
161pub mod json_utils;
162pub mod loaders;
163pub mod markers;
164pub mod memory;
165pub mod model;
166pub mod one_or_many;
167pub mod prelude;
168pub(crate) mod provider_response;
169pub mod providers;
170pub mod rerank;
171
172pub mod streaming;
173#[cfg(any(test, feature = "test-utils"))]
174#[cfg_attr(docsrs, doc(cfg(feature = "test-utils")))]
175pub mod test_utils;
176pub mod tool;
177pub mod transcription;
178pub mod vector_store;
179pub mod wasm_compat;
180
181// Re-export commonly used types and traits
182pub use completion::message;
183pub use embeddings::Embed;
184pub use one_or_many::{EmptyListError, OneOrMany};
185pub use provider_response::ProviderResponseError;
186// `schemars`, `serde`, and `serde_json` are re-exported so macro-generated
187// code (and downstream crates) can resolve them through Rig instead of
188// requiring a direct dependency on each.
189pub use schemars;
190pub use serde;
191pub use serde_json;
192
193#[cfg(feature = "derive")]
194#[cfg_attr(docsrs, doc(cfg(feature = "derive")))]
195pub use rig_derive::Embed;
196
197// The portable `#[rig_tool]` macro produces context-free `PortableTool`s, which
198// are rig-core-owned, so direct `rig-core` dependents can reach it without
199// pulling in `rig-derive` themselves.
200#[cfg(feature = "derive")]
201#[cfg_attr(docsrs, doc(cfg(feature = "derive")))]
202pub use rig_derive::{rig_tool, rig_tool as tool_macro};
203
204pub mod telemetry;
rig_core/lib.rs

rig_core/
lib.rs
