Struct CompletionRequest 

#[non_exhaustive]
pub struct CompletionRequest {

    pub model: Option<String>,
    pub chat_history: Vec<Message>,
    pub documents: Vec<Document>,
    pub tools: Vec<ToolDefinition>,
    pub temperature: Option<f64>,
    pub max_tokens: Option<u64>,
    pub tool_choice: Option<ToolChoice>,
    pub additional_params: Option<Value>,
    pub output_schema: Option<Schema>,
    pub record_telemetry_content: bool,
    pub accept_unknown_finish_reasons: bool,
    pub options: GenerationOptions,
    pub provider_options: ProviderOptions,
}

Struct representing a general completion request that can be sent to a completion model provider.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

model: Option<String>

Optional model override for this request.

chat_history: Vec<Message>

The chat history to be sent to the completion model provider. The very last message is the prompt.

It must hold at least one message, and every user and assistant message must carry content. The field is public, so this is a rule rather than a type guarantee: Self::validate_message_content checks it at the request boundary.

documents: Vec<Document>

The documents to be sent to the completion model provider

tools: Vec<ToolDefinition>

The tools to be sent to the completion model provider

temperature: Option<f64>

The temperature to be sent to the completion model provider

max_tokens: Option<u64>

The max tokens to be sent to the completion model provider

tool_choice: Option<ToolChoice>

Whether tools are required to be used by the model provider or not before providing a response.

additional_params: Option<Value>

Additional provider-specific parameters to be sent to the completion model provider

output_schema: Option<Schema>

Optional JSON Schema for structured output. When set, providers that support native structured outputs will constrain the model’s response to match this schema.

record_telemetry_content: bool

Opt-in for sensitive request, response, and tool-content telemetry. Defaults to false and is excluded from serialization. Enabling it can expose prompts, context, tool results, and model output in span attributes and increase telemetry storage costs. Requires explicit caller consent. Agent drivers record normalized content; direct provider coverage varies, especially for streams consumed after the provider returns.

accept_unknown_finish_reasons: bool

Whether a finish reason outside the normalized vocabulary (FinishReason::Other) ends the turn as a normal stop instead of a failure. Defaults to false. The response carries the choice, so its CompletionResponse::stop, the runtimes and history replay agree. Other also holds genuine failures, such as a malformed tool call or a recitation block, so with this set the tool calls of such a reply run. FinishReason::ContentFilter still fails the turn.

options: GenerationOptions

Portable generation options. Precedence, lowest first: the mapped options, then Self::provider_options, then additional_params.

provider_options: ProviderOptions

Typed per-provider options. The wire reads only the entry of its own provider, above the mapped options and below additional_params.

Implementations

impl CompletionRequest

pub fn system_instructions(&self) -> Option<&str>

The system instructions of this request: the content of the leading Message::System in chat_history, which is where Self::preamble places it.

pub fn validate_message_content(&self) -> Result<(), ProviderError>

Reject a request with no messages, a user or assistant message with no content, or a tool result with no content blocks. The error is ProviderError::Request and names the role and index of the first offending message.

Every wire rejects an empty turn, so this turns a remote 400 into a local error. It checks the request direction only: a provider may return empty assistant content, which the reply keeps and the runtime judges. System content is a String and is not checked. A tool result holding one empty text block is not empty.

Model::call, Model::stream and their _observed twins run it before encoding, so it covers DynModel, every model the bus serves and the agent runtimes built on them. The OpenAI Responses websocket session sends without the driver and runs it on each send. Code that encodes a request some other way should call it first.

pub fn output_schema_name(&self) -> Option<String>

Extracts a name from the output schema’s "title" field, falling back to "response_schema". Useful for providers that require a name alongside the JSON Schema (e.g., OpenAI).

pub fn normalized_documents(&self) -> Option<Message>

Returns documents normalized into a message (if any). Most providers do not accept documents directly as input, so it needs to convert into a Message so that it can be incorporated into chat_history.

impl CompletionRequest

pub fn new(prompt: impl Into<Message>) -> Self

A request whose conversation is the one user message prompt, with no preamble, documents or tools. The setters below add to it and check nothing; Self::validate_message_content checks the content when the request is sent.

Each setter changes the request’s public fields as it is called, so order matters where two setters touch the same field: a second Self::preamble adds a second system message, and Self::additional_params with a tools key (or None) replaces provider tools added before it. Set additional_params first.

use rig_core::completion::CompletionRequest;

let request = CompletionRequest::new("Who are you?")
    .preamble("You are a concise assistant.")
    .temperature(0.5);
assert_eq!(request.chat_history.len(), 2);
assert_eq!(request.temperature, Some(0.5));

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

Put preamble first in the conversation, as a Message::System, ahead of any system message already there.

pub fn model<S: Into<String>>(self, model: impl Into<Option<S>>) -> Self

Override the model for this request.

pub fn message(self, message: Message) -> Self

Add message to the conversation, before the prompt (its last message).

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

Add messages to the conversation in order, before the prompt (its last message).

pub fn document(self, document: Document) -> Self

Add a document.

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

Add documents in order.

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

Add a tool.

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

Add tools in order.

pub fn provider_tool(self, tool: ProviderToolDefinition) -> Self

Add a provider-hosted tool: appended to additional_params.tools, so a later Self::additional_params with a tools key replaces it.

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

Add provider-hosted tools in order: appended to additional_params.tools.

pub fn additional_params( self, additional_params: impl Into<Option<Value>>, ) -> Self

Merge provider-specific parameters into the request’s, key by key; None clears them, provider tools included. Provider conversion determines precedence over typed fields, and a key that overrides a typed field this request sets is logged.

pub fn temperature(self, temperature: impl Into<Option<f64>>) -> Self

Set, or with None clear, the temperature.

pub fn max_tokens(self, max_tokens: impl Into<Option<u64>>) -> Self

Set, or with None clear, the output-token limit. Provider-specific defaults and requirements apply.

pub fn tool_choice(self, tool_choice: ToolChoice) -> Self

Set the tool-selection policy.

pub fn output_schema(self, schema: impl Into<Option<Schema>>) -> Self

Set, or with None clear, a native structured-output schema for providers that support one. The returned content is not deserialized.

pub fn record_content_telemetry(self, enabled: bool) -> Self

Opt in to sensitive content telemetry, off by default. See Self::record_telemetry_content for what that exposes.

pub fn accept_unknown_finish_reasons(self, accept: bool) -> Self

Accept, or with false refuse, finish reasons outside the normalized vocabulary as a normal stop. See Self::accept_unknown_finish_reasons for what that lets through.

pub fn options(self, options: GenerationOptions) -> Self

Replace the portable generation options with options, a reusable value. Calls apply in order: this replaces every field, so a shortcut such as Self::seed called before it is lost, and one called after it sets its one field on top.

use rig_core::completion::{CompletionRequest, Effort, GenerationOptions};

let shared = GenerationOptions::new().reasoning(Effort::High).seed(1);
let request = CompletionRequest::new("hi").seed(7).options(shared.clone()).seed(2);
assert_eq!(request.options, shared.seed(2));

pub fn reasoning(self, reasoning: impl Into<Reasoning>) -> Self

Set the reasoning level or budget in Self::options, as GenerationOptions::reasoning does, keeping its other fields. See Self::options for the order of calls.

pub fn cache(self, cache: CacheRetention) -> Self

Set the cache retention in Self::options, as GenerationOptions::cache does, keeping its other fields. See Self::options for the order of calls.

pub fn service_tier(self, tier: ServiceTier) -> Self

Set the service tier in Self::options, as GenerationOptions::service_tier does, keeping its other fields. See Self::options for the order of calls.

pub fn verbosity(self, verbosity: Verbosity) -> Self

Set the answer verbosity in Self::options, as GenerationOptions::verbosity does, keeping its other fields. See Self::options for the order of calls.

pub fn parallel_tool_calls(self, parallel: bool) -> Self

Set whether the model may call several tools in one turn in Self::options, as GenerationOptions::parallel_tool_calls does, keeping its other fields. See Self::options for the order of calls.

pub fn top_p(self, top_p: f64) -> Self

Set the nucleus sampling probability mass in Self::options, as GenerationOptions::top_p does, keeping its other fields. See Self::options for the order of calls.

pub fn seed(self, seed: u64) -> Self

Set the sampling seed in Self::options, as GenerationOptions::seed does, keeping its other fields. See Self::options for the order of calls.

pub fn stop<S: Into<String>>(self, stop: impl IntoIterator<Item = S>) -> Self

Set the stop sequences in Self::options, as GenerationOptions::stop does, keeping its other fields. See Self::options for the order of calls.

pub fn on_unsupported(self, policy: OnUnsupported) -> Self

Set what happens to an option the wire or model cannot honour in Self::options, as GenerationOptions::on_unsupported does, keeping its other fields. See Self::options for the order of calls.

pub fn provider_options(self, options: ProviderOptions) -> Self

Replace the typed per-provider options.

Calls apply in order: this replaces every entry, so an entry set by an earlier Self::provider_option is lost, and a later Self::provider_option replaces its provider’s entry on top.

pub fn provider_option<O: ExtensionOptions>(self, options: O) -> Self

Store options as the entry of their provider (ExtensionOptions::Ext), replacing that provider’s entry and keeping every other, as ProviderOptions::set does. Options that do not serialize fail the request’s encode.

The entry is always stored under O::Ext’s key, the built-in provider the options type belongs to. A third-party provider whose extension reuses a built-in options type (say OpenAiOptions for an OpenAI-compatible gateway) must store them with ProviderOptions::with::<P> instead, or its wire never reads them.

use rig_core::completion::{CompletionRequest, ProviderOptions};
use rig_core::providers::openrouter::extension::{
    OpenRouterExt, OpenRouterOptions, ProviderPreferences,
};

let request = CompletionRequest::new("hi").provider_option(
    OpenRouterOptions::new().provider(ProviderPreferences::new().allow_fallbacks(false)),
);
assert!(request.provider_options.contains::<OpenRouterExt>());

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

The input messages telemetry records: the conversation with the documents inserted after any leading system messages.

Trait Implementations

impl Clone for CompletionRequest

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CompletionRequest

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for CompletionRequest

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<&str> for CompletionRequest

fn from(prompt: &str) -> Self

Converts to this type from the input type.

impl From<Message> for CompletionRequest

fn from(prompt: Message) -> Self

Converts to this type from the input type.

impl From<String> for CompletionRequest

fn from(prompt: String) -> Self

Converts to this type from the input type.

impl From<Vec<Message>> for CompletionRequest

The conversation as given, ending with the prompt. An empty one fails CompletionRequest::validate_message_content.

fn from(chat_history: Vec<Message>) -> Self

Converts to this type from the input type.

impl Serialize for CompletionRequest

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.