Struct ModelRequest 

pub struct ModelRequest {

    pub request_id: RequestId,
    pub purpose: ModelPurpose,
    pub messages: Vec<Message>,
    pub system: Option<String>,
    pub output: OutputSpec,
    pub tools: Vec<ToolSpec>,
    pub tool_choice: ToolChoice,
    pub max_output_tokens: Option<u32>,
    pub temperature: Option<f32>,
    pub reasoning_effort: Option<ReasoningEffort>,
    pub seed: Option<u64>,
    pub stop: Vec<String>,
    pub metadata: RequestMetadata,
    pub timeout: Duration,
    pub cache_hint: CacheHint,
}

One model call (spec §20.1).

Build it with ModelRequest::new and the with_* methods; every field is public so an adapter can read it without ceremony.

Fields

request_id: RequestId

Stable id of the logical call, unchanged across retries and fallbacks (spec §20.7).

purpose: ModelPurpose

Why the call is being made. Decides capability requirements and logging policy; adapters do not branch on it.

messages: Vec<Message>

The conversation, oldest first.

system: Option<String>

Framing instructions, hoisted out of messages because most providers carry them in a dedicated field.

output: OutputSpec

The shape of the answer.

tools: Vec<ToolSpec>

Read-only tools the model may call.

tool_choice: ToolChoice

How free the model is to call them.

max_output_tokens: Option<u32>

Cap on generated tokens.

temperature: Option<f32>

Sampling temperature. None leaves the provider’s default in place.

reasoning_effort: Option<ReasoningEffort>

How much a reasoning model may think. None leaves the provider’s default.

seed: Option<u64>

Sampling seed, for providers that honour one.

stop: Vec<String>

Stop sequences.

metadata: RequestMetadata

Non-personal labels.

timeout: Duration

Deadline for the whole call, including reading a streamed body.

cache_hint: CacheHint

Prompt-caching hint.

Implementations

impl ModelRequest

pub fn new(purpose: ModelPurpose) -> Self

A free-text request for purpose with a fresh RequestId and the DEFAULT_TIMEOUT.

pub fn with_request_id(self, request_id: RequestId) -> Self

Pins the request id, so a retry or a fallback reuses it.

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

Sets the system prompt.

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

Appends one message.

pub fn with_messages(self, messages: Vec<Message>) -> Self

Replaces the conversation.

pub fn with_output(self, output: OutputSpec) -> Self

Sets the expected output shape.

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

Declares the read-only tools.

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

Sets the tool-choice mode.

pub fn with_max_output_tokens(self, tokens: u32) -> Self

Caps generated tokens.

pub fn with_temperature(self, temperature: f32) -> Self

Sets the sampling temperature.

pub fn sampling_for(&self, capabilities: &ProviderCapabilities) -> Sampling

The sampling parameters capabilities accepts, with the rest named as dropped.

pub fn with_reasoning_effort(self, effort: ReasoningEffort) -> Self

Sets how much a reasoning model may think.

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

Sets the sampling seed.

pub fn with_stop(self, stop: Vec<String>) -> Self

Sets the stop sequences.

pub fn with_timeout(self, timeout: Duration) -> Self

Sets the deadline.

pub fn with_cache_hint(self, cache_hint: CacheHint) -> Self

Sets the caching hint.

pub fn with_metadata( self, key: impl Into<String>, value: impl Into<String>, ) -> Result<Self, MetadataError>

Adds a metadata label.

Errors

Returns MetadataError when the value is not label-shaped.

pub fn requirements(&self) -> CapabilityRequirements

The capability requirements this request implies on its own, before the purpose’s own requirements are folded in.

It asks for tools when tools are declared, vision when any message carries an image, document input when any message carries a document, and the structured-output transports the purpose accepts when OutputSpec::Json is requested.

Trait Implementations

impl Clone for ModelRequest

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 ModelRequest

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ModelRequest

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for ModelRequest

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for ModelRequest

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for ModelRequest