Struct ClientBuilder 

pub struct ClientBuilder<ModelState = ModelMissing> { /* private fields */ }

Builder for creating a Client.

Set credentials (usually with from_env), then optionally a default model, generation config, retry policy, and shared tools, and finish with build.

Explicit setters win over the environment regardless of chain order relative to from_env(), because from_env() replaces the accumulated config — so call it first.

Examples

use std::time::Duration;

use rai_sdk::{ClientBuilder, GenerationConfig, Model, RetryConfig};

let client = ClientBuilder::new()
    .from_env()
    .model(Model::gpt4o_mini())
    .config(GenerationConfig::new().with_max_tokens(1024))
    .retry_config(RetryConfig::new().with_initial_delay(Duration::from_millis(250)))
    .timeout(60)
    .build()?;

Implementations

impl ClientBuilder<ModelMissing>

pub fn new() -> Self

Start a client builder.

impl<ModelState> ClientBuilder<ModelState>

pub fn from_env(self) -> Self

Load configuration from environment variables.

Reads the API keys, base URLs, timeout, and retry variables documented in config. This replaces any configuration already accumulated on the builder, so call it first and then override individual values.

pub fn openai_key(self, key: impl Into<String>) -> Self

Set the OpenAI API key.

pub fn openai_base_url(self, url: impl Into<String>) -> Self

Set the OpenAI base URL.

pub fn openai_compatible_base_url(self, url: impl Into<String>) -> Self

Point this client at an OpenAI-compatible endpoint.

The URL is the API root serving POST /chat/completions, so it usually ends in /v1 — http://localhost:8000/v1 for vLLM, http://localhost:1234/v1 for LM Studio. Setting it is what makes ProviderKind::OpenAICompatible available; there is no default endpoint and no environment variable, because the endpoint is a property of this client rather than of the process. See Config::openai_compatible_base_url.

Examples

Two endpoints in one process, each with its own client:

use rai_sdk::{ClientBuilder, Model};

let local = ClientBuilder::new()
    .ollama()
    .model(Model::openai_compatible("llama3.1:8b"))
    .build()?;

let cluster = ClientBuilder::new()
    .openai_compatible_base_url("https://vllm.internal.example/v1")
    .openai_compatible_key("shared-secret")
    .model(Model::openai_compatible("Qwen/Qwen2.5-7B-Instruct"))
    .build()?;

pub fn openai_compatible_key(self, key: impl Into<String>) -> Self

Set the bearer token for the OpenAI-compatible endpoint.

Optional. With no key set, requests carry no Authorization header at all, which is what a local runtime expects.

pub fn openai_compatible_capabilities( self, capabilities: EndpointCapabilities, ) -> Self

Declare what the OpenAI-compatible endpoint supports.

Requests needing something it was declared not to support fail with Error::CapabilityUnsupported before any HTTP call, instead of reaching the endpoint and coming back as an opaque bad request.

Examples

use rai_sdk::{ClientBuilder, EndpointCapabilities, Model};

let client = ClientBuilder::new()
    .ollama()
    .openai_compatible_capabilities(
        EndpointCapabilities::default().with_tool_calling(false),
    )
    .model(Model::openai_compatible("gemma3:4b"))
    .build()?;

pub fn ollama(self) -> Self

Point this client at a local Ollama server.

Shorthand for openai_compatible_base_url with OLLAMA_BASE_URL (http://localhost:11434/v1). Pass the URL explicitly for any other host or port.

pub fn anthropic_key(self, key: impl Into<String>) -> Self

Set the Anthropic API key.

pub fn anthropic_base_url(self, url: impl Into<String>) -> Self

Set the Anthropic base URL.

pub fn openrouter_key(self, key: impl Into<String>) -> Self

Set the OpenRouter API key.

pub fn openrouter_base_url(self, url: impl Into<String>) -> Self

Set the OpenRouter base URL.

pub fn openrouter_http_referer(self, referer: impl Into<String>) -> Self

Set the OpenRouter HTTP referer attribution header.

pub fn openrouter_title(self, title: impl Into<String>) -> Self

Set the OpenRouter title attribution header.

pub fn openrouter_categories(self, categories: Vec<String>) -> Self

Set OpenRouter app categories attribution header.

pub fn openrouter_app_url(self, url: impl Into<String>) -> Self

Set the OpenRouter App URL.

pub fn openrouter_app_title(self, title: impl Into<String>) -> Self

Set the OpenRouter App Title.

pub fn timeout(self, seconds: u64) -> Self

Set the request timeout.

pub fn model(self, model: Model) -> ClientBuilder<ModelReady>

Set the default model used by request builders.

This also moves the builder into the model-ready state, so the resulting client can start requests that need only a prompt. Individual requests can still override it with RequestBuilder::model.

pub fn config(self, config: GenerationConfig) -> Self

Set the default generation config used by request builders.

pub fn retry_config(self, config: RetryConfig) -> Self

Set the default retry configuration for all requests.

pub fn no_retry(self) -> Self

Disable retries by default for all requests.

pub fn tool(self, tool: Tool) -> Self

Register a tool that RequestBuilder::generate may auto-execute.

Client-level tools are available to every request. Requests that stream must opt out with RequestBuilder::no_tools, since streaming cannot run a tool loop; see RequestBuilder::stream.

pub fn tools<T>(self, tools: T) -> Self

where T: IntoIterator<Item = Tool>,

Register multiple tools to be auto-executed by generate().

pub fn build(self) -> Result<Client<ModelState>>

Build the client.

Providers with credentials are initialized; providers without them are left unavailable rather than causing a failure, so this succeeds even if only one key is present.

Errors

• Error::InvalidRequest if two registered tools share a name, or a tool’s input schema is invalid.
• An error if a provider’s HTTP client cannot be constructed.

Trait Implementations

impl<ModelState> Debug for ClientBuilder<ModelState>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.