0xplaygrounds/rig

Building with Rig

Rig is a Rust library for building LLM-powered applications with a provider-agnostic API. All patterns use the builder pattern and async/await via tokio.

Quick Start

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(openai::GPT_4O)
        .preamble("You are a helpful assistant.")
        .build();

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

Core Patterns

1. Simple Agent

let agent = client.agent(openai::GPT_4O)
    .preamble("System prompt")
    .temperature(0.7)
    .max_tokens(2000)
    .build();

let response = agent.prompt("Your question").await?;

2. Agent with Tools

Define a tool by implementing the Tool trait, then attach it:

let agent = client.agent(openai::GPT_4O)
    .preamble("You can use tools.")
    .tool(MyTool)
    .build();

See references/tools.md for the full Tool trait signature.

3. RAG (Retrieval-Augmented Generation)

let embedding_model = client.embedding_model(openai::TEXT_EMBEDDING_ADA_002);
let index = vector_store.index(embedding_model);

let agent = client.agent(openai::GPT_4O)
    .preamble("Answer using the provided context.")
    .dynamic_context(5, index)  // top-5 similar docs per query
    .build();

See references/rag.md for vector store setup and the Embed derive macro.

4. Streaming

use futures::StreamExt;
use rig::streaming::StreamedAssistantContent;
use rig::agent::prompt_request::streaming::MultiTurnStreamItem;

let mut stream = agent.stream_prompt("Tell me a story").await?;

while let Some(chunk) = stream.next().await {
    match chunk? {
        MultiTurnStreamItem::StreamAssistantItem(
            StreamedAssistantContent::Text(text)
        ) => print!("{}", text.text),
        MultiTurnStreamItem::FinalResponse(resp) => {
            println!("\n{}", resp.response());
        }
        _ => {}
    }
}

5. Structured Extraction

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

#[derive(Deserialize, Serialize, JsonSchema)]
struct Person {
    pub name: Option<String>,
    pub age: Option<u8>,
}

let extractor = client.extractor::<Person>(openai::GPT_4O).build();
let person = extractor.extract("John is 30 years old.").await?;

6. Chat with History

use rig::completion::Chat;

let history = vec![
    Message::from("Hi, I'm Alice."),
    // ...previous messages
];
let response = agent.chat("What's my name?", history).await?;

Agent Builder Methods

| Method | Description | |--------|-------------| | .preamble(str) | Set system prompt | | .context(str) | Add static context document | | .dynamic_context(n, index) | Add RAG with top-n retrieval | | .tool(impl Tool) | Attach a callable tool | | .tools(Vec<Box<dyn ToolDyn>>) | Attach multiple tools | | .temperature(f64) | Set temperature (0.0-1.0) | | .max_tokens(u64) | Set max output tokens | | .additional_params(json!{...}) | Provider-specific params | | .tool_choice(ToolChoice) | Control tool usage | | .build() | Build the agent |

Available Providers

Create a client with ProviderName::Client::from_env() or ProviderName::Client::new("key").

| Provider | Module | Example Model Constant | |----------|--------|----------------------| | OpenAI | openai | GPT_4O, GPT_4O_MINI | | Anthropic | anthropic | CLAUDE_4_OPUS, CLAUDE_4_SONNET | | Cohere | cohere | COMMAND_R_PLUS | | Mistral | mistral | MISTRAL_LARGE | | Gemini | gemini | model string | | Groq | groq | model string | | Ollama | ollama | model string | | DeepSeek | deepseek | model string | | xAI | xai | model string | | Together | together | model string | | Perplexity | perplexity | model string | | OpenRouter | openrouter | model string | | HuggingFace | huggingface | model string | | Azure | azure | deployment string | | Hyperbolic | hyperbolic | model string | | Galadriel | galadriel | model string | | Moonshot | moonshot | model string | | Mira | mira | model string | | Voyage AI | voyageai | embeddings only |

Vector Store Crates

| Backend | Crate | |---------|-------| | In-memory | rig-core (built-in) | | MongoDB | rig-mongodb | | LanceDB | rig-lancedb | | Qdrant | rig-qdrant | | SQLite | rig-sqlite | | Neo4j | rig-neo4j | | Milvus | rig-milvus | | SurrealDB | rig-surrealdb |

Key Rules

• All async code runs on tokio.
• Use WasmCompatSend / WasmCompatSync instead of raw Send / Sync for WASM compatibility.
• Use proper error types with thiserror — never Result<(), String>.
• Avoid .unwrap() — use ? operator.

Further Reference

Detailed API documentation (available when installed via Claude Code skills):

• tools — Tool trait, ToolDefinition, ToolEmbedding, attachment patterns
• rag — Vector stores, Embed derive, EmbeddingsBuilder, search requests
• providers — Provider-specific initialization, model constants, env vars
• patterns — Multi-agent, hooks, streaming details, chaining, extraction

For the full reference, see the Rig examples at rig-core/examples/ or https://docs.rig.rs