Struct CompletionRequestBuilder 

pub struct CompletionRequestBuilder<M>
where
    M: CompletionModel,
{ /* private fields */ }

Builder struct for constructing a completion request.

Example usage:

use rig_core::{
    client::CompletionClient,
    providers::openai::{Client, self},
    completion::{CompletionModel, CompletionRequestBuilder},
};

let openai = Client::new("your-openai-api-key")?;
let model = openai.completion_model(openai::GPT_5_2);

// Create the completion request and execute it separately
let request = CompletionRequestBuilder::new(model.clone(), "Who are you?".to_string())
    .preamble("You are Marvin from the Hitchhiker's Guide to the Galaxy.".to_string())
    .temperature(0.5)
    .build();

let response = model.completion(request).await?;

Alternatively, you can execute the completion request directly from the builder:

use rig_core::{
    client::CompletionClient,
    providers::openai::{Client, self},
    completion::CompletionRequestBuilder,
};

let openai = Client::new("your-openai-api-key")?;
let model = openai.completion_model(openai::GPT_5_2);

// Create the completion request and execute it directly
let response = CompletionRequestBuilder::new(model, "Who are you?".to_string())
    .preamble("You are Marvin from the Hitchhiker's Guide to the Galaxy.".to_string())
    .temperature(0.5)
    .send()
    .await?;

Note: It is usually unnecessary to create a completion request builder directly. Instead, use the CompletionModel::completion_request method.

Implementations

impl<M> CompletionRequestBuilder<M>

where M: CompletionModel,

pub fn new(model: M, prompt: impl Into<Message>) -> CompletionRequestBuilder<M>

pub fn preamble(self, preamble: String) -> CompletionRequestBuilder<M>

Sets the preamble for the completion request.

pub fn model(self, model: impl Into<String>) -> CompletionRequestBuilder<M>

Overrides the model used for this request.

pub fn model_opt(self, model: Option<String>) -> CompletionRequestBuilder<M>

Overrides the model used for this request.

pub fn without_preamble(self) -> CompletionRequestBuilder<M>

pub fn message(self, message: Message) -> CompletionRequestBuilder<M>

Adds a message to the chat history for the completion request.

pub fn messages( self, messages: impl IntoIterator<Item = Message>, ) -> CompletionRequestBuilder<M>

Adds a list of messages to the chat history for the completion request.

pub fn document(self, document: Document) -> CompletionRequestBuilder<M>

Adds a document to the completion request.

pub fn documents( self, documents: impl IntoIterator<Item = Document>, ) -> CompletionRequestBuilder<M>

Adds a list of documents to the completion request.

pub fn tool(self, tool: ToolDefinition) -> CompletionRequestBuilder<M>

Adds a tool to the completion request.

pub fn tools(self, tools: Vec<ToolDefinition>) -> CompletionRequestBuilder<M>

Adds a list of tools to the completion request.

pub fn provider_tool( self, tool: ProviderToolDefinition, ) -> CompletionRequestBuilder<M>

Adds a provider-hosted tool to the completion request.

pub fn provider_tools( self, tools: Vec<ProviderToolDefinition>, ) -> CompletionRequestBuilder<M>

Adds provider-hosted tools to the completion request.

pub fn additional_params( self, additional_params: Value, ) -> CompletionRequestBuilder<M>

Adds additional parameters to the completion request. This can be used to set additional provider-specific parameters. For example, Cohere’s completion models accept a connectors parameter that can be used to specify the data connectors used by Cohere when executing the completion (see examples/cohere_connectors.rs).

pub fn additional_params_opt( self, additional_params: Option<Value>, ) -> CompletionRequestBuilder<M>

Sets the additional parameters for the completion request. This can be used to set additional provider-specific parameters. For example, Cohere’s completion models accept a connectors parameter that can be used to specify the data connectors used by Cohere when executing the completion (see examples/cohere_connectors.rs).

pub fn temperature(self, temperature: f64) -> CompletionRequestBuilder<M>

Sets the temperature for the completion request.

pub fn temperature_opt( self, temperature: Option<f64>, ) -> CompletionRequestBuilder<M>

Sets the temperature for the completion request.

pub fn max_tokens(self, max_tokens: u64) -> CompletionRequestBuilder<M>

Sets the max tokens for the completion request. Note: This is required if using Anthropic

pub fn max_tokens_opt( self, max_tokens: Option<u64>, ) -> CompletionRequestBuilder<M>

Sets the max tokens for the completion request. Note: This is required if using Anthropic

pub fn tool_choice(self, tool_choice: ToolChoice) -> CompletionRequestBuilder<M>

Sets the thing.

pub fn output_schema(self, schema: Schema) -> CompletionRequestBuilder<M>

Sets the output schema for structured output. When set, providers that support native structured outputs will constrain the model’s response to match this schema. NOTE: For direct type conversion, you may want to use Agent::prompt_typed() - using this method with Agent::prompt() will still output a String at the end, it’ll just be compatible with whatever type you want to use here. This method is primarily an escape hatch for agents being used as tools to still be able to leverage structured outputs.

pub fn output_schema_opt( self, schema: Option<Schema>, ) -> CompletionRequestBuilder<M>

Sets the output schema for structured output from an optional value. NOTE: For direct type conversion, you may want to use Agent::prompt_typed() - using this method with Agent::prompt() will still output a String at the end, it’ll just be compatible with whatever type you want to use here. This method is primarily an escape hatch for agents being used as tools to still be able to leverage structured outputs.

pub fn record_content_telemetry( self, enabled: bool, ) -> CompletionRequestBuilder<M>

Opt in or out of recording sensitive request, response, and tool content on GenAI telemetry spans for this request.

Defaults to false. Enabling this can expose prompts, retrieved context, tool results, model responses, and other sensitive or high-cardinality data through OpenTelemetry span attributes, which can increase observability backend storage and query costs. Only enable it when content telemetry is acceptable for this request. Structural metadata and token usage remain available when this is disabled.

This low-level builder only stores the opt-in on the built request. It does not guarantee portable input/output message fields for direct model calls; exact coverage is provider- and surface-dependent. Agent APIs own normalized input/output recording and provide the consistent surface.

pub fn messages_for_telemetry(&self) -> Vec<Message>

Returns the normalized input messages used by runtime telemetry.

pub fn build(self) -> CompletionRequest

Builds the completion request.

pub async fn send( self, ) -> Result<CompletionResponse<<M as CompletionModel>::Response>, CompletionError>

Sends the completion request to the completion model provider and returns the completion response.

pub async fn stream<'a>( self, ) -> Result<StreamingCompletionResponse<<M as CompletionModel>::StreamingResponse>, CompletionError>

where <M as CompletionModel>::StreamingResponse: 'a, CompletionRequestBuilder<M>: 'a,

Stream the completion request