Model Provider Clients in Rig

A provider client (or a model provider client) is an entity represented as a struct that can create clients for different types of LLMs or models, depending on the features supported by a given model provider.

Client Architecture (v0.31.0)

In v0.31.0, the provider client system has been significantly redesigned around a generic Client struct and a capability-based type system.

The Client Struct

At the core is rig::client::Client<Ext, H>, a generic struct parameterized by:

• Ext: A provider extension (implementing the Provider trait) that defines provider-specific behavior
• H: An API key type (implementing the ApiKey trait)

use rig::providers::openai;
 
// Create a client from environment variables
let client = openai::Client::from_env();
 
// Or with an explicit API key
let client = openai::Client::new("your-api-key");

Provider Trait

The Provider trait abstracts over provider-specific extensions and specifically handles building out the client with the provider extension. URL construction and custom instantiation are added as provided methods, should you want to implement your own version of this.

pub trait Provider: Sized {
    type Builder: ProviderBuilder;
 
    const VERIFY_PATH: &'static str;
 
    // Required method
    fn build<H>(
        builder: &ClientBuilder<Self::Builder, <Self::Builder as ProviderBuilder>::ApiKey, H>,
    ) -> Result<Self>;
}

Each provider module (e.g., rig::providers::openai, rig::providers::anthropic) implements this trait.

ProviderBuilder Trait

The ProviderBuilder trait provides a builder pattern for configuring providers:

pub trait ProviderBuilder {
    type Output: Provider;
    type ApiKey;
 
    const BASE_URL: &'static str;
 
    // Provided method
    fn finish<H>(
        &self,
        builder: ClientBuilder<Self, Self::ApiKey, H>,
    ) -> Result<ClientBuilder<Self, Self::ApiKey, H>> { ... }
}

Capabilities System

Rig introduces a type-level capabilities system via the Capabilities and Capability traits. This allows compile-time checking of what a provider supports:

pub trait Capabilities<H = Client> {
    type Completion: Capability;
    type Embeddings: Capability;
    type Transcription: Capability;
    type ModelListing: Capability;
    type ImageGeneration: Capability;
    type AudioGeneration: Capability;
}
 
pub trait Capability {
    const CAPABLE: bool;
}

ProviderClient Trait

The ProviderClient trait provides a unified interface for creating clients:

pub trait ProviderClient {
    type Input;
 
    /// Create a client from the process's environment.
    fn from_env() -> Self where Self: Sized;
 
    fn from_val(input: Self::Input) -> Self;
}

Supported Capabilities

Provider clients can support any combination of the following:

Auth Types

v0.31.0 provides typed authentication:

• BearerAuth: API key inserted as a bearer token in request headers
• NeedsApiKey: Marker indicating the provider requires an API key
• Nothing: Marker for providers that don’t need an API key (e.g., local Ollama)

Creating Models

Once you have a client, create models using the corresponding client trait methods:

use rig::client::CompletionClient;
 
let openai = openai::Client::from_env();
 
// Create a completion model
let model = openai.completion_model("gpt-5.2");
 
// Create an embedding model
let embedding_model = openai.embedding_model("text-embedding-3-small");
 
// Create an agent (shorthand for completion_model + AgentBuilder)
let agent = openai.agent("gpt-5.2")
    .preamble("You are a helpful assistant.")
    .build();

How to Write a Custom Provider

To implement a custom provider, you need to:

1. Implement the Provider trait for your extension type
2. Implement CompletionModel for your completion model type
3. Optionally implement EmbeddingModel, TranscriptionModel, etc.
4. Implement the relevant client traits (CompletionClient, EmbeddingsClient, etc.)

For a detailed walkthrough, see the Write Your Own Provider guide.