Architecture

Rig is a Rust library for building LLM-powered applications. Everything lives in one core crate that stacks provider clients underneath a small set of composable abstractions - completion and embedding models, agents, tools, and vector stores - which your app builds on. This page is the map: the layer stack, the crate layout, and how the pieces compose.

flowchart TB
    App["Your app: agents, workflows, RAG"]
    subgraph Core["rig abstractions"]
      direction LR
      Agent["Agent"]
      Completion["CompletionModel"]
      Embedding["EmbeddingModel"]
      Tools["Tools"]
      VS["VectorStore /<br/>VectorStoreIndex"]
    end
    Providers["Provider clients<br/>OpenAI · Anthropic · Cohere · Gemini · ..."]
    Stores["Vector-store crates<br/>rig-mongodb · rig-lancedb · rig-neo4j · rig-qdrant · rig-surrealdb"]

    App --> Core
    Core --> Providers
    VS --> Stores

A minimal agent shows the whole stack in miniature - a provider client at the bottom, an Agent on top, your code driving it:

use rig::client::{CompletionClient, ProviderClient};
use rig::completion::Prompt;
use rig::providers::openai;

#[tokio::main]
async fn main() -> Result<(), anyhow::Error> {
    let client = openai::Client::from_env()?;

    let agent = client
        .agent("gpt-5.5")
        .preamble("You are a helpful assistant.")
        .build();

    let response = agent.prompt("Hello!").await?;
    println!("{response}");

    Ok(())
}

Two surfaces: this guide vs. the API reference

Rig has two complementary sources of documentation:

• This guide (the pages under Core Concepts, Guides, and Integrations) teaches the mental model with minimal, runnable examples - start here to learn what a piece does and why you’d use it.
• The rig API reference on docs.rs is the exhaustive, always-current listing of every trait, type, method, and feature flag - reach for it when you need an exact signature.

Throughout these docs we teach a concept, then link out to docs.rs for the full details rather than repeating signatures that can drift.

Crate layout

Rig’s core lives in a single crate, with vector-store integrations shipped as separate companion crates so you only pull in the dependencies you actually use.

• Directoryrig

  • Directoryloaders

    • file.rs
    • pdf.rs
    • …(other loaders)
  • Directoryproviders

    • Directoryopenai

      • mod.rs
      • client.rs
      • completion.rs
    • … (other providers)
  • Directoryvector_store

    • in_memory_store.rs
• Directoryrig-mongodb

  • lib.rs
• Directoryrig-neo4j

  • mod.rs
• …

rig (the rig crate, imported as rig) contains everything you need to build agents: provider clients, the completion and embedding model traits, agents, tools, extractors, loaders, and an in-memory vector store.

Companion crates extend the core behind their own dependencies — vector-store implementations backed by external databases, plus reusable conversation-memory policies:

• rig-mongodb - MongoDB Atlas Vector Search
• rig-lancedb - LanceDB
• rig-neo4j - Neo4j
• rig-qdrant - Qdrant
• rig-surrealdb - SurrealDB
• rig-memory - history-bounding policies (sliding window, token budget, compaction) for conversation memory

See Integrations for the full list of providers and vector stores.

Core abstractions

Rig is built around a small set of traits and types that compose. This section walks the chain from a provider client up to the higher-level abstractions.

Provider clients

Each model provider (OpenAI, Anthropic, Cohere, Gemini, and more) exposes a Client. The client is your entry point: it holds credentials and constructs completion and embedding models. Clients are typically created with Client::from_env() (reading an API key from the environment) or Client::new(api_key).

See Providers & Clients.

Completion and embedding models

From a client you create models that implement Rig’s two core low-level traits:

• CompletionModel - a common interface for building and executing completion (chat) requests, created with client.completion_model("gpt-5.5").
• EmbeddingModel - a common interface for turning text into vector embeddings, created with client.embedding_model("text-embedding-3-small").

Because these traits are provider-agnostic, code written against them works across providers with minimal changes.

See Completions and Embeddings.

Agents

The Agent type is Rig’s high-level abstraction over a completion model. It bundles a model with a preamble (system prompt), tools, and optional context, and handles the agentic loop - including tool calls - for you. Agents range from a simple prompt-in, text-out assistant to a full RAG system answering questions from a knowledge base (see the minimal example above).

See Agents, Tools, and the Quickstart.

Vector stores and indexes

For retrieval and RAG, Rig defines a common interface for vector storage and search:

• VectorStore - persists documents and their embeddings.
• VectorStoreIndex - performs similarity search over stored embeddings.

Any type implementing these traits can serve as an agent’s knowledge base or as a source of context documents in a custom multi-model architecture. rig ships an in-memory implementation; the companion crates above implement the same traits over external databases.

See Vector Stores & RAG and Vector Stores.

Workflows

Compose models, agents, and tools into multi-step flows using plain Rust - chain steps sequentially, run them concurrently with futures::join!, or branch with match. There’s no DSL; a workflow is just ordinary async code.

See Workflows.

See also

• Core Concepts - the full concept hub.
• Quickstart - build your first agent.
• rig API reference on docs.rs - exhaustive signatures.