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::{
13    AssistantContent, AssistantMessage, CallId, DocumentMediaType, Origin, StopReason, ToolCall,
14};
15use super::options::{
16    CacheRetention, GenerationOptions, OnUnsupported, Reasoning, ServiceTier, Verbosity,
17};
18use super::provider_options::{ExtensionOptions, ProviderExtension, ProviderOptions, ReplyExtras};
19use crate::error::ProviderError;
20use crate::json_utils::remove_preserving_order;
21use crate::message::ToolChoice;
22use crate::{
23    json_utils,
24    message::{Message, ToolName, UserContent},
25};
26
27use serde::{Deserialize, Serialize};
28use std::collections::HashMap;
29use std::ops::{Add, AddAssign};
30use std::sync::Arc;
31
32/// A document sent with a request as context, rendered before the chat history.
33#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
34pub struct Document {
35    /// Stable document identifier included in the serialized context block.
36    pub id: String,
37    /// Text content passed to the model as retrieval or static context.
38    pub text: String,
39    /// Additional string metadata rendered before the document text.
40    #[serde(flatten)]
41    pub additional_props: HashMap<String, String>,
42}
43
44impl std::fmt::Display for Document {
45    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
46        write!(
47            f,
48            concat!("<file id: {}>\n", "{}\n", "</file>\n"),
49            self.id,
50            if self.additional_props.is_empty() {
51                self.text.clone()
52            } else {
53                let mut sorted_props = self.additional_props.iter().collect::<Vec<_>>();
54                sorted_props.sort_by(|a, b| a.0.cmp(b.0));
55                let metadata = sorted_props
56                    .iter()
57                    .map(|(k, v)| format!("{k}: {v:?}"))
58                    .collect::<Vec<_>>()
59                    .join(" ");
60                format!("<metadata {} />\n{}", metadata, self.text)
61            }
62        )
63    }
64}
65
66/// A tool the model may call: its name, description and argument schema,
67/// sent to the model, and what the tool does to the world
68/// ([`ToolAnnotations`]), which stays with the host.
69#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
70pub struct ToolDefinition {
71    /// Tool name exposed to the model. It must match the registered tool name.
72    pub name: ToolName,
73    /// Human-readable description sent to the model.
74    pub description: String,
75    /// JSON Schema describing tool arguments.
76    pub parameters: serde_json::Value,
77    /// What calling the tool does to the world, for the host's policies
78    /// (approval, plan mode, running calls side by side). Never sent to
79    /// the model; written only when something is stated.
80    #[serde(default, skip_serializing_if = "ToolAnnotations::is_empty")]
81    pub annotations: ToolAnnotations,
82}
83
84impl ToolDefinition {
85    /// A tool the model may call by `name`, with arguments matching the
86    /// JSON Schema `parameters`, and no annotations.
87    pub fn new(
88        name: ToolName,
89        description: impl Into<String>,
90        parameters: serde_json::Value,
91    ) -> Self {
92        Self {
93            name,
94            description: description.into(),
95            parameters,
96            annotations: ToolAnnotations::default(),
97        }
98    }
99
100    /// The same definition with `annotations`.
101    pub fn with_annotations(mut self, annotations: ToolAnnotations) -> Self {
102        self.annotations = annotations;
103        self
104    }
105}
106
107/// What calling a tool does to the world, as the Model Context Protocol's
108/// tool annotations state it, and spelled as they are on its wire
109/// (`readOnlyHint`, …), so an MCP tool's annotations read straight into
110/// one. Each is a hint a tool's author gives: a host's policies read them
111/// (approval, plan mode, which calls run side by side), never trusting a
112/// tool it does not trust for them. A hint left unset takes the protocol's
113/// default, which the accessors apply: not read-only, destructive, not
114/// idempotent, open world.
115///
116/// ```
117/// use rig_core::completion::ToolAnnotations;
118///
119/// let read = ToolAnnotations::default().with_read_only(true).with_open_world(false);
120/// assert!(read.read_only() && !read.destructive() && !read.open_world());
121/// let unknown = ToolAnnotations::default();
122/// assert!(!unknown.read_only() && unknown.destructive() && unknown.open_world());
123/// let mcp: ToolAnnotations = serde_json::from_value(serde_json::json!({"readOnlyHint": true}))?;
124/// assert!(mcp.read_only());
125/// # Ok::<(), serde_json::Error>(())
126/// ```
127#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, Deserialize, Serialize)]
128#[serde(rename_all = "camelCase")]
129pub struct ToolAnnotations {
130    /// A human-readable title for the tool.
131    #[serde(default, skip_serializing_if = "Option::is_none")]
132    pub title: Option<String>,
133    /// Whether the tool changes nothing in its environment.
134    #[serde(default, skip_serializing_if = "Option::is_none")]
135    pub read_only_hint: Option<bool>,
136    /// Whether a tool that changes things may also destroy or overwrite
137    /// what was there (rather than only add). Meaningless for a read-only
138    /// tool.
139    #[serde(default, skip_serializing_if = "Option::is_none")]
140    pub destructive_hint: Option<bool>,
141    /// Whether calling the tool again with the same arguments has no
142    /// further effect. Meaningless for a read-only tool.
143    #[serde(default, skip_serializing_if = "Option::is_none")]
144    pub idempotent_hint: Option<bool>,
145    /// Whether the tool reaches beyond a closed set of things, such as the
146    /// web or a shell; `false` for one that works on a known store, such
147    /// as the project's files.
148    #[serde(default, skip_serializing_if = "Option::is_none")]
149    pub open_world_hint: Option<bool>,
150}
151
152impl ToolAnnotations {
153    /// Whether nothing is stated.
154    pub fn is_empty(&self) -> bool {
155        *self == Self::default()
156    }
157
158    /// Whether the tool changes nothing: the hint, else `false`.
159    pub fn read_only(&self) -> bool {
160        self.read_only_hint.unwrap_or(false)
161    }
162
163    /// Whether the tool may destroy or overwrite something: never for a
164    /// read-only tool, else the hint, else `true`.
165    pub fn destructive(&self) -> bool {
166        !self.read_only() && self.destructive_hint.unwrap_or(true)
167    }
168
169    /// Whether repeating a call has no further effect: always for a
170    /// read-only tool, else the hint, else `false`.
171    pub fn idempotent(&self) -> bool {
172        self.read_only() || self.idempotent_hint.unwrap_or(false)
173    }
174
175    /// Whether the tool reaches an open world: the hint, else `true`.
176    pub fn open_world(&self) -> bool {
177        self.open_world_hint.unwrap_or(true)
178    }
179
180    /// The same annotations with a title.
181    pub fn with_title(mut self, title: impl Into<String>) -> Self {
182        self.title = Some(title.into());
183        self
184    }
185
186    /// The same annotations stating whether the tool is read-only.
187    pub fn with_read_only(mut self, read_only: bool) -> Self {
188        self.read_only_hint = Some(read_only);
189        self
190    }
191
192    /// The same annotations stating whether the tool is destructive.
193    pub fn with_destructive(mut self, destructive: bool) -> Self {
194        self.destructive_hint = Some(destructive);
195        self
196    }
197
198    /// The same annotations stating whether the tool is idempotent.
199    pub fn with_idempotent(mut self, idempotent: bool) -> Self {
200        self.idempotent_hint = Some(idempotent);
201        self
202    }
203
204    /// The same annotations stating whether the tool reaches an open world.
205    pub fn with_open_world(mut self, open_world: bool) -> Self {
206        self.open_world_hint = Some(open_world);
207        self
208    }
209}
210
211/// Provider-native tool definition.
212///
213/// Stored under `additional_params.tools` and forwarded by providers that support
214/// provider-managed tools.
215#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
216pub struct ProviderToolDefinition {
217    /// Tool type/kind name as expected by the target provider (for example `web_search`).
218    #[serde(rename = "type")]
219    pub kind: String,
220    /// Additional provider-specific configuration for this hosted tool.
221    #[serde(flatten, default, skip_serializing_if = "serde_json::Map::is_empty")]
222    pub config: serde_json::Map<String, serde_json::Value>,
223}
224
225impl ProviderToolDefinition {
226    /// Creates a provider-hosted tool definition by type.
227    pub fn new(kind: impl Into<String>) -> Self {
228        Self {
229            kind: kind.into(),
230            config: serde_json::Map::new(),
231        }
232    }
233
234    /// Adds a provider-specific configuration key/value.
235    pub fn with_config(mut self, key: impl Into<String>, value: serde_json::Value) -> Self {
236        self.config.insert(key.into(), value);
237        self
238    }
239}
240
241/// Normalized generation ending. Unmapped provider values remain in [`Self::Other`].
242/// Failure statuses may accompany parseable output; callers must decide whether
243/// such output is usable rather than treating every response as successful.
244#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
245#[serde(rename_all = "snake_case")]
246#[non_exhaustive]
247pub enum FinishReason {
248    /// Natural end of the response.
249    Stop,
250    /// The response hit the output-token limit.
251    Length,
252    /// The model stopped to call one or more tools.
253    ToolCalls,
254    /// The provider filtered the content.
255    ContentFilter,
256    /// A provider-specific reason outside the normalized vocabulary, carried
257    /// verbatim in the provider's own wire spelling.
258    Other(String),
259}
260
261impl FinishReason {
262    /// Changes [`Self::Stop`] to [`Self::ToolCalls`] when output contains a tool
263    /// call. All other reasons remain unchanged. Response builders and streaming
264    /// aggregation apply this reconciliation.
265    pub fn reconcile_with_output(self, has_tool_call: bool) -> Self {
266        if has_tool_call && matches!(self, Self::Stop) {
267            Self::ToolCalls
268        } else {
269            self
270        }
271    }
272
273    /// Returns whether the reason is [`Self::Length`] or [`Self::ContentFilter`].
274    /// These reasons permit answerless turns without treating absent content as
275    /// a malformed response. Unknown reasons are not classified as truncation.
276    pub fn truncated_output(&self) -> bool {
277        matches!(self, Self::Length | Self::ContentFilter)
278    }
279
280    /// Formats an answerless-turn diagnostic with budget or filtering advice
281    /// for known truncation reasons, and a generic explanation otherwise.
282    pub fn no_answer_message(&self) -> String {
283        let remedy = match self {
284            Self::Length => {
285                "the turn ran out of output budget before producing one — \
286                 raise max_tokens for this request"
287            }
288            Self::ContentFilter => {
289                "the provider filtered the response — the content, not the \
290                 budget, is what it objected to"
291            }
292            _ => "the turn ended before producing one",
293        };
294        format!(
295            "the model produced no answer and stopped with \
296             finish_reason={self:?}; {remedy}"
297        )
298    }
299}
300
301/// Assistant content and normalized completion metadata. The choice may be
302/// empty, including for truncated or filtered turns. Provider-specific data is
303/// available through [`Self::raw`] without retaining a concrete model type.
304///
305/// A response goes straight back into the conversation as the assistant
306/// turn: `history.extend(response.message())`.
307#[non_exhaustive]
308#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
309#[serde(from = "CompletionResponseRepr")]
310pub struct CompletionResponse {
311    /// Assistant content returned by the provider, one block per provider
312    /// output item, in provider order. Possibly empty.
313    pub choice: Vec<AssistantContent>,
314    /// Tokens used during prompting and responding
315    pub usage: Usage,
316    /// The wire, provider and requested model that produced the response,
317    /// with the model and response id the provider reported.
318    pub origin: Origin,
319    /// The provider's report that the turn failed, such as a refusal's
320    /// explanation. The turn's message then ends in [`StopReason::Error`]
321    /// and is never replayed.
322    #[serde(default, skip_serializing_if = "Option::is_none")]
323    pub error: Option<String>,
324    /// Why the reply stopped before the provider ended it, when the caller
325    /// stopped reading: the turn's message then ends in
326    /// [`StopReason::Aborted`] and is replayed as its text alone.
327    #[serde(default, skip_serializing_if = "Option::is_none")]
328    pub aborted: Option<String>,
329    /// Request identifier from HTTP headers or SDK metadata, not the body's
330    /// response ID. `None` when the provider reports none.
331    #[serde(default, skip_serializing_if = "Option::is_none")]
332    pub provider_request_id: Option<String>,
333    /// Reported finish reason, reconciled by the setters with tool-call output.
334    /// Read through [`Self::finish_reason`].
335    #[serde(default)]
336    finish_reason: Option<FinishReason>,
337    /// Whether [`FinishReason::Other`] ends the turn as a normal stop. Read
338    /// through [`Self::accepts_unknown_finish_reasons`].
339    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
340    accepts_unknown_finish_reasons: bool,
341    /// The calls the provider ended the reply in the middle of. Read
342    /// through [`Self::unfinished_calls`].
343    #[serde(default, skip_serializing_if = "Vec::is_empty")]
344    unfinished_calls: Vec<CallId>,
345    /// Provider response document for typed inspection through deserialization.
346    /// Parsed wire types may omit unmodeled fields. This data does not override
347    /// normalized fields; callers constructing responses must supply it.
348    pub raw: serde_json::Value,
349}
350
351/// Distinct response and transport identifiers for one model call.
352/// Unreported identifiers remain `None`.
353#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
354pub struct ResponseIdentity {
355    /// Response-wide ID.
356    #[serde(default, skip_serializing_if = "Option::is_none")]
357    pub response_id: Option<String>,
358    /// Transport request ID from HTTP headers or SDK metadata.
359    #[serde(default, skip_serializing_if = "Option::is_none")]
360    pub provider_request_id: Option<String>,
361}
362
363impl CompletionResponse {
364    /// Create a response from its required parts; optional metadata starts
365    /// unset. `raw` is the provider's own document for this response,
366    /// serialized; see [`Self::raw`].
367    pub fn new(
368        choice: Vec<AssistantContent>,
369        usage: Usage,
370        origin: Origin,
371        raw: serde_json::Value,
372    ) -> Self {
373        Self {
374            choice,
375            usage,
376            origin,
377            error: None,
378            aborted: None,
379            provider_request_id: None,
380            finish_reason: None,
381            accepts_unknown_finish_reasons: false,
382            unfinished_calls: Vec::new(),
383            raw,
384        }
385    }
386
387    /// The provider descriptor name (`"openai"`).
388    pub fn provider(&self) -> &str {
389        &self.origin.provider
390    }
391
392    /// `P`'s typed view of [`Self::raw`]. `None` unless `P` is the provider
393    /// that produced the reply.
394    ///
395    /// # Errors
396    ///
397    /// The inner result fails when `raw` does not hold `P`'s extras.
398    pub fn extras<P: ProviderExtension>(&self) -> Option<Result<P::Extras, serde_json::Error>> {
399        (self.origin.provider == P::PROVIDER)
400            .then(|| P::Extras::from_reply(&self.origin.api, &self.raw))
401    }
402
403    /// `P`'s typed view of [`Self::raw`], or the empty view (every field
404    /// `None`) when it cannot be read: when another provider produced the
405    /// reply, or when `raw` does not hold `P`'s extras. A decode failure is
406    /// logged at `debug`; use [`Self::extras`] to tell the cases apart.
407    pub fn extras_lossy<P: ProviderExtension>(&self) -> P::Extras
408    where
409        P::Extras: Default,
410    {
411        match self.extras::<P>() {
412            Some(Ok(extras)) => extras,
413            Some(Err(error)) => {
414                tracing::debug!(
415                    provider = P::PROVIDER,
416                    api = %self.origin.api,
417                    %error,
418                    "reply extras did not decode; reading them as empty"
419                );
420                P::Extras::default()
421            }
422            None => P::Extras::default(),
423        }
424    }
425
426    /// The model the provider reported, when it reported one.
427    pub fn model(&self) -> Option<&str> {
428        self.origin.response_model.as_deref()
429    }
430
431    /// The provider's response id, when it sent one.
432    pub fn response_id(&self) -> Option<&str> {
433        self.origin.response_id.as_deref()
434    }
435
436    /// Why the model stopped generating, when the provider reported it.
437    pub fn finish_reason(&self) -> Option<FinishReason> {
438        self.finish_reason.clone()
439    }
440
441    /// Whether a finish reason outside the normalized vocabulary ends the
442    /// turn as a normal stop, as the request asked
443    /// ([`CompletionRequest::accept_unknown_finish_reasons`]).
444    ///
445    /// [`CompletionRequest::accept_unknown_finish_reasons`]: field@CompletionRequest::accept_unknown_finish_reasons
446    pub fn accepts_unknown_finish_reasons(&self) -> bool {
447        self.accepts_unknown_finish_reasons
448    }
449
450    /// The tool calls the provider ended the reply in the middle of (their
451    /// arguments as far as they came), in the order they opened, such as a
452    /// call cut by [`FinishReason::Length`]. Empty when every call in
453    /// [`Self::choice`] was finished. The calls to answer as cut off are
454    /// [`cut_off_calls`](Self::cut_off_calls).
455    pub fn unfinished_calls(&self) -> impl Iterator<Item = &ToolCall> {
456        self.tool_calls()
457            .filter(|call| self.unfinished_calls.contains(&call.id))
458    }
459
460    /// The calls a host answers as cut off and never runs: the
461    /// [`unfinished_calls`](Self::unfinished_calls) of a reply whose finish
462    /// reason [truncated its output](FinishReason::truncated_output), the
463    /// output limit or a content filter. Empty for any other finish reason
464    /// or none, even with unfinished calls, such as a reply the caller
465    /// stopped reading, whose calls are its own to settle. Today only a
466    /// streamed reply marks calls unfinished, so a reply that came whole
467    /// has none.
468    pub fn cut_off_calls(&self) -> impl Iterator<Item = &ToolCall> {
469        let truncated = self
470            .finish_reason
471            .as_ref()
472            .is_some_and(FinishReason::truncated_output);
473        self.unfinished_calls().filter(move |_| truncated)
474    }
475
476    /// The same response, `calls` (ids of calls in [`Self::choice`]) being
477    /// the ones the provider ended the reply in the middle of.
478    pub fn with_unfinished_calls(mut self, calls: impl IntoIterator<Item = CallId>) -> Self {
479        self.unfinished_calls = calls.into_iter().collect();
480        self
481    }
482
483    /// Accept, or refuse, [`FinishReason::Other`] as a normal stop in
484    /// [`Self::stop`]. Filtered content and a reported failure still fail.
485    pub fn accept_unknown_finish_reasons(mut self, accept: bool) -> Self {
486        self.accepts_unknown_finish_reasons = accept;
487        self
488    }
489
490    /// How the turn ended, for history. It fails closed: only a natural
491    /// stop, the token limit and a stop to call tools are successes. A
492    /// reported failure, filtered content and any finish reason outside
493    /// that set are [`StopReason::Error`], unless the response accepts
494    /// unknown reasons ([`Self::accepts_unknown_finish_reasons`]), which then
495    /// stop like [`FinishReason::Stop`]. A reply the caller stopped reading
496    /// is [`StopReason::Aborted`].
497    pub fn stop(&self) -> StopReason {
498        if let Some(error) = &self.error {
499            return StopReason::Error(error.clone());
500        }
501        if let Some(reason) = &self.aborted {
502            return StopReason::Aborted(reason.clone());
503        }
504        match &self.finish_reason {
505            Some(FinishReason::Length) => StopReason::Length,
506            Some(FinishReason::ToolCalls) => StopReason::ToolUse,
507            Some(FinishReason::ContentFilter) => {
508                StopReason::Error("Provider finish_reason: content_filter".to_owned())
509            }
510            Some(FinishReason::Other(reason)) if !self.accepts_unknown_finish_reasons => {
511                StopReason::Error(format!("Provider finish_reason: {reason}"))
512            }
513            Some(FinishReason::Stop | FinishReason::Other(_)) | None
514                if self.tool_calls().next().is_some() =>
515            {
516                StopReason::ToolUse
517            }
518            Some(FinishReason::Stop | FinishReason::Other(_)) | None => StopReason::Stop,
519        }
520    }
521
522    /// This response's identity metadata as one [`ResponseIdentity`] carrier.
523    pub fn identity(&self) -> ResponseIdentity {
524        ResponseIdentity {
525            response_id: self.origin.response_id.clone(),
526            provider_request_id: self.provider_request_id.clone(),
527        }
528    }
529
530    /// Attach the normalized finish reason, reconciled against the choice via
531    /// [`FinishReason::reconcile_with_output`].
532    pub fn with_finish_reason(self, finish_reason: FinishReason) -> Self {
533        self.with_optional_finish_reason(Some(finish_reason))
534    }
535
536    /// The text parts of [`Self::choice`], concatenated in order.
537    pub fn text(&self) -> String {
538        AssistantContent::concat_text(&self.choice)
539    }
540
541    /// The reasoning text of [`Self::choice`], concatenated in order.
542    /// Redacted reasoning has no text.
543    pub fn reasoning(&self) -> String {
544        self.choice
545            .iter()
546            .filter_map(|part| match part {
547                AssistantContent::Reasoning(reasoning) => Some(reasoning.text.as_str()),
548                _ => None,
549            })
550            .collect()
551    }
552
553    /// The assistant turn to append to the conversation: [`Self::choice`] in
554    /// order with its origin and stop, or `None` for an
555    /// empty choice.
556    pub fn message(&self) -> Option<Message> {
557        if self.choice.is_empty() {
558            return None;
559        }
560        Some(Message::Assistant(AssistantMessage {
561            content: self.choice.clone(),
562            ..self.head()
563        }))
564    }
565
566    /// The turn this response began, holding `content`, for a runtime that
567    /// cut the reply short and answers its calls itself (an agent rolling a
568    /// turn back over an invalid call). It keeps the origin, and stops to
569    /// call tools, since the runtime answers them. A block keeps its provider
570    /// item only when this response holds the same block with it. A response
571    /// the provider did not end, or one the consumer has not wholly taken,
572    /// holds no provider item, so its turn replays canonically.
573    pub fn continued(&self, content: Vec<AssistantContent>) -> AssistantMessage {
574        let content = content
575            .into_iter()
576            .map(|block| {
577                if self.choice.contains(&block) {
578                    block
579                } else {
580                    crate::operation::completion::canonical(block)
581                }
582            })
583            .collect();
584        AssistantMessage::rolled_back(Some(self.origin.clone()), content)
585    }
586
587    /// The turn's origin and stop with no content, for a
588    /// runtime that carries the content separately.
589    pub fn head(&self) -> AssistantMessage {
590        AssistantMessage {
591            content: Vec::new(),
592            origin: Some(self.origin.clone()),
593            stop: Some(self.stop()),
594        }
595    }
596
597    /// The tool calls in [`Self::choice`], in order.
598    pub fn tool_calls(&self) -> impl Iterator<Item = &ToolCall> {
599        self.choice
600            .iter()
601            .filter_map(AssistantContent::as_tool_call)
602    }
603
604    /// Sets or clears the finish reason, reconciling a present reason with the choice.
605    pub fn with_optional_finish_reason(mut self, finish_reason: Option<FinishReason>) -> Self {
606        let has_tool_call = self.tool_calls().next().is_some();
607        self.finish_reason =
608            finish_reason.map(|reason| reason.reconcile_with_output(has_tool_call));
609        self
610    }
611}
612
613/// Deserialization shape routed through builders for finish-reason reconciliation
614/// and empty-identifier normalization.
615#[derive(Deserialize)]
616struct CompletionResponseRepr {
617    choice: Vec<AssistantContent>,
618    usage: Usage,
619    origin: Origin,
620    #[serde(default)]
621    error: Option<String>,
622    #[serde(default)]
623    aborted: Option<String>,
624    #[serde(default)]
625    provider_request_id: Option<String>,
626    #[serde(default)]
627    finish_reason: Option<FinishReason>,
628    #[serde(default)]
629    accepts_unknown_finish_reasons: bool,
630    #[serde(default)]
631    unfinished_calls: Vec<CallId>,
632    raw: serde_json::Value,
633}
634
635impl From<CompletionResponseRepr> for CompletionResponse {
636    fn from(repr: CompletionResponseRepr) -> Self {
637        let CompletionResponseRepr {
638            choice,
639            usage,
640            mut origin,
641            error,
642            aborted,
643            provider_request_id,
644            finish_reason,
645            accepts_unknown_finish_reasons,
646            unfinished_calls,
647            raw,
648        } = repr;
649        use crate::provider_response::reported;
650        origin.response_id = reported(origin.response_id);
651        origin.response_model = reported(origin.response_model);
652        let mut response =
653            Self::new(choice, usage, origin, raw).with_optional_finish_reason(finish_reason);
654        response.error = error;
655        response.aborted = aborted;
656        response.provider_request_id = reported(provider_request_id);
657        response.accepts_unknown_finish_reasons = accepts_unknown_finish_reasons;
658        response.unfinished_calls = unfinished_calls;
659        response
660    }
661}
662
663/// The token usage a provider reported for one completion.
664///
665/// Every provider mapping keeps one contract, so the counters read the same
666/// way on every provider:
667///
668/// - `cached_input_tokens + cache_creation_input_tokens <= input_tokens`:
669///   input counts every prompt token, cache reads and writes included.
670/// - `reasoning_tokens <= output_tokens`: output counts every generated
671///   token, reasoning included.
672/// - `total_tokens == input_tokens + output_tokens`, absent unless both are
673///   reported.
674///
675/// A counter the provider did not send is `None`; a reported zero is
676/// `Some(0)`. Serialized as the same keys, absent when `None`.
677///
678/// ```
679/// use rig_core::completion::Usage;
680///
681/// let usage = Usage::new().input_tokens(12).output_tokens(3).total_tokens(15);
682/// assert_eq!(usage.input_tokens, Some(12));
683/// assert!(usage.cost.is_none());
684/// ```
685#[non_exhaustive]
686#[derive(Debug, Default, PartialEq, Clone, Copy, Serialize, Deserialize)]
687pub struct Usage {
688    /// Every input token of the request: uncached, read from a cache,
689    /// written to a cache, and any prompt a provider's hosted tools added.
690    #[serde(default, skip_serializing_if = "Option::is_none")]
691    pub input_tokens: Option<u64>,
692    /// Every output token, reasoning included.
693    #[serde(default, skip_serializing_if = "Option::is_none")]
694    pub output_tokens: Option<u64>,
695    /// `input_tokens + output_tokens`; absent unless both are reported.
696    #[serde(default, skip_serializing_if = "Option::is_none")]
697    pub total_tokens: Option<u64>,
698    /// The part of `input_tokens` read from a provider-managed cache.
699    #[serde(default, skip_serializing_if = "Option::is_none")]
700    pub cached_input_tokens: Option<u64>,
701    /// The part of `input_tokens` written to a provider-managed cache.
702    #[serde(default, skip_serializing_if = "Option::is_none")]
703    pub cache_creation_input_tokens: Option<u64>,
704    /// The part of `input_tokens` a provider's hosted tools added to the prompt.
705    #[serde(default, skip_serializing_if = "Option::is_none")]
706    pub tool_use_prompt_tokens: Option<u64>,
707    /// The part of `output_tokens` spent on internal reasoning ("thinking",
708    /// "thoughts").
709    #[serde(default, skip_serializing_if = "Option::is_none")]
710    pub reasoning_tokens: Option<u64>,
711    /// What the turn cost in USD, when known. Never derived from the token
712    /// counters here, and none of them is derived from it. A cost the
713    /// provider reports is its figure. One priced from the model's catalog
714    /// spec ([`Pricing::cost`](crate::catalog::Pricing::cost), from the
715    /// facts the wire was connected with) is the
716    /// standard-tier list price of the counted tokens: it leaves out the
717    /// service tier, long-context price tiers and hosted-tool fees (web
718    /// search, code execution), so it can be lower than the bill.
719    #[serde(default, skip_serializing_if = "Option::is_none")]
720    pub cost: Option<Cost>,
721    /// Whether this sum misses a figure, as [`Self::tokens_complete`] reads it.
722    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
723    pub(crate) incomplete_tokens: bool,
724}
725
726impl Usage {
727    /// No counter and no cost reported.
728    pub const fn new() -> Self {
729        Self {
730            input_tokens: None,
731            output_tokens: None,
732            total_tokens: None,
733            cached_input_tokens: None,
734            cache_creation_input_tokens: None,
735            tool_use_prompt_tokens: None,
736            reasoning_tokens: None,
737            cost: None,
738            incomplete_tokens: false,
739        }
740    }
741
742    /// Whether the provider reported any counter or a cost.
743    pub fn is_reported(&self) -> bool {
744        Self {
745            incomplete_tokens: false,
746            ..*self
747        } != Self::default()
748    }
749
750    /// Whether this sum has a figure from every call for each of input,
751    /// output and total. `false` means a summed counter can be lower than
752    /// what the calls used. A counter no call reported stays `None`, which
753    /// does not make the sum incomplete, and the detail counters such as
754    /// [`Self::reasoning_tokens`](field@Self::reasoning_tokens) are not
755    /// considered.
756    pub fn tokens_complete(&self) -> bool {
757        !self.incomplete_tokens
758    }
759
760    /// The tokens the call read and wrote, what a conversation's next
761    /// request sends again: [`Self::total_tokens`](field@Self::total_tokens),
762    /// else the input and output tokens. `None` without input tokens.
763    pub fn context_tokens(&self) -> Option<u64> {
764        self.total_tokens.or_else(|| {
765            Some(
766                self.input_tokens?
767                    .saturating_add(self.output_tokens.unwrap_or(0)),
768            )
769        })
770    }
771
772    /// Set, or with `None` clear, [`Self::input_tokens`](field@Self::input_tokens).
773    pub fn input_tokens(mut self, tokens: impl Into<Option<u64>>) -> Self {
774        self.input_tokens = tokens.into();
775        self
776    }
777
778    /// Set, or with `None` clear, [`Self::output_tokens`](field@Self::output_tokens).
779    pub fn output_tokens(mut self, tokens: impl Into<Option<u64>>) -> Self {
780        self.output_tokens = tokens.into();
781        self
782    }
783
784    /// Set, or with `None` clear, [`Self::total_tokens`](field@Self::total_tokens).
785    pub fn total_tokens(mut self, tokens: impl Into<Option<u64>>) -> Self {
786        self.total_tokens = tokens.into();
787        self
788    }
789
790    /// Set, or with `None` clear,
791    /// [`Self::cached_input_tokens`](field@Self::cached_input_tokens).
792    pub fn cached_input_tokens(mut self, tokens: impl Into<Option<u64>>) -> Self {
793        self.cached_input_tokens = tokens.into();
794        self
795    }
796
797    /// Set, or with `None` clear,
798    /// [`Self::cache_creation_input_tokens`](field@Self::cache_creation_input_tokens).
799    pub fn cache_creation_input_tokens(mut self, tokens: impl Into<Option<u64>>) -> Self {
800        self.cache_creation_input_tokens = tokens.into();
801        self
802    }
803
804    /// Set, or with `None` clear,
805    /// [`Self::tool_use_prompt_tokens`](field@Self::tool_use_prompt_tokens).
806    pub fn tool_use_prompt_tokens(mut self, tokens: impl Into<Option<u64>>) -> Self {
807        self.tool_use_prompt_tokens = tokens.into();
808        self
809    }
810
811    /// Set, or with `None` clear, [`Self::reasoning_tokens`](field@Self::reasoning_tokens).
812    pub fn reasoning_tokens(mut self, tokens: impl Into<Option<u64>>) -> Self {
813        self.reasoning_tokens = tokens.into();
814        self
815    }
816
817    /// Set, or with `None` clear, [`Self::cost`](field@Self::cost).
818    pub fn cost(mut self, cost: impl Into<Option<Cost>>) -> Self {
819        self.cost = cost.into();
820        self
821    }
822}
823
824/// What one or more turns cost, in USD. `total` is what was charged, or
825/// when [`Self::is_complete`] is `false`, a lower bound of it.
826///
827/// A part is `None` when its source does not give it: a provider that
828/// reports only a total leaves every part `None`, and one that reports
829/// input and output leaves the cache parts `None`. A cost computed from
830/// the catalog ([`Pricing::cost`](crate::catalog::Pricing::cost)) leaves a
831/// cache part `None` when the catalog lists no rate for it and the usage
832/// has such tokens; its `total` then sums the known parts only, and it is
833/// not complete. A part is never filled with a placeholder `0.0`. Summing
834/// costs keeps a part only when every side has it, and is complete only
835/// when every side is. A `None` part is left out when serialized, and an
836/// absent one reads back as `None`.
837#[non_exhaustive]
838#[derive(Clone, Copy, Debug, Default, PartialEq, Serialize, Deserialize)]
839pub struct Cost {
840    /// Uncached input tokens.
841    #[serde(
842        default,
843        skip_serializing_if = "Option::is_none",
844        deserialize_with = "crate::json_utils::floats"
845    )]
846    pub input: Option<f64>,
847    /// Output tokens, reasoning included.
848    #[serde(
849        default,
850        skip_serializing_if = "Option::is_none",
851        deserialize_with = "crate::json_utils::floats"
852    )]
853    pub output: Option<f64>,
854    /// Input tokens read from a cache.
855    #[serde(
856        default,
857        skip_serializing_if = "Option::is_none",
858        deserialize_with = "crate::json_utils::floats"
859    )]
860    pub cache_read: Option<f64>,
861    /// Input tokens written to a cache.
862    #[serde(
863        default,
864        skip_serializing_if = "Option::is_none",
865        deserialize_with = "crate::json_utils::floats"
866    )]
867    pub cache_write: Option<f64>,
868    /// The whole charge, or a lower bound of it when the cost is not
869    /// complete.
870    #[serde(deserialize_with = "crate::json_utils::floats")]
871    pub total: f64,
872    /// Whether a part with tokens had no price, so `total` leaves it out.
873    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
874    incomplete: bool,
875}
876
877impl Cost {
878    /// Whether [`Self::total`](field@Self::total) is the whole charge.
879    /// `false` when a part the usage has tokens for had no known price, so
880    /// `total` is a lower bound.
881    pub fn is_complete(&self) -> bool {
882        !self.incomplete
883    }
884
885    /// A cost from the catalog's prices, where `None` marks a part whose
886    /// tokens had no price: `total` sums the known parts, and the cost is
887    /// complete only when no part is `None`.
888    pub(crate) fn priced(
889        input: f64,
890        output: f64,
891        cache_read: Option<f64>,
892        cache_write: Option<f64>,
893    ) -> Self {
894        Self {
895            input: Some(input),
896            output: Some(output),
897            cache_read,
898            cache_write,
899            total: input + output + cache_read.unwrap_or(0.0) + cache_write.unwrap_or(0.0),
900            incomplete: cache_read.is_none() || cache_write.is_none(),
901        }
902    }
903
904    /// A cost split into its parts, each known; `total` is their sum.
905    pub fn from_parts(input: f64, output: f64, cache_read: f64, cache_write: f64) -> Self {
906        Self::priced(input, output, Some(cache_read), Some(cache_write))
907    }
908
909    /// A cost known only as its total; every part is `None`.
910    pub fn from_total(total: f64) -> Self {
911        Self {
912            total,
913            ..Self::default()
914        }
915    }
916
917    /// Set, or with `None` clear, [`Self::input`](field@Self::input).
918    /// `total` is left as it is.
919    pub fn input(mut self, input: impl Into<Option<f64>>) -> Self {
920        self.input = input.into();
921        self
922    }
923
924    /// Set, or with `None` clear, [`Self::output`](field@Self::output).
925    /// `total` is left as it is.
926    pub fn output(mut self, output: impl Into<Option<f64>>) -> Self {
927        self.output = output.into();
928        self
929    }
930
931    /// Set, or with `None` clear, [`Self::cache_read`](field@Self::cache_read).
932    /// `total` is left as it is.
933    pub fn cache_read(mut self, cache_read: impl Into<Option<f64>>) -> Self {
934        self.cache_read = cache_read.into();
935        self
936    }
937
938    /// Set, or with `None` clear, [`Self::cache_write`](field@Self::cache_write).
939    /// `total` is left as it is.
940    pub fn cache_write(mut self, cache_write: impl Into<Option<f64>>) -> Self {
941        self.cache_write = cache_write.into();
942        self
943    }
944}
945
946/// Sum one part of two costs: unknown when either side's is unknown, since
947/// a known part plus an unknown one is not known.
948fn add_part(lhs: Option<f64>, rhs: Option<f64>) -> Option<f64> {
949    Some(lhs? + rhs?)
950}
951
952/// `total` always sums. Each part sums only when both sides know it, and is
953/// `None` otherwise, so a summed part never understates what it covers. The
954/// sum is complete only when both sides are.
955impl Add for Cost {
956    type Output = Self;
957
958    fn add(self, other: Self) -> Self::Output {
959        Self {
960            input: add_part(self.input, other.input),
961            output: add_part(self.output, other.output),
962            cache_read: add_part(self.cache_read, other.cache_read),
963            cache_write: add_part(self.cache_write, other.cache_write),
964            total: self.total + other.total,
965            incomplete: self.incomplete || other.incomplete,
966        }
967    }
968}
969
970/// Sum two counters where an unreported side does not turn a reported one
971/// into "unreported". A running account stops at `u64::MAX` rather than
972/// wrap.
973fn add_counter(lhs: Option<u64>, rhs: Option<u64>) -> Option<u64> {
974    match (lhs, rhs) {
975        (None, None) => None,
976        (lhs, rhs) => Some(lhs.unwrap_or(0).saturating_add(rhs.unwrap_or(0))),
977    }
978}
979
980/// The sum of the token `counts` one reply reported, or an error when it
981/// overflows: no reply counts that many tokens, so its usage is malformed.
982pub(crate) fn token_sum(counts: impl IntoIterator<Item = u64>) -> Result<u64, ProviderError> {
983    counts
984        .into_iter()
985        .try_fold(0_u64, u64::checked_add)
986        .ok_or_else(|| ProviderError::Response("the reply's token counts overflow".to_owned()))
987}
988
989impl Add for Usage {
990    type Output = Self;
991
992    fn add(mut self, other: Self) -> Self::Output {
993        self += other;
994        self
995    }
996}
997
998/// Token counters add where an unreported side adds nothing. Cost sums only
999/// when both sides have one: a turn whose cost is unknown makes the sum
1000/// unknown, rather than too low. A side that reports nothing at all
1001/// ([`Usage::is_reported`] is `false`) adds nothing, so a fold from
1002/// [`Usage::default`] keeps its first turn's cost.
1003///
1004/// The sum is no longer [complete](Usage::tokens_complete) when either side
1005/// is not, when only one side has input, output or total, or when the right
1006/// side reports nothing, which counts as a call that reported nothing. An
1007/// empty left side counts as the start of a fold, so fold calls from
1008/// [`Usage::default`]: `empty_call + call` leaves no mark.
1009impl AddAssign for Usage {
1010    fn add_assign(&mut self, other: Self) {
1011        let gap = |lhs: Option<u64>, rhs: Option<u64>| lhs.is_some() != rhs.is_some();
1012        let incomplete_tokens = self.incomplete_tokens
1013            || other.incomplete_tokens
1014            || !other.is_reported()
1015            || (self.is_reported()
1016                && (gap(self.input_tokens, other.input_tokens)
1017                    || gap(self.output_tokens, other.output_tokens)
1018                    || gap(self.total_tokens, other.total_tokens)));
1019        self.add_figures(other);
1020        self.incomplete_tokens = incomplete_tokens;
1021    }
1022}
1023
1024impl Usage {
1025    /// Sums the counters and cost of `other` into this one.
1026    fn add_figures(&mut self, other: Self) {
1027        if !other.is_reported() {
1028            return;
1029        }
1030        if !self.is_reported() {
1031            *self = other;
1032            return;
1033        }
1034        self.cost = match (self.cost, other.cost) {
1035            (Some(lhs), Some(rhs)) => Some(lhs + rhs),
1036            _ => None,
1037        };
1038        self.input_tokens = add_counter(self.input_tokens, other.input_tokens);
1039        self.output_tokens = add_counter(self.output_tokens, other.output_tokens);
1040        self.total_tokens = add_counter(self.total_tokens, other.total_tokens);
1041        self.cached_input_tokens = add_counter(self.cached_input_tokens, other.cached_input_tokens);
1042        self.cache_creation_input_tokens = add_counter(
1043            self.cache_creation_input_tokens,
1044            other.cache_creation_input_tokens,
1045        );
1046        self.tool_use_prompt_tokens =
1047            add_counter(self.tool_use_prompt_tokens, other.tool_use_prompt_tokens);
1048        self.reasoning_tokens = add_counter(self.reasoning_tokens, other.reasoning_tokens);
1049    }
1050}
1051
1052/// Many calls' [`Usage`] summed for a running account: the token counters,
1053/// the known cost, and how many calls the sum holds and how many of them
1054/// were not fully priced.
1055///
1056/// ```
1057/// use rig_core::completion::{Usage, UsageTotals};
1058///
1059/// let mut totals = UsageTotals::default();
1060/// totals.record(&Usage::new().input_tokens(100).output_tokens(20).total_tokens(120));
1061/// assert_eq!((totals.calls, totals.unpriced, totals.uncached_input()), (1, 1, 100));
1062/// ```
1063#[derive(Clone, Copy, Debug, Default, PartialEq, Serialize, Deserialize)]
1064pub struct UsageTotals {
1065    /// The token counters summed, with no cost: a call that did not
1066    /// report a counter adds nothing to it, and
1067    /// [`Usage::tokens_complete`] is then `false`.
1068    pub tokens: Usage,
1069    /// The known costs summed, in USD.
1070    pub cost: f64,
1071    /// The calls whose cost is not known, or known only in part, so
1072    /// [`Self::cost`](field@Self::cost) is a lower bound when any.
1073    pub unpriced: u64,
1074    /// The calls summed.
1075    pub calls: u64,
1076}
1077
1078impl UsageTotals {
1079    /// Adds a finished call's `usage`.
1080    pub fn record(&mut self, usage: &Usage) {
1081        self.calls += 1;
1082        match usage.cost {
1083            Some(cost) => {
1084                self.cost += cost.total;
1085                if !cost.is_complete() {
1086                    self.unpriced += 1;
1087                }
1088            }
1089            None => self.unpriced += 1,
1090        }
1091        self.tokens += usage.cost(None);
1092    }
1093
1094    /// Adds what `other` summed.
1095    pub fn add(&mut self, other: &UsageTotals) {
1096        if other.calls > 0 {
1097            self.tokens += other.tokens;
1098        }
1099        self.cost += other.cost;
1100        self.unpriced += other.unpriced;
1101        self.calls += other.calls;
1102    }
1103
1104    /// Input tokens neither read from nor written to a cache.
1105    pub fn uncached_input(&self) -> u64 {
1106        self.tokens
1107            .input_tokens
1108            .unwrap_or(0)
1109            .saturating_sub(self.tokens.cached_input_tokens.unwrap_or(0))
1110            .saturating_sub(self.tokens.cache_creation_input_tokens.unwrap_or(0))
1111    }
1112
1113    /// The tokens read and written, cached input included.
1114    pub fn total_tokens(&self) -> u64 {
1115        self.tokens
1116            .input_tokens
1117            .unwrap_or(0)
1118            .saturating_add(self.tokens.output_tokens.unwrap_or(0))
1119    }
1120
1121    /// The cost as `$0.123`, ending in `+` when some calls were not priced,
1122    /// or `None` when no call was.
1123    pub fn cost_label(&self) -> Option<String> {
1124        if self.unpriced >= self.calls {
1125            return None;
1126        }
1127        let more = if self.unpriced > 0 { "+" } else { "" };
1128        Some(format!("{}{more}", dollars_label(self.cost)))
1129    }
1130
1131    /// The [cost](Self::cost_label), or as `1.2M tokens` when no call was
1132    /// priced, such as a local or subscription model's.
1133    pub fn cost_or_tokens(&self) -> String {
1134        self.cost_label()
1135            .unwrap_or_else(|| format!("{} tokens", tokens_label(self.total_tokens())))
1136    }
1137}
1138
1139/// One line for a person or a log: the calls, the tokens by kind and the
1140/// cost.
1141impl std::fmt::Display for UsageTotals {
1142    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1143        match self.calls {
1144            1 => f.write_str("1 model call")?,
1145            calls => write!(f, "{calls} model calls")?,
1146        }
1147        write!(f, ": {} in", tokens_label(self.uncached_input()))?;
1148        if let Some(read) = self.tokens.cached_input_tokens.filter(|read| *read > 0) {
1149            write!(f, ", {} cache read", tokens_label(read))?;
1150        }
1151        if let Some(written) = self
1152            .tokens
1153            .cache_creation_input_tokens
1154            .filter(|written| *written > 0)
1155        {
1156            write!(f, ", {} cache written", tokens_label(written))?;
1157        }
1158        write!(
1159            f,
1160            ", {} out",
1161            tokens_label(self.tokens.output_tokens.unwrap_or(0))
1162        )?;
1163        if let Some(thought) = self.tokens.reasoning_tokens.filter(|thought| *thought > 0) {
1164            write!(f, " ({} reasoning)", tokens_label(thought))?;
1165        }
1166        let cost = self.cost_label();
1167        write!(f, "; {}", cost.as_deref().unwrap_or("cost unknown"))
1168    }
1169}
1170
1171/// The context a conversation's next request sends, against the model's
1172/// input limit.
1173#[derive(Clone, Copy, Debug, PartialEq, Eq)]
1174pub struct ContextUse {
1175    /// Tokens in use.
1176    pub tokens: u64,
1177    /// The model's input limit, when known.
1178    pub limit: Option<u32>,
1179}
1180
1181impl ContextUse {
1182    /// The share of the input limit in use, in percent, when the limit is
1183    /// known.
1184    pub fn percent(&self) -> Option<u64> {
1185        self.limit
1186            .filter(|limit| *limit > 0)
1187            .map(|limit| self.tokens.saturating_mul(100) / u64::from(limit))
1188    }
1189}
1190
1191/// `45k/200k (22%)`, or `45k` when the input limit is not known.
1192impl std::fmt::Display for ContextUse {
1193    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1194        match (self.limit, self.percent()) {
1195            (Some(limit), Some(percent)) => write!(
1196                f,
1197                "{}/{} ({percent}%)",
1198                tokens_label(self.tokens),
1199                tokens_label(u64::from(limit))
1200            ),
1201            _ => f.write_str(&tokens_label(self.tokens)),
1202        }
1203    }
1204}
1205
1206/// A token count in at most four characters plus a unit: `999`, `1.2k`,
1207/// `45k`, `1.2M`.
1208pub fn tokens_label(count: u64) -> String {
1209    // The unit follows the rounded value, so 9,999 reads `10k`, not `10.0k`.
1210    let rounded = |unit: u64| count.saturating_add(unit / 2) / unit;
1211    let tenths = |unit: u64| {
1212        let tenths = rounded(unit / 10);
1213        format!("{}.{}", tenths / 10, tenths % 10)
1214    };
1215    match count {
1216        0..1_000 => count.to_string(),
1217        _ if rounded(100) < 100 => format!("{}k", tenths(1_000)),
1218        _ if rounded(1_000) < 1_000 => format!("{}k", rounded(1_000)),
1219        _ if rounded(100_000) < 100 => format!("{}M", tenths(1_000_000)),
1220        _ => format!("{}M", rounded(1_000_000)),
1221    }
1222}
1223
1224/// A cost in USD: tenths of a cent below a dollar, cents above.
1225fn dollars_label(cost: f64) -> String {
1226    if cost < 1.0 {
1227        format!("${cost:.3}")
1228    } else {
1229        format!("${cost:.2}")
1230    }
1231}
1232
1233/// Model capabilities used by runtimes when preparing requests.
1234/// Defaults are conservative; construct through [`Self::new`] and setters.
1235#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
1236pub struct ProviderCapabilities {
1237    /// Whether native structured output can remain enabled with tool calls
1238    /// without suppressing them. Defaults to `false`.
1239    pub composes_native_output_with_tools: bool,
1240    /// Whether the model answers a forced tool choice (`Required` or
1241    /// `Specific`) with an error. Rig then does not force the output tool
1242    /// of its own structured-output flow (the extractor). Defaults to `false`.
1243    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
1244    pub rejects_forced_tool_choice: bool,
1245}
1246
1247impl ProviderCapabilities {
1248    /// Create the conservative capability set used by default.
1249    pub const fn new() -> Self {
1250        Self {
1251            composes_native_output_with_tools: false,
1252            rejects_forced_tool_choice: false,
1253        }
1254    }
1255
1256    /// Declare whether native structured output composes with tool calls.
1257    pub const fn with_native_output_tool_composition(mut self, supported: bool) -> Self {
1258        self.composes_native_output_with_tools = supported;
1259        self
1260    }
1261
1262    /// Declare whether the model rejects a forced tool choice.
1263    pub const fn with_forced_tool_choice_rejected(mut self, rejected: bool) -> Self {
1264        self.rejects_forced_tool_choice = rejected;
1265        self
1266    }
1267}
1268
1269/// A completion request to any provider's model.
1270#[non_exhaustive]
1271#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
1272pub struct CompletionRequest {
1273    /// Optional model override for this request.
1274    pub model: Option<String>,
1275    /// The chat history to be sent to the completion model provider.
1276    /// The very last message is the prompt.
1277    ///
1278    /// It must hold at least one message, and every user and assistant
1279    /// message must carry content. The field is public, so this is a rule
1280    /// rather than a type guarantee: [`Self::validate_message_content`]
1281    /// checks it at the request boundary.
1282    ///
1283    /// Each message is shared, with the conversation it came from and the
1284    /// records of the request, so copying a request copies pointers.
1285    pub chat_history: Vec<Arc<Message>>,
1286    /// The documents to be sent to the completion model provider
1287    pub documents: Vec<Document>,
1288    /// The tools to be sent to the completion model provider, each shared,
1289    /// so copying a request copies pointers.
1290    pub tools: Vec<Arc<ToolDefinition>>,
1291    /// The temperature to be sent to the completion model provider
1292    #[serde(default, deserialize_with = "crate::json_utils::floats")]
1293    pub temperature: Option<f64>,
1294    /// The max tokens to be sent to the completion model provider
1295    pub max_tokens: Option<u64>,
1296    /// Which tools the model may or must call before it answers.
1297    pub tool_choice: Option<ToolChoice>,
1298    /// Additional provider-specific parameters to be sent to the completion model provider
1299    pub additional_params: Option<serde_json::Value>,
1300    /// Optional JSON Schema for structured output. When set, providers that support
1301    /// native structured outputs will constrain the model's response to match this schema.
1302    pub output_schema: Option<schemars::Schema>,
1303    /// Opt-in for sensitive request, response, and tool-content telemetry.
1304    /// Defaults to `false` and is excluded from serialization. Enabling it can
1305    /// expose prompts, context, tool results, and model output in span attributes
1306    /// and increase telemetry storage costs. Requires explicit caller consent.
1307    /// Agent drivers record normalized content; direct provider coverage varies,
1308    /// especially for streams consumed after the provider returns.
1309    #[serde(skip)]
1310    pub record_telemetry_content: bool,
1311    /// Whether a finish reason outside the normalized vocabulary
1312    /// ([`FinishReason::Other`]) ends the turn as a normal stop instead of a
1313    /// failure. Defaults to `false`. The response carries the choice, so its
1314    /// [`CompletionResponse::stop`], the runtimes and history replay agree.
1315    /// `Other` also holds genuine failures, such as a malformed tool call or a
1316    /// recitation block, so with this set the tool calls of such a reply run.
1317    /// [`FinishReason::ContentFilter`] still fails the turn.
1318    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
1319    pub accept_unknown_finish_reasons: bool,
1320    /// Send other models' reasoning in the history as reasoning where the
1321    /// target reads it ([`Accepts::foreign_reasoning`]), instead of as plain
1322    /// text. Defaults to `false`.
1323    ///
1324    /// [`Accepts::foreign_reasoning`]: crate::completion::Accepts::foreign_reasoning
1325    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
1326    pub foreign_reasoning: bool,
1327    /// Portable generation options. Precedence, lowest first: the mapped
1328    /// options, then [`Self::provider_options`], then `additional_params`.
1329    #[serde(default, skip_serializing_if = "GenerationOptions::is_default")]
1330    pub options: GenerationOptions,
1331    /// Typed per-provider options. The wire reads only the entry of its own
1332    /// provider, above the mapped options and below `additional_params`.
1333    #[serde(default, skip_serializing_if = "ProviderOptions::is_empty")]
1334    pub provider_options: ProviderOptions,
1335    /// Where a provider that caches prompts by marker (Anthropic's Messages
1336    /// family, OpenAI's Responses API from GPT-5.6 on) may mark the end of a
1337    /// stable prefix that later requests repeat, beside its own markers, so
1338    /// content after it (per-turn memory, a reminder) does not cost the
1339    /// cached prefix. A provider that takes fewer markers keeps the points
1340    /// furthest into the request; one that caches prefixes without markers
1341    /// ignores them. A provider that marks only some parts of a request moves
1342    /// a point back to the last part it can mark. Empty marks nothing.
1343    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1344    pub cache_points: Vec<CachePoint>,
1345}
1346
1347/// A point in a [`CompletionRequest`] that ends a stable prefix, for
1348/// [`CompletionRequest::cache_points`]. Prefixes run in the order a request
1349/// is sent: tools, then the system prompt, then the messages.
1350#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
1351#[serde(rename_all = "snake_case")]
1352pub enum CachePoint {
1353    /// After the tool definitions.
1354    Tools,
1355    /// After the system prompt.
1356    System,
1357    /// After the first `n` user and assistant messages. System messages
1358    /// are not counted, wherever they sit; `Messages(0)` is [`Self::System`].
1359    /// The point names the request's messages as written: adapting them
1360    /// for a wire, which drops some and joins adjacent user messages, moves
1361    /// the point with them, inside a joined message when it ends there.
1362    Messages(usize),
1363    /// After the first `items` content items of the user or assistant
1364    /// message at `message`, counted as [`Self::Messages`] counts them.
1365    Within {
1366        /// The message, from 0, system messages not counted.
1367        message: usize,
1368        /// How many of its content items the prefix holds.
1369        items: usize,
1370    },
1371}
1372
1373impl CompletionRequest {
1374    /// The system instructions of this request: the content of the leading
1375    /// [`Message::System`] in `chat_history`, which is where
1376    /// [`Self::preamble`] places it.
1377    pub fn system_instructions(&self) -> Option<&str> {
1378        match self.chat_history.first().map(Arc::as_ref) {
1379            Some(Message::System { content }) => Some(content.as_str()),
1380            _ => None,
1381        }
1382    }
1383
1384    /// Reject a request with no messages, a user or assistant message with no
1385    /// content, or a tool result with no content blocks. The error is
1386    /// [`ProviderError::Request`] and names the role and index of the first
1387    /// offending message.
1388    ///
1389    /// Every wire rejects an empty turn, so this turns a remote 400 into a
1390    /// local error. It checks the request direction only: a provider may
1391    /// return empty assistant content, which the reply keeps and the
1392    /// runtime judges. `System` content is a
1393    /// `String` and is not checked. A tool result holding one empty text
1394    /// block is not empty.
1395    ///
1396    /// [`Model::call`](crate::driver::Model::call)
1397    /// and [`Model::stream`](crate::driver::Model::stream) run it before
1398    /// encoding, so it covers
1399    /// [`DynModel`](crate::DynModel), every model a handler serves and the
1400    /// agent runtimes built on them. The OpenAI Responses websocket session
1401    /// sends without the driver and runs it on each send. Code that encodes
1402    /// a request some other way should call it first.
1403    pub fn validate_message_content(&self) -> Result<(), ProviderError> {
1404        if self.chat_history.is_empty() {
1405            return Err(ProviderError::request(
1406                "request has an empty chat history; providers require at least one message",
1407            ));
1408        }
1409
1410        let empty_message = |role: &str, index: usize| {
1411            ProviderError::request(format!(
1412                "{role} message at index {index} has no content; \
1413                 providers reject empty content blocks"
1414            ))
1415        };
1416
1417        for (index, message) in self.chat_history.iter().enumerate() {
1418            match &**message {
1419                Message::System { .. } => {}
1420                Message::Assistant(AssistantMessage { content, .. }) => {
1421                    if content.is_empty() {
1422                        return Err(empty_message("assistant", index));
1423                    }
1424                }
1425                Message::User { content } => {
1426                    if content.is_empty() {
1427                        return Err(empty_message("user", index));
1428                    }
1429                }
1430            }
1431        }
1432
1433        Ok(())
1434    }
1435
1436    /// The output schema's `"title"`, else `"response_schema"`: a name for
1437    /// providers that need one beside the JSON Schema (such as OpenAI).
1438    pub fn output_schema_name(&self) -> Option<String> {
1439        self.output_schema.as_ref().map(|schema| {
1440            schema
1441                .as_object()
1442                .and_then(|o| o.get("title"))
1443                .and_then(|v| v.as_str())
1444                .unwrap_or("response_schema")
1445                .to_string()
1446        })
1447    }
1448
1449    /// Returns documents normalized into a message (if any).
1450    /// Most providers do not accept documents directly as input, so it needs to convert into a
1451    /// `Message` so that it can be incorporated into `chat_history`.
1452    pub fn normalized_documents(&self) -> Option<Message> {
1453        if self.documents.is_empty() {
1454            return None;
1455        }
1456
1457        let content = self
1458            .documents
1459            .iter()
1460            .map(|doc| UserContent::document_text(doc.to_string(), Some(DocumentMediaType::TXT)))
1461            .collect();
1462
1463        Some(Message::User { content })
1464    }
1465}
1466
1467/// Place the documents message `message` at the first non-system position,
1468/// so document context lands after any leading system messages. A user
1469/// message already there takes the documents at its front instead, so the
1470/// history keeps alternating roles. Telemetry and the sent request must
1471/// agree on this placement.
1472pub(crate) fn insert_after_leading_system(chat_history: &mut Vec<Arc<Message>>, message: Message) {
1473    let insert_at = chat_history
1474        .iter()
1475        .position(|message| !matches!(&**message, Message::System { .. }))
1476        .unwrap_or(chat_history.len());
1477    let joins =
1478        |at: &&mut Arc<Message>| matches!(&***at, Message::User { content } if !content.is_empty());
1479    match (
1480        chat_history
1481            .get_mut(insert_at)
1482            .filter(joins)
1483            .map(Arc::make_mut),
1484        message,
1485    ) {
1486        (Some(Message::User { content }), Message::User { content: documents }) => {
1487            content.splice(0..0, documents);
1488        }
1489        (_, message) => chat_history.insert(insert_at, Arc::new(message)),
1490    }
1491}
1492
1493fn merge_provider_tools_into_additional_params(
1494    additional_params: Option<serde_json::Value>,
1495    provider_tools: Vec<ProviderToolDefinition>,
1496) -> Option<serde_json::Value> {
1497    if provider_tools.is_empty() {
1498        return additional_params;
1499    }
1500
1501    let mut provider_tools_json = provider_tools
1502        .into_iter()
1503        .map(|ProviderToolDefinition { kind, mut config }| {
1504            // Force the provider tool type from the strongly-typed field.
1505            config.insert("type".to_string(), serde_json::Value::String(kind));
1506            serde_json::Value::Object(config)
1507        })
1508        .collect::<Vec<_>>();
1509
1510    let mut params_map = match additional_params {
1511        Some(serde_json::Value::Object(map)) => map,
1512        Some(serde_json::Value::Bool(stream)) => {
1513            let mut map = serde_json::Map::new();
1514            map.insert("stream".to_string(), serde_json::Value::Bool(stream));
1515            map
1516        }
1517        _ => serde_json::Map::new(),
1518    };
1519
1520    let mut merged_tools = match remove_preserving_order(&mut params_map, "tools") {
1521        Some(serde_json::Value::Array(existing)) => existing,
1522        _ => Vec::new(),
1523    };
1524    merged_tools.append(&mut provider_tools_json);
1525    params_map.insert("tools".to_string(), serde_json::Value::Array(merged_tools));
1526    Some(serde_json::Value::Object(params_map))
1527}
1528
1529impl CompletionRequest {
1530    /// A request whose conversation is the one user message `prompt`, with
1531    /// no preamble, documents or tools. The setters below add to it and
1532    /// check nothing; [`Self::validate_message_content`] checks the content
1533    /// when the request is sent.
1534    ///
1535    /// Each setter changes the request's public fields as it is called, so
1536    /// order matters where two setters touch the same field: a second
1537    /// [`Self::preamble`] adds a second system message, and
1538    /// [`Self::additional_params`] with a `tools` key (or `None`) replaces
1539    /// provider tools added before it. Set `additional_params` first.
1540    ///
1541    /// ```
1542    /// use rig_core::completion::CompletionRequest;
1543    ///
1544    /// let request = CompletionRequest::new("Who are you?")
1545    ///     .preamble("You are a concise assistant.")
1546    ///     .temperature(0.5);
1547    /// assert_eq!(request.chat_history.len(), 2);
1548    /// assert_eq!(request.temperature, Some(0.5));
1549    /// ```
1550    pub fn new(prompt: impl Into<Message>) -> Self {
1551        Self::conversation(vec![Arc::new(prompt.into())])
1552    }
1553
1554    /// A request for `chat_history` as given, with nothing else set.
1555    fn conversation(chat_history: Vec<Arc<Message>>) -> Self {
1556        Self {
1557            model: None,
1558            chat_history,
1559            documents: Vec::new(),
1560            tools: Vec::new(),
1561            temperature: None,
1562            max_tokens: None,
1563            tool_choice: None,
1564            additional_params: None,
1565            output_schema: None,
1566            record_telemetry_content: false,
1567            accept_unknown_finish_reasons: false,
1568            foreign_reasoning: false,
1569            options: GenerationOptions::default(),
1570            provider_options: ProviderOptions::default(),
1571            cache_points: Vec::new(),
1572        }
1573    }
1574
1575    /// Put `preamble` first in the conversation, as a [`Message::System`],
1576    /// ahead of any system message already there.
1577    pub fn preamble(mut self, preamble: impl Into<String>) -> Self {
1578        self.chat_history
1579            .insert(0, Arc::new(Message::system(preamble.into())));
1580        self
1581    }
1582
1583    /// Override the model for this request.
1584    pub fn model<S: Into<String>>(mut self, model: impl Into<Option<S>>) -> Self {
1585        self.model = model.into().map(Into::into);
1586        self.warn_if_shadowed("model", self.model.is_some());
1587        self
1588    }
1589
1590    /// Add `message` to the conversation, before the prompt (its last
1591    /// message).
1592    pub fn message(self, message: impl Into<Arc<Message>>) -> Self {
1593        self.messages([message])
1594    }
1595
1596    /// Add `messages` to the conversation in order, before the prompt (its
1597    /// last message).
1598    pub fn messages(mut self, messages: impl IntoIterator<Item = impl Into<Arc<Message>>>) -> Self {
1599        let prompt = self.chat_history.pop();
1600        self.chat_history
1601            .extend(messages.into_iter().map(Into::into));
1602        self.chat_history.extend(prompt);
1603        self
1604    }
1605
1606    /// Add a document.
1607    pub fn document(mut self, document: Document) -> Self {
1608        self.documents.push(document);
1609        self
1610    }
1611
1612    /// Add documents in order.
1613    pub fn documents(mut self, documents: impl IntoIterator<Item = Document>) -> Self {
1614        self.documents.extend(documents);
1615        self
1616    }
1617
1618    /// Add a tool.
1619    pub fn tool(self, tool: impl Into<Arc<ToolDefinition>>) -> Self {
1620        self.tools([tool])
1621    }
1622
1623    /// Add tools in order.
1624    pub fn tools(
1625        mut self,
1626        tools: impl IntoIterator<Item = impl Into<Arc<ToolDefinition>>>,
1627    ) -> Self {
1628        let first = self.tools.is_empty();
1629        self.tools.extend(tools.into_iter().map(Into::into));
1630        self.warn_if_shadowed("tools", first && !self.tools.is_empty());
1631        self
1632    }
1633
1634    /// Add a provider-hosted tool: appended to `additional_params.tools`,
1635    /// so a later [`Self::additional_params`] with a `tools` key replaces
1636    /// it.
1637    pub fn provider_tool(self, tool: ProviderToolDefinition) -> Self {
1638        self.provider_tools(vec![tool])
1639    }
1640
1641    /// Add provider-hosted tools in order: appended to
1642    /// `additional_params.tools`.
1643    pub fn provider_tools(mut self, tools: Vec<ProviderToolDefinition>) -> Self {
1644        self.additional_params =
1645            merge_provider_tools_into_additional_params(self.additional_params.take(), tools);
1646        self
1647    }
1648
1649    /// Merge provider-specific parameters into the request's, key by key;
1650    /// `None` clears them, provider tools included. Provider conversion
1651    /// determines precedence over typed fields, and a key that overrides a
1652    /// typed field this request sets is logged.
1653    pub fn additional_params(
1654        mut self,
1655        additional_params: impl Into<Option<serde_json::Value>>,
1656    ) -> Self {
1657        let additional_params = additional_params.into();
1658        for key in shadowed_typed_fields(
1659            additional_params.as_ref(),
1660            &[
1661                ("temperature", self.temperature.is_some()),
1662                ("max_tokens", self.max_tokens.is_some()),
1663                ("tool_choice", self.tool_choice.is_some()),
1664                ("model", self.model.is_some()),
1665                ("tools", !self.tools.is_empty()),
1666                ("response_format", self.output_schema.is_some()),
1667            ],
1668        ) {
1669            warn_shadowed(key);
1670        }
1671        self.additional_params =
1672            json_utils::merge_params(self.additional_params.take(), additional_params);
1673        self
1674    }
1675
1676    /// Set, or with `None` clear, the temperature.
1677    pub fn temperature(mut self, temperature: impl Into<Option<f64>>) -> Self {
1678        self.temperature = temperature.into();
1679        self.warn_if_shadowed("temperature", self.temperature.is_some());
1680        self
1681    }
1682
1683    /// Set, or with `None` clear, the output-token limit. Provider-specific
1684    /// defaults and requirements apply.
1685    pub fn max_tokens(mut self, max_tokens: impl Into<Option<u64>>) -> Self {
1686        self.max_tokens = max_tokens.into();
1687        self.warn_if_shadowed("max_tokens", self.max_tokens.is_some());
1688        self
1689    }
1690
1691    /// Set the tool-selection policy.
1692    pub fn tool_choice(mut self, tool_choice: ToolChoice) -> Self {
1693        self.tool_choice = Some(tool_choice);
1694        self.warn_if_shadowed("tool_choice", true);
1695        self
1696    }
1697
1698    /// Set, or with `None` clear, a native structured-output schema for
1699    /// providers that support one. The returned content is not
1700    /// deserialized.
1701    pub fn output_schema(mut self, schema: impl Into<Option<schemars::Schema>>) -> Self {
1702        self.output_schema = schema.into();
1703        self.warn_if_shadowed("response_format", self.output_schema.is_some());
1704        self
1705    }
1706
1707    /// Opt in to sensitive content telemetry, off by default. See
1708    /// [`Self::record_telemetry_content`] for what that exposes.
1709    pub fn record_content_telemetry(mut self, enabled: bool) -> Self {
1710        self.record_telemetry_content = enabled;
1711        self
1712    }
1713
1714    /// Accept, or with `false` refuse, finish reasons outside the normalized
1715    /// vocabulary as a normal stop. See
1716    /// [`Self::accept_unknown_finish_reasons`] for what that lets through.
1717    ///
1718    /// [`Self::accept_unknown_finish_reasons`]: field@Self::accept_unknown_finish_reasons
1719    pub fn accept_unknown_finish_reasons(mut self, accept: bool) -> Self {
1720        self.accept_unknown_finish_reasons = accept;
1721        self
1722    }
1723
1724    /// Replace the portable generation options with `options`, a reusable
1725    /// value. Calls apply in order: this replaces every field, so a
1726    /// shortcut such as [`Self::seed`] called before it is lost, and one
1727    /// called after it sets its one field on top.
1728    ///
1729    /// ```
1730    /// use rig_core::completion::{CompletionRequest, Effort, GenerationOptions};
1731    ///
1732    /// let shared = GenerationOptions::new().reasoning(Effort::High).seed(1);
1733    /// let request = CompletionRequest::new("hi").seed(7).options(shared.clone()).seed(2);
1734    /// assert_eq!(request.options, shared.seed(2));
1735    /// ```
1736    pub fn options(mut self, options: GenerationOptions) -> Self {
1737        self.options = options;
1738        self
1739    }
1740
1741    /// Set the reasoning level or budget in [`Self::options`](field@Self::options), as
1742    /// [`GenerationOptions::reasoning`](GenerationOptions::reasoning) does,
1743    /// keeping its other fields. See
1744    /// [`Self::options`](method@Self::options) for the order of calls.
1745    pub fn reasoning(mut self, reasoning: impl Into<Reasoning>) -> Self {
1746        self.options = std::mem::take(&mut self.options).reasoning(reasoning);
1747        self
1748    }
1749
1750    /// Set the cache retention in [`Self::options`](field@Self::options), as
1751    /// [`GenerationOptions::cache`](GenerationOptions::cache) does,
1752    /// keeping its other fields. See
1753    /// [`Self::options`](method@Self::options) for the order of calls.
1754    pub fn cache(mut self, cache: CacheRetention) -> Self {
1755        self.options = std::mem::take(&mut self.options).cache(cache);
1756        self
1757    }
1758
1759    /// Set the service tier in [`Self::options`](field@Self::options), as
1760    /// [`GenerationOptions::service_tier`](GenerationOptions::service_tier) does,
1761    /// keeping its other fields. See
1762    /// [`Self::options`](method@Self::options) for the order of calls.
1763    pub fn service_tier(mut self, tier: ServiceTier) -> Self {
1764        self.options = std::mem::take(&mut self.options).service_tier(tier);
1765        self
1766    }
1767
1768    /// Set the answer verbosity in [`Self::options`](field@Self::options), as
1769    /// [`GenerationOptions::verbosity`](GenerationOptions::verbosity) does,
1770    /// keeping its other fields. See
1771    /// [`Self::options`](method@Self::options) for the order of calls.
1772    pub fn verbosity(mut self, verbosity: Verbosity) -> Self {
1773        self.options = std::mem::take(&mut self.options).verbosity(verbosity);
1774        self
1775    }
1776
1777    /// Set whether the model may call several tools in one turn in
1778    /// [`Self::options`](field@Self::options), as
1779    /// [`GenerationOptions::parallel_tool_calls`] does, keeping its other
1780    /// fields. See
1781    /// [`Self::options`](method@Self::options) for the order of calls.
1782    pub fn parallel_tool_calls(mut self, parallel: bool) -> Self {
1783        self.options = std::mem::take(&mut self.options).parallel_tool_calls(parallel);
1784        self
1785    }
1786
1787    /// Set the nucleus sampling probability mass in [`Self::options`](field@Self::options), as
1788    /// [`GenerationOptions::top_p`](GenerationOptions::top_p) does,
1789    /// keeping its other fields. See
1790    /// [`Self::options`](method@Self::options) for the order of calls.
1791    pub fn top_p(mut self, top_p: f64) -> Self {
1792        self.options = std::mem::take(&mut self.options).top_p(top_p);
1793        self
1794    }
1795
1796    /// Set the sampling seed in [`Self::options`](field@Self::options), as
1797    /// [`GenerationOptions::seed`](GenerationOptions::seed) does,
1798    /// keeping its other fields. See
1799    /// [`Self::options`](method@Self::options) for the order of calls.
1800    pub fn seed(mut self, seed: u64) -> Self {
1801        self.options = std::mem::take(&mut self.options).seed(seed);
1802        self
1803    }
1804
1805    /// Set the stop sequences in [`Self::options`](field@Self::options), as
1806    /// [`GenerationOptions::stop`](GenerationOptions::stop) does,
1807    /// keeping its other fields. See
1808    /// [`Self::options`](method@Self::options) for the order of calls.
1809    pub fn stop<S: Into<String>>(mut self, stop: impl IntoIterator<Item = S>) -> Self {
1810        self.options = std::mem::take(&mut self.options).stop(stop);
1811        self
1812    }
1813
1814    /// Set what happens to an option the wire or model cannot honour in
1815    /// [`Self::options`](field@Self::options), as
1816    /// [`GenerationOptions::on_unsupported`] does, keeping its other fields. See
1817    /// [`Self::options`](method@Self::options) for the order of calls.
1818    pub fn on_unsupported(mut self, policy: OnUnsupported) -> Self {
1819        self.options = std::mem::take(&mut self.options).on_unsupported(policy);
1820        self
1821    }
1822
1823    /// Replace the typed per-provider options.
1824    ///
1825    /// Calls apply in order: this replaces every entry, so an entry set by
1826    /// an earlier [`Self::provider_option`] is lost, and a later
1827    /// [`Self::provider_option`] replaces its provider's entry on top.
1828    pub fn provider_options(mut self, options: ProviderOptions) -> Self {
1829        self.provider_options = options;
1830        self
1831    }
1832
1833    /// Store `options` as the entry of their provider
1834    /// ([`ExtensionOptions::Ext`]), replacing that provider's entry and
1835    /// keeping every other, as [`ProviderOptions::set`] does. Options that
1836    /// do not serialize fail the request's encode.
1837    ///
1838    /// The entry is always stored under `O::Ext`'s key, the built-in
1839    /// provider the options type belongs to. A third-party provider whose
1840    /// extension reuses a built-in options type (say `OpenAiOptions` for an
1841    /// OpenAI-compatible gateway) must store them with
1842    /// [`ProviderOptions::with::<P>`](ProviderOptions::with) instead, or its
1843    /// wire never reads them.
1844    ///
1845    /// ```
1846    /// use rig_core::completion::{CompletionRequest, ProviderOptions};
1847    /// use rig_core::providers::openrouter::extension::{
1848    ///     OpenRouterExt, OpenRouterOptions, ProviderPreferences,
1849    /// };
1850    ///
1851    /// let request = CompletionRequest::new("hi").provider_option(
1852    ///     OpenRouterOptions::new().provider(ProviderPreferences::new().allow_fallbacks(false)),
1853    /// );
1854    /// assert!(request.provider_options.contains::<OpenRouterExt>());
1855    /// ```
1856    pub fn provider_option<O: ExtensionOptions>(mut self, options: O) -> Self {
1857        self.provider_options = std::mem::take(&mut self.provider_options).set(options);
1858        self
1859    }
1860
1861    /// The input messages telemetry records: the conversation with the
1862    /// documents inserted after any leading system messages.
1863    pub fn messages_for_telemetry(&self) -> Vec<Arc<Message>> {
1864        let mut messages = self.chat_history.clone();
1865        if let Some(documents) = self.normalized_documents() {
1866            insert_after_leading_system(&mut messages, documents);
1867        }
1868        messages
1869    }
1870
1871    /// Log a typed field `key` that `additional_params` already overrides.
1872    fn warn_if_shadowed(&self, key: &'static str, set: bool) {
1873        if !shadowed_typed_fields(self.additional_params.as_ref(), &[(key, set)]).is_empty() {
1874            warn_shadowed(key);
1875        }
1876    }
1877}
1878
1879fn warn_shadowed(key: &str) {
1880    if matches!(key, "tools" | "response_format") {
1881        tracing::warn!(
1882            key,
1883            "additional_params also carries `{key}`; the provider decides how it combines with the typed field"
1884        );
1885    } else {
1886        tracing::warn!(
1887            key,
1888            "additional_params overrides the typed `{key}` field set on the same request"
1889        );
1890    }
1891}
1892
1893impl From<&str> for CompletionRequest {
1894    fn from(prompt: &str) -> Self {
1895        Self::new(prompt)
1896    }
1897}
1898
1899impl From<String> for CompletionRequest {
1900    fn from(prompt: String) -> Self {
1901        Self::new(prompt)
1902    }
1903}
1904
1905impl From<Message> for CompletionRequest {
1906    fn from(prompt: Message) -> Self {
1907        Self::new(prompt)
1908    }
1909}
1910
1911/// The conversation as given, ending with the prompt. An empty one fails
1912/// [`CompletionRequest::validate_message_content`].
1913impl From<Vec<Message>> for CompletionRequest {
1914    fn from(chat_history: Vec<Message>) -> Self {
1915        Self::conversation(chat_history.into_iter().map(Arc::new).collect())
1916    }
1917}
1918
1919/// The passthrough keys that will override a typed field the caller also set.
1920/// The override itself is the documented precedence (see
1921/// [`CompletionRequest::additional_params`]); naming the collisions
1922/// makes an accidental one visible instead of silent.
1923pub(crate) fn shadowed_typed_fields<'a>(
1924    additional_params: Option<&serde_json::Value>,
1925    typed: &[(&'a str, bool)],
1926) -> Vec<&'a str> {
1927    let Some(serde_json::Value::Object(params)) = additional_params else {
1928        return Vec::new();
1929    };
1930    typed
1931        .iter()
1932        .filter(|(key, set)| *set && params.contains_key(*key))
1933        .map(|(key, _)| *key)
1934        .collect()
1935}
1936
1937#[cfg(test)]
1938mod tests;
1939
1940#[cfg(test)]
1941mod response_identity_tests;
1942
1943#[cfg(test)]
1944mod plain_value_tests;