Skip to main content

rig_core/completion/
request.rs

1//! Completion requests, normalized responses, and provider model contracts.
2//!
3//! ```
4//! use rig_core::completion::CompletionRequest;
5//!
6//! let request = CompletionRequest::new("Who are you?")
7//!     .preamble("You are a concise assistant.")
8//!     .temperature(0.5);
9//! assert_eq!(request.temperature, Some(0.5));
10//! ```
11
12use super::message::{AssistantContent, DocumentMediaType, Reasoning, ReasoningContent, ToolCall};
13use crate::error::ProviderError;
14use crate::message::ToolChoice;
15use crate::{
16    json_utils,
17    message::{Message, ToolName, UserContent},
18};
19
20use serde::{Deserialize, Serialize};
21use std::collections::HashMap;
22use std::ops::{Add, AddAssign};
23
24#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
25pub struct Document {
26    /// Stable document identifier included in the serialized context block.
27    pub id: String,
28    /// Text content passed to the model as retrieval or static context.
29    pub text: String,
30    /// Additional string metadata rendered before the document text.
31    #[serde(flatten)]
32    pub additional_props: HashMap<String, String>,
33}
34
35impl std::fmt::Display for Document {
36    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
37        write!(
38            f,
39            concat!("<file id: {}>\n", "{}\n", "</file>\n"),
40            self.id,
41            if self.additional_props.is_empty() {
42                self.text.clone()
43            } else {
44                let mut sorted_props = self.additional_props.iter().collect::<Vec<_>>();
45                sorted_props.sort_by(|a, b| a.0.cmp(b.0));
46                let metadata = sorted_props
47                    .iter()
48                    .map(|(k, v)| format!("{k}: {v:?}"))
49                    .collect::<Vec<_>>()
50                    .join(" ");
51                format!("<metadata {} />\n{}", metadata, self.text)
52            }
53        )
54    }
55}
56
57#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
58pub struct ToolDefinition {
59    /// Tool name exposed to the model. It must match the registered tool name.
60    pub name: String,
61    /// Human-readable description sent to the model.
62    pub description: String,
63    /// JSON Schema describing tool arguments.
64    pub parameters: serde_json::Value,
65}
66
67impl ToolDefinition {
68    /// A tool the model may call by `name`, with arguments matching the
69    /// JSON Schema `parameters`.
70    pub fn new(
71        name: ToolName,
72        description: impl Into<String>,
73        parameters: serde_json::Value,
74    ) -> Self {
75        Self {
76            name: name.into(),
77            description: description.into(),
78            parameters,
79        }
80    }
81}
82
83/// Provider-native tool definition.
84///
85/// Stored under `additional_params.tools` and forwarded by providers that support
86/// provider-managed tools.
87#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
88pub struct ProviderToolDefinition {
89    /// Tool type/kind name as expected by the target provider (for example `web_search`).
90    #[serde(rename = "type")]
91    pub kind: String,
92    /// Additional provider-specific configuration for this hosted tool.
93    #[serde(flatten, default, skip_serializing_if = "serde_json::Map::is_empty")]
94    pub config: serde_json::Map<String, serde_json::Value>,
95}
96
97impl ProviderToolDefinition {
98    /// Creates a provider-hosted tool definition by type.
99    pub fn new(kind: impl Into<String>) -> Self {
100        Self {
101            kind: kind.into(),
102            config: serde_json::Map::new(),
103        }
104    }
105
106    /// Adds a provider-specific configuration key/value.
107    pub fn with_config(mut self, key: impl Into<String>, value: serde_json::Value) -> Self {
108        self.config.insert(key.into(), value);
109        self
110    }
111}
112
113/// Normalized generation ending. Unmapped provider values remain in [`Self::Other`].
114/// Failure statuses may accompany parseable output; callers must decide whether
115/// such output is usable rather than treating every response as successful.
116#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
117#[serde(rename_all = "snake_case")]
118pub enum FinishReason {
119    /// Natural end of the response.
120    Stop,
121    /// The response hit the output-token limit.
122    Length,
123    /// The model stopped to call one or more tools.
124    ToolCalls,
125    /// The provider filtered the content.
126    ContentFilter,
127    /// A provider-specific reason outside the normalized vocabulary, carried
128    /// verbatim in the provider's own wire spelling.
129    Other(String),
130}
131
132impl FinishReason {
133    /// Changes [`Self::Stop`] to [`Self::ToolCalls`] when output contains a tool
134    /// call. All other reasons remain unchanged. Response builders and streaming
135    /// aggregation apply this reconciliation.
136    pub fn reconcile_with_output(self, has_tool_call: bool) -> Self {
137        if has_tool_call && matches!(self, Self::Stop) {
138            Self::ToolCalls
139        } else {
140            self
141        }
142    }
143
144    /// Returns whether the reason is [`Self::Length`] or [`Self::ContentFilter`].
145    /// These reasons permit answerless turns without treating absent content as
146    /// a malformed response. Unknown reasons are not classified as truncation.
147    pub fn truncated_output(&self) -> bool {
148        matches!(self, Self::Length | Self::ContentFilter)
149    }
150
151    /// Formats an answerless-turn diagnostic with budget or filtering advice
152    /// for known truncation reasons, and a generic explanation otherwise.
153    pub fn no_answer_message(&self) -> String {
154        let remedy = match self {
155            Self::Length => {
156                "the turn ran out of output budget before producing one — \
157                 raise max_tokens for this request"
158            }
159            Self::ContentFilter => {
160                "the provider filtered the response — the content, not the \
161                 budget, is what it objected to"
162            }
163            _ => "the turn ended before producing one",
164        };
165        format!(
166            "the model produced no answer and stopped with \
167             finish_reason={self:?}; {remedy}"
168        )
169    }
170}
171
172/// Assistant content and normalized completion metadata. The choice may be
173/// empty, including for truncated or filtered turns. Provider-specific data is
174/// available through [`Self::raw`] without retaining a concrete model type.
175///
176/// A response goes straight back into the conversation as the assistant
177/// turn: `history.push(response.into())`.
178#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
179#[serde(from = "CompletionResponseRepr")]
180pub struct CompletionResponse {
181    /// Assistant content returned by the provider, possibly empty.
182    pub choice: Vec<AssistantContent>,
183    /// Tokens used during prompting and responding
184    pub usage: Usage,
185    /// Provider-issued assistant message ID suitable for replay in
186    /// [`Message::Assistant`]. Response-wide IDs belong in [`Self::response_id`].
187    #[serde(default)]
188    pub message_id: Option<String>,
189    /// Provider-issued response ID for telemetry and diagnostics.
190    /// Must not be replayed as an assistant message ID.
191    #[serde(default)]
192    pub response_id: Option<String>,
193    /// Request identifier from HTTP headers or SDK metadata, not the body's
194    /// message or response ID. `None` when the provider reports none.
195    #[serde(default, skip_serializing_if = "Option::is_none")]
196    pub provider_request_id: Option<String>,
197    /// Reported finish reason, reconciled by the setters with tool-call output.
198    /// Read through [`Self::finish_reason`].
199    #[serde(default)]
200    finish_reason: Option<FinishReason>,
201    /// Stable descriptor name of the provider that produced this response, for
202    /// example `"openai"`. Always populated, including for responses derived
203    /// from a stream that ended before its terminal record.
204    pub provider: String,
205    /// Provider-reported model identifier for the response.
206    ///
207    /// This is the model named by the wire response, not the model that was
208    /// requested; it is `None` when the provider reports no identifier.
209    #[serde(default)]
210    pub model: Option<String>,
211    /// Provider response document for typed inspection through deserialization.
212    /// Parsed wire types may omit unmodeled fields. This data does not override
213    /// normalized fields; callers constructing responses must supply it.
214    pub raw: serde_json::Value,
215}
216
217/// Distinct message, response, and transport identifiers for one model call.
218/// Unreported identifiers remain `None`.
219#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
220pub struct ResponseIdentity {
221    /// Provider-issued assistant message ID suitable for replay.
222    #[serde(default, skip_serializing_if = "Option::is_none")]
223    pub message_id: Option<String>,
224    /// Response-wide ID, never replayed as a message ID.
225    #[serde(default, skip_serializing_if = "Option::is_none")]
226    pub response_id: Option<String>,
227    /// Transport request ID from HTTP headers or SDK metadata.
228    #[serde(default, skip_serializing_if = "Option::is_none")]
229    pub provider_request_id: Option<String>,
230}
231
232impl CompletionResponse {
233    /// Create a response from its required parts; optional metadata starts
234    /// unset. `raw` is the provider's own document for this response,
235    /// serialized; see [`Self::raw`].
236    pub fn new(
237        choice: Vec<AssistantContent>,
238        usage: Usage,
239        provider: impl Into<String>,
240        raw: serde_json::Value,
241    ) -> Self {
242        Self {
243            choice,
244            usage,
245            message_id: None,
246            response_id: None,
247            provider_request_id: None,
248            finish_reason: None,
249            provider: provider.into(),
250            model: None,
251            raw,
252        }
253    }
254
255    /// Why the model stopped generating, when the provider reported it.
256    pub fn finish_reason(&self) -> Option<FinishReason> {
257        self.finish_reason.clone()
258    }
259
260    /// This response's identity metadata as one [`ResponseIdentity`] carrier.
261    pub fn identity(&self) -> ResponseIdentity {
262        ResponseIdentity {
263            message_id: self.message_id.clone(),
264            response_id: self.response_id.clone(),
265            provider_request_id: self.provider_request_id.clone(),
266        }
267    }
268
269    /// Attach the normalized finish reason, reconciled against the choice via
270    /// [`FinishReason::reconcile_with_output`].
271    pub fn with_finish_reason(self, finish_reason: FinishReason) -> Self {
272        self.with_optional_finish_reason(Some(finish_reason))
273    }
274
275    /// The text parts of [`Self::choice`], concatenated in order.
276    pub fn text(&self) -> String {
277        self.choice
278            .iter()
279            .filter_map(|part| match part {
280                AssistantContent::Text(text) => Some(text.text.as_str()),
281                _ => None,
282            })
283            .collect()
284    }
285
286    /// The reasoning text of [`Self::choice`] (text and summaries), concatenated
287    /// in order. Encrypted and redacted reasoning has no text.
288    pub fn reasoning(&self) -> String {
289        self.choice
290            .iter()
291            .filter_map(|part| match part {
292                AssistantContent::Reasoning(reasoning) => {
293                    reasoning.open(reasoning.issuer()).map(reasoning_text)
294                }
295                _ => None,
296            })
297            .collect()
298    }
299
300    /// The assistant turn to append to the conversation: [`Self::choice`] in
301    /// order under the provider's message id, or `None` for an empty choice.
302    pub fn message(&self) -> Option<Message> {
303        if self.choice.is_empty() {
304            return None;
305        }
306        Some(Message::Assistant {
307            id: self.message_id.clone(),
308            content: self.choice.clone(),
309        })
310    }
311
312    /// The tool calls in [`Self::choice`], in order.
313    pub fn tool_calls(&self) -> impl Iterator<Item = &ToolCall> {
314        self.choice.iter().filter_map(|part| match part {
315            AssistantContent::ToolCall(call) => Some(call),
316            _ => None,
317        })
318    }
319
320    /// Sets or clears the finish reason, reconciling a present reason with the choice.
321    pub fn with_optional_finish_reason(mut self, finish_reason: Option<FinishReason>) -> Self {
322        let has_tool_call = self
323            .choice
324            .iter()
325            .any(|content| matches!(content, AssistantContent::ToolCall(_)));
326        self.finish_reason =
327            finish_reason.map(|reason| reason.reconcile_with_output(has_tool_call));
328        self
329    }
330}
331
332/// The text and summaries of one reasoning part, concatenated in order.
333pub(crate) fn reasoning_text(reasoning: &Reasoning) -> String {
334    reasoning
335        .content
336        .iter()
337        .filter_map(|content| match content {
338            ReasoningContent::Text { text, .. } => Some(text.as_str()),
339            ReasoningContent::Summary(summary) => Some(summary.as_str()),
340            ReasoningContent::Encrypted(_) | ReasoningContent::Redacted { .. } => None,
341        })
342        .collect()
343}
344
345/// Deserialization shape routed through builders for finish-reason reconciliation
346/// and empty-identifier normalization.
347#[derive(Deserialize)]
348struct CompletionResponseRepr {
349    choice: Vec<AssistantContent>,
350    usage: Usage,
351    #[serde(default)]
352    message_id: Option<String>,
353    #[serde(default)]
354    response_id: Option<String>,
355    #[serde(default)]
356    provider_request_id: Option<String>,
357    #[serde(default)]
358    finish_reason: Option<FinishReason>,
359    provider: String,
360    #[serde(default)]
361    model: Option<String>,
362    raw: serde_json::Value,
363}
364
365impl From<CompletionResponseRepr> for CompletionResponse {
366    fn from(repr: CompletionResponseRepr) -> Self {
367        let CompletionResponseRepr {
368            choice,
369            usage,
370            message_id,
371            response_id,
372            provider_request_id,
373            finish_reason,
374            provider,
375            model,
376            raw,
377        } = repr;
378        use crate::provider_response::reported;
379        let mut response =
380            Self::new(choice, usage, provider, raw).with_optional_finish_reason(finish_reason);
381        response.message_id = reported(message_id);
382        response.response_id = reported(response_id);
383        response.provider_request_id = reported(provider_request_id);
384        response.model = reported(model);
385        response
386    }
387}
388
389/// The token usage a provider reported for one completion.
390///
391/// Every provider mapping keeps one contract, so the counters read the same
392/// way on every provider:
393///
394/// - `cached_input_tokens + cache_creation_input_tokens <= input_tokens`:
395///   input counts every prompt token, cache reads and writes included.
396/// - `reasoning_tokens <= output_tokens`: output counts every generated
397///   token, reasoning included.
398/// - `total_tokens == input_tokens + output_tokens`, absent unless both are
399///   reported.
400///
401/// A counter the provider did not send is `None`; a reported zero is
402/// `Some(0)`. Serialized as the same keys, absent when `None`.
403#[derive(Debug, Default, PartialEq, Eq, Clone, Copy, Serialize, Deserialize)]
404pub struct Usage {
405    /// Every input token of the request: uncached, read from a cache,
406    /// written to a cache, and any prompt a provider's hosted tools added.
407    #[serde(default, skip_serializing_if = "Option::is_none")]
408    pub input_tokens: Option<u64>,
409    /// Every output token, reasoning included.
410    #[serde(default, skip_serializing_if = "Option::is_none")]
411    pub output_tokens: Option<u64>,
412    /// `input_tokens + output_tokens`; absent unless both are reported.
413    #[serde(default, skip_serializing_if = "Option::is_none")]
414    pub total_tokens: Option<u64>,
415    /// The part of `input_tokens` read from a provider-managed cache.
416    #[serde(default, skip_serializing_if = "Option::is_none")]
417    pub cached_input_tokens: Option<u64>,
418    /// The part of `input_tokens` written to a provider-managed cache.
419    #[serde(default, skip_serializing_if = "Option::is_none")]
420    pub cache_creation_input_tokens: Option<u64>,
421    /// The part of `input_tokens` a provider's hosted tools added to the prompt.
422    #[serde(default, skip_serializing_if = "Option::is_none")]
423    pub tool_use_prompt_tokens: Option<u64>,
424    /// The part of `output_tokens` spent on internal reasoning ("thinking",
425    /// "thoughts").
426    #[serde(default, skip_serializing_if = "Option::is_none")]
427    pub reasoning_tokens: Option<u64>,
428}
429
430impl Usage {
431    /// Whether the provider reported any counter at all.
432    pub fn is_reported(&self) -> bool {
433        *self != Self::default()
434    }
435}
436
437/// Sum two counters where an unreported side does not turn a reported one
438/// into "unreported".
439fn add_counter(lhs: Option<u64>, rhs: Option<u64>) -> Option<u64> {
440    match (lhs, rhs) {
441        (None, None) => None,
442        (lhs, rhs) => Some(lhs.unwrap_or(0) + rhs.unwrap_or(0)),
443    }
444}
445
446impl Add for Usage {
447    type Output = Self;
448
449    fn add(mut self, other: Self) -> Self::Output {
450        self += other;
451        self
452    }
453}
454
455impl AddAssign for Usage {
456    fn add_assign(&mut self, other: Self) {
457        self.input_tokens = add_counter(self.input_tokens, other.input_tokens);
458        self.output_tokens = add_counter(self.output_tokens, other.output_tokens);
459        self.total_tokens = add_counter(self.total_tokens, other.total_tokens);
460        self.cached_input_tokens = add_counter(self.cached_input_tokens, other.cached_input_tokens);
461        self.cache_creation_input_tokens = add_counter(
462            self.cache_creation_input_tokens,
463            other.cache_creation_input_tokens,
464        );
465        self.tool_use_prompt_tokens =
466            add_counter(self.tool_use_prompt_tokens, other.tool_use_prompt_tokens);
467        self.reasoning_tokens = add_counter(self.reasoning_tokens, other.reasoning_tokens);
468    }
469}
470
471/// Model capabilities used by runtimes when preparing requests.
472/// Defaults are conservative; construct through [`Self::new`] and setters.
473#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
474pub struct ProviderCapabilities {
475    /// Whether native structured output can remain enabled with tool calls
476    /// without suppressing them. Defaults to `false`.
477    pub composes_native_output_with_tools: bool,
478    /// Whether the model answers a forced tool choice (`Required` or
479    /// `Specific`) with an error. Rig then does not force the output tool
480    /// of its own structured-output flow (the extractor). Defaults to `false`.
481    #[serde(default, skip_serializing_if = "crate::json_utils::is_false")]
482    pub rejects_forced_tool_choice: bool,
483}
484
485impl ProviderCapabilities {
486    /// Create the conservative capability set used by default.
487    pub const fn new() -> Self {
488        Self {
489            composes_native_output_with_tools: false,
490            rejects_forced_tool_choice: false,
491        }
492    }
493
494    /// Declare whether native structured output composes with tool calls.
495    pub const fn with_native_output_tool_composition(mut self, supported: bool) -> Self {
496        self.composes_native_output_with_tools = supported;
497        self
498    }
499
500    /// Declare whether the model rejects a forced tool choice.
501    pub const fn with_forced_tool_choice_rejected(mut self, rejected: bool) -> Self {
502        self.rejects_forced_tool_choice = rejected;
503        self
504    }
505}
506
507/// Struct representing a general completion request that can be sent to a completion model provider.
508#[derive(Debug, Clone, Serialize, Deserialize)]
509pub struct CompletionRequest {
510    /// Optional model override for this request.
511    pub model: Option<String>,
512    /// The chat history to be sent to the completion model provider.
513    /// The very last message is the prompt.
514    ///
515    /// It must hold at least one message, and every user and assistant
516    /// message must carry content. The field is public, so this is a rule
517    /// rather than a type guarantee: [`Self::validate_message_content`]
518    /// checks it at the request boundary.
519    pub chat_history: Vec<Message>,
520    /// The documents to be sent to the completion model provider
521    pub documents: Vec<Document>,
522    /// The tools to be sent to the completion model provider
523    pub tools: Vec<ToolDefinition>,
524    /// The temperature to be sent to the completion model provider
525    pub temperature: Option<f64>,
526    /// The max tokens to be sent to the completion model provider
527    pub max_tokens: Option<u64>,
528    /// Whether tools are required to be used by the model provider or not before providing a response.
529    pub tool_choice: Option<ToolChoice>,
530    /// Additional provider-specific parameters to be sent to the completion model provider
531    pub additional_params: Option<serde_json::Value>,
532    /// Optional JSON Schema for structured output. When set, providers that support
533    /// native structured outputs will constrain the model's response to match this schema.
534    pub output_schema: Option<schemars::Schema>,
535    /// Opt-in for sensitive request, response, and tool-content telemetry.
536    /// Defaults to `false` and is excluded from serialization. Enabling it can
537    /// expose prompts, context, tool results, and model output in span attributes
538    /// and increase telemetry storage costs. Requires explicit caller consent.
539    /// Agent drivers record normalized content; direct provider coverage varies,
540    /// especially for streams consumed after the provider returns.
541    #[serde(skip)]
542    pub record_telemetry_content: bool,
543}
544
545impl CompletionRequest {
546    /// The system instructions of this request: the content of the leading
547    /// [`Message::System`] in `chat_history`, which is where
548    /// [`Self::preamble`] places it.
549    pub fn system_instructions(&self) -> Option<&str> {
550        match self.chat_history.first() {
551            Some(Message::System { content }) => Some(content.as_str()),
552            _ => None,
553        }
554    }
555
556    /// Reject a request with no messages, a user or assistant message with no
557    /// content, or a tool result with no content blocks. The error is
558    /// [`ProviderError::Request`] and names the role and index of the first
559    /// offending message.
560    ///
561    /// Every wire rejects an empty turn, so this turns a remote 400 into a
562    /// local error. It checks the request direction only: a provider may
563    /// return empty assistant content, and each wire judges its own replies
564    /// with [`crate::message::require_non_empty`]. `System` content is a
565    /// `String` and is not checked. A tool result holding one empty text
566    /// block is not empty.
567    ///
568    /// [`Model::call`](crate::driver::Model::call),
569    /// [`Model::stream`](crate::driver::Model::stream) and their `_observed`
570    /// twins run it before encoding, so it covers
571    /// [`DynModel`](crate::DynModel), every model the bus serves and the
572    /// agent runtimes built on them. The OpenAI Responses websocket session
573    /// sends without the driver and runs it on each send. Code that encodes
574    /// a request some other way should call it first.
575    pub fn validate_message_content(&self) -> Result<(), ProviderError> {
576        if self.chat_history.is_empty() {
577            return Err(ProviderError::request(
578                "request has an empty chat history; providers require at least one message",
579            ));
580        }
581
582        let empty_message = |role: &str, index: usize| {
583            ProviderError::request(format!(
584                "{role} message at index {index} has no content; \
585                 providers reject empty content blocks"
586            ))
587        };
588
589        for (index, message) in self.chat_history.iter().enumerate() {
590            match message {
591                Message::System { .. } => {}
592                Message::Assistant { content, .. } => {
593                    if content.is_empty() {
594                        return Err(empty_message("assistant", index));
595                    }
596                }
597                Message::User { content } => {
598                    if content.is_empty() {
599                        return Err(empty_message("user", index));
600                    }
601                    for (position, item) in content.iter().enumerate() {
602                        // Exhaustive, so a new variant with its own block
603                        // list decides here whether its emptiness is checked.
604                        match item {
605                            UserContent::ToolResult(result) if result.content.is_empty() => {
606                                let name = &result.name;
607                                return Err(ProviderError::request(format!(
608                                    "tool result for `{name}` at index {position} of the user \
609                                     message at index {index} has no content; providers \
610                                     reject empty content blocks"
611                                )));
612                            }
613                            UserContent::ToolResult(_)
614                            | UserContent::Text(_)
615                            | UserContent::Image(_)
616                            | UserContent::Audio(_)
617                            | UserContent::Video(_)
618                            | UserContent::Document(_) => {}
619                        }
620                    }
621                }
622            }
623        }
624
625        Ok(())
626    }
627
628    /// This request as a service replaying reasoning `issuers` issued reads
629    /// it: assistant messages holding only reasoning none of them opens are
630    /// left out ([`Message::replays_to`]). A wire reads each remaining
631    /// reasoning part through [`Sealed::open_for`](crate::message::Sealed::open_for).
632    ///
633    /// Returns a request error when nothing is left to send.
634    pub fn replayable_to(
635        mut self,
636        issuers: &[crate::message::Issuer],
637    ) -> Result<Self, crate::error::EncodeError> {
638        self.chat_history
639            .retain(|message| message.replays_to(issuers));
640        if self.chat_history.is_empty() {
641            return Err(crate::error::EncodeError::request(
642                "no message is left once reasoning another service issued is left out",
643            ));
644        }
645        Ok(self)
646    }
647
648    /// Extracts a name from the output schema's `"title"` field, falling back to `"response_schema"`.
649    /// Useful for providers that require a name alongside the JSON Schema (e.g., OpenAI).
650    pub fn output_schema_name(&self) -> Option<String> {
651        self.output_schema.as_ref().map(|schema| {
652            schema
653                .as_object()
654                .and_then(|o| o.get("title"))
655                .and_then(|v| v.as_str())
656                .unwrap_or("response_schema")
657                .to_string()
658        })
659    }
660
661    /// Returns documents normalized into a message (if any).
662    /// Most providers do not accept documents directly as input, so it needs to convert into a
663    /// `Message` so that it can be incorporated into `chat_history`.
664    pub fn normalized_documents(&self) -> Option<Message> {
665        Self::normalized_documents_from(&self.documents)
666    }
667
668    fn normalized_documents_from(documents: &[Document]) -> Option<Message> {
669        if documents.is_empty() {
670            return None;
671        }
672
673        let content = documents
674            .iter()
675            .map(|doc| UserContent::document(doc.to_string(), Some(DocumentMediaType::TXT)))
676            .collect();
677
678        Some(Message::User { content })
679    }
680
681    pub(crate) fn chat_history_with_documents(&self) -> Vec<Message> {
682        let mut chat_history = self.chat_history.clone();
683        if let Some(documents) = self.normalized_documents() {
684            insert_after_leading_system(&mut chat_history, documents);
685        }
686        chat_history
687    }
688}
689
690/// Insert `message` at the first non-system position so document context lands
691/// after any leading system messages; telemetry and the sent request must
692/// agree on this placement.
693fn insert_after_leading_system(chat_history: &mut Vec<Message>, message: Message) {
694    let insert_at = chat_history
695        .iter()
696        .position(|message| !matches!(message, Message::System { .. }))
697        .unwrap_or(chat_history.len());
698    chat_history.insert(insert_at, message);
699}
700
701fn merge_provider_tools_into_additional_params(
702    additional_params: Option<serde_json::Value>,
703    provider_tools: Vec<ProviderToolDefinition>,
704) -> Option<serde_json::Value> {
705    if provider_tools.is_empty() {
706        return additional_params;
707    }
708
709    let mut provider_tools_json = provider_tools
710        .into_iter()
711        .map(|ProviderToolDefinition { kind, mut config }| {
712            // Force the provider tool type from the strongly-typed field.
713            config.insert("type".to_string(), serde_json::Value::String(kind));
714            serde_json::Value::Object(config)
715        })
716        .collect::<Vec<_>>();
717
718    let mut params_map = match additional_params {
719        Some(serde_json::Value::Object(map)) => map,
720        Some(serde_json::Value::Bool(stream)) => {
721            let mut map = serde_json::Map::new();
722            map.insert("stream".to_string(), serde_json::Value::Bool(stream));
723            map
724        }
725        _ => serde_json::Map::new(),
726    };
727
728    let mut merged_tools = match params_map.remove("tools") {
729        Some(serde_json::Value::Array(existing)) => existing,
730        _ => Vec::new(),
731    };
732    merged_tools.append(&mut provider_tools_json);
733    params_map.insert("tools".to_string(), serde_json::Value::Array(merged_tools));
734    Some(serde_json::Value::Object(params_map))
735}
736
737impl CompletionRequest {
738    /// A request whose conversation is the one user message `prompt`, with
739    /// no preamble, documents or tools. The setters below add to it and
740    /// check nothing; [`Self::validate_message_content`] checks the content
741    /// when the request is sent.
742    ///
743    /// Each setter changes the request's public fields as it is called, so
744    /// order matters where two setters touch the same field: a second
745    /// [`Self::preamble`] adds a second system message, and
746    /// [`Self::additional_params`] with a `tools` key (or `None`) replaces
747    /// provider tools added before it. Set `additional_params` first.
748    ///
749    /// ```
750    /// use rig_core::completion::CompletionRequest;
751    ///
752    /// let request = CompletionRequest::new("Who are you?")
753    ///     .preamble("You are a concise assistant.")
754    ///     .temperature(0.5);
755    /// assert_eq!(request.chat_history.len(), 2);
756    /// assert_eq!(request.temperature, Some(0.5));
757    /// ```
758    pub fn new(prompt: impl Into<Message>) -> Self {
759        Self::conversation(vec![prompt.into()])
760    }
761
762    /// A request for `chat_history` as given, with nothing else set.
763    fn conversation(chat_history: Vec<Message>) -> Self {
764        Self {
765            model: None,
766            chat_history,
767            documents: Vec::new(),
768            tools: Vec::new(),
769            temperature: None,
770            max_tokens: None,
771            tool_choice: None,
772            additional_params: None,
773            output_schema: None,
774            record_telemetry_content: false,
775        }
776    }
777
778    /// Put `preamble` first in the conversation, as a [`Message::System`],
779    /// ahead of any system message already there.
780    pub fn preamble(mut self, preamble: impl Into<String>) -> Self {
781        self.chat_history
782            .insert(0, Message::system(preamble.into()));
783        self
784    }
785
786    /// Override the model for this request.
787    pub fn model<S: Into<String>>(mut self, model: impl Into<Option<S>>) -> Self {
788        self.model = model.into().map(Into::into);
789        self.warn_if_shadowed("model", self.model.is_some());
790        self
791    }
792
793    /// Add `message` to the conversation, before the prompt (its last
794    /// message).
795    pub fn message(self, message: Message) -> Self {
796        self.messages([message])
797    }
798
799    /// Add `messages` to the conversation in order, before the prompt (its
800    /// last message).
801    pub fn messages(mut self, messages: impl IntoIterator<Item = Message>) -> Self {
802        let prompt = self.chat_history.pop();
803        self.chat_history.extend(messages);
804        self.chat_history.extend(prompt);
805        self
806    }
807
808    /// Add a document.
809    pub fn document(mut self, document: Document) -> Self {
810        self.documents.push(document);
811        self
812    }
813
814    /// Add documents in order.
815    pub fn documents(mut self, documents: impl IntoIterator<Item = Document>) -> Self {
816        self.documents.extend(documents);
817        self
818    }
819
820    /// Add a tool.
821    pub fn tool(self, tool: ToolDefinition) -> Self {
822        self.tools(vec![tool])
823    }
824
825    /// Add tools in order.
826    pub fn tools(mut self, tools: Vec<ToolDefinition>) -> Self {
827        let first = self.tools.is_empty();
828        self.tools.extend(tools);
829        self.warn_if_shadowed("tools", first && !self.tools.is_empty());
830        self
831    }
832
833    /// Add a provider-hosted tool: appended to `additional_params.tools`,
834    /// so a later [`Self::additional_params`] with a `tools` key replaces
835    /// it.
836    pub fn provider_tool(self, tool: ProviderToolDefinition) -> Self {
837        self.provider_tools(vec![tool])
838    }
839
840    /// Add provider-hosted tools in order: appended to
841    /// `additional_params.tools`.
842    pub fn provider_tools(mut self, tools: Vec<ProviderToolDefinition>) -> Self {
843        self.additional_params =
844            merge_provider_tools_into_additional_params(self.additional_params.take(), tools);
845        self
846    }
847
848    /// Merge provider-specific parameters into the request's, key by key;
849    /// `None` clears them, provider tools included. Provider conversion determines precedence over typed fields,
850    /// and a key that overrides a typed field this request sets is logged.
851    pub fn additional_params(
852        mut self,
853        additional_params: impl Into<Option<serde_json::Value>>,
854    ) -> Self {
855        let additional_params = additional_params.into();
856        for key in shadowed_typed_fields(
857            additional_params.as_ref(),
858            &[
859                ("temperature", self.temperature.is_some()),
860                ("max_tokens", self.max_tokens.is_some()),
861                ("tool_choice", self.tool_choice.is_some()),
862                ("model", self.model.is_some()),
863                ("tools", !self.tools.is_empty()),
864                ("response_format", self.output_schema.is_some()),
865            ],
866        ) {
867            warn_shadowed(key);
868        }
869        self.additional_params =
870            json_utils::merge_params(self.additional_params.take(), additional_params);
871        self
872    }
873
874    /// Set, or with `None` clear, the temperature.
875    pub fn temperature(mut self, temperature: impl Into<Option<f64>>) -> Self {
876        self.temperature = temperature.into();
877        self.warn_if_shadowed("temperature", self.temperature.is_some());
878        self
879    }
880
881    /// Set, or with `None` clear, the output-token limit. Provider-specific
882    /// defaults and requirements apply.
883    pub fn max_tokens(mut self, max_tokens: impl Into<Option<u64>>) -> Self {
884        self.max_tokens = max_tokens.into();
885        self.warn_if_shadowed("max_tokens", self.max_tokens.is_some());
886        self
887    }
888
889    /// Set the tool-selection policy.
890    pub fn tool_choice(mut self, tool_choice: ToolChoice) -> Self {
891        self.tool_choice = Some(tool_choice);
892        self.warn_if_shadowed("tool_choice", true);
893        self
894    }
895
896    /// Set, or with `None` clear, a native structured-output schema for
897    /// providers that support one. The returned content is not
898    /// deserialized.
899    pub fn output_schema(mut self, schema: impl Into<Option<schemars::Schema>>) -> Self {
900        self.output_schema = schema.into();
901        self.warn_if_shadowed("response_format", self.output_schema.is_some());
902        self
903    }
904
905    /// Opt in to sensitive content telemetry, off by default. See
906    /// [`Self::record_telemetry_content`] for what that exposes.
907    pub fn record_content_telemetry(mut self, enabled: bool) -> Self {
908        self.record_telemetry_content = enabled;
909        self
910    }
911
912    /// The input messages telemetry records: the conversation with the
913    /// documents inserted after any leading system messages.
914    pub fn messages_for_telemetry(&self) -> Vec<Message> {
915        self.chat_history_with_documents()
916    }
917
918    /// Log a typed field `key` that `additional_params` already overrides.
919    fn warn_if_shadowed(&self, key: &'static str, set: bool) {
920        if !shadowed_typed_fields(self.additional_params.as_ref(), &[(key, set)]).is_empty() {
921            warn_shadowed(key);
922        }
923    }
924}
925
926fn warn_shadowed(key: &str) {
927    if matches!(key, "tools" | "response_format") {
928        tracing::warn!(
929            key,
930            "additional_params also carries `{key}`; the provider decides how it combines with the typed field"
931        );
932    } else {
933        tracing::warn!(
934            key,
935            "additional_params overrides the typed `{key}` field set on the same request"
936        );
937    }
938}
939
940impl From<&str> for CompletionRequest {
941    fn from(prompt: &str) -> Self {
942        Self::new(prompt)
943    }
944}
945
946impl From<String> for CompletionRequest {
947    fn from(prompt: String) -> Self {
948        Self::new(prompt)
949    }
950}
951
952impl From<Message> for CompletionRequest {
953    fn from(prompt: Message) -> Self {
954        Self::new(prompt)
955    }
956}
957
958/// The conversation as given, ending with the prompt. An empty one fails
959/// [`CompletionRequest::validate_message_content`].
960impl From<Vec<Message>> for CompletionRequest {
961    fn from(chat_history: Vec<Message>) -> Self {
962        Self::conversation(chat_history)
963    }
964}
965
966/// The passthrough keys that will override a typed field the caller also set.
967/// The override itself is the documented precedence (see
968/// [`CompletionRequest::additional_params`]); naming the collisions
969/// makes an accidental one visible instead of silent.
970pub(crate) fn shadowed_typed_fields<'a>(
971    additional_params: Option<&serde_json::Value>,
972    typed: &[(&'a str, bool)],
973) -> Vec<&'a str> {
974    let Some(serde_json::Value::Object(params)) = additional_params else {
975        return Vec::new();
976    };
977    typed
978        .iter()
979        .filter(|(key, set)| *set && params.contains_key(*key))
980        .map(|(key, _)| *key)
981        .collect()
982}
983
984#[cfg(test)]
985mod tests;
986
987#[cfg(test)]
988mod response_identity_tests;
989
990#[cfg(test)]
991mod plain_value_tests;