Struct CompletionRequest 

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,
}

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

Fields

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.

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, and each wire judges its own replies with crate::message::require_non_empty. 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 replayable_to(self, issuers: &[Issuer]) -> Result<Self, EncodeError>

This request as a service replaying reasoning issuers issued reads it: assistant messages holding only reasoning none of them opens are left out (Message::replays_to). A wire reads each remaining reasoning part through Sealed::open_for.

Returns a request error when nothing is left to send.

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 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.