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;