rig_core/completion/

request.rs

//! Completion requests, normalized responses, and provider model contracts.
//!
//! ```
//! use rig_core::completion::CompletionRequest;
//!
//! let request = CompletionRequest::new("Who are you?")
//!     .preamble("You are a concise assistant.")
//!     .temperature(0.5);
//! assert_eq!(request.temperature, Some(0.5));
//! ```

use super::message::{
    AssistantContent, AssistantMessage, CallId, DocumentMediaType, Origin, StopReason, ToolCall,
};
use super::options::{
    CacheRetention, GenerationOptions, OnUnsupported, Reasoning, ServiceTier, Verbosity,
};
use super::provider_options::{ExtensionOptions, ProviderExtension, ProviderOptions, ReplyExtras};
use crate::error::ProviderError;
use crate::json_utils::remove_preserving_order;
use crate::message::ToolChoice;
use crate::{
    json_utils,
    message::{Message, ToolName, UserContent},
};

use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use std::ops::{Add, AddAssign};
use std::sync::Arc;

/// A document sent with a request as context, rendered before the chat history.
#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
pub struct Document {
    /// Stable document identifier included in the serialized context block.
    pub id: String,
    /// Text content passed to the model as retrieval or static context.
    pub text: String,
    /// Additional string metadata rendered before the document text.
    #[serde(flatten)]
    pub additional_props: HashMap<String, String>,
}

impl std::fmt::Display for Document {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
            concat!("<file id: {}>\n", "{}\n", "</file>\n"),
            self.id,
            if self.additional_props.is_empty() {
                self.text.clone()
            } else {
                let mut sorted_props = self.additional_props.iter().collect::<Vec<_>>();
                sorted_props.sort_by(|a, b| a.0.cmp(b.0));
                let metadata = sorted_props
                    .iter()
                    .map(|(k, v)| format!("{k}: {v:?}"))
                    .collect::<Vec<_>>()
                    .join(" ");
                format!("<metadata {} />\n{}", metadata, self.text)
            }
        )
    }
}

/// A tool the model may call: its name, description and argument schema,
/// sent to the model, and what the tool does to the world
/// ([`ToolAnnotations`]), which stays with the host.
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
pub struct ToolDefinition {
    /// Tool name exposed to the model. It must match the registered tool name.
    pub name: ToolName,
    /// Human-readable description sent to the model.
    pub description: String,
    /// JSON Schema describing tool arguments.
    pub parameters: serde_json::Value,
    /// What calling the tool does to the world, for the host's policies
    /// (approval, plan mode, running calls side by side). Never sent to
    /// the model; written only when something is stated.
    #[serde(default, skip_serializing_if = "ToolAnnotations::is_empty")]
    pub annotations: ToolAnnotations,
}

impl ToolDefinition {
    /// A tool the model may call by `name`, with arguments matching the
    /// JSON Schema `parameters`, and no annotations.
    pub fn new(
        name: ToolName,
        description: impl Into<String>,
        parameters: serde_json::Value,
    ) -> Self {
        Self {
            name,
            description: description.into(),
            parameters,
            annotations: ToolAnnotations::default(),
        }
    }

    /// The same definition with `annotations`.
    pub fn with_annotations(mut self, annotations: ToolAnnotations) -> Self {
        self.annotations = annotations;
        self
    }
}

/// What calling a tool does to the world, as the Model Context Protocol's
/// tool annotations state it, and spelled as they are on its wire
/// (`readOnlyHint`, …), so an MCP tool's annotations read straight into
/// one. Each is a hint a tool's author gives: a host's policies read them
/// (approval, plan mode, which calls run side by side), never trusting a
/// tool it does not trust for them. A hint left unset takes the protocol's
/// default, which the accessors apply: not read-only, destructive, not
/// idempotent, open world.
///
/// ```
/// use rig_core::completion::ToolAnnotations;
///
/// let read = ToolAnnotations::default().with_read_only(true).with_open_world(false);
/// assert!(read.read_only() && !read.destructive() && !read.open_world());
/// let unknown = ToolAnnotations::default();
/// assert!(!unknown.read_only() && unknown.destructive() && unknown.open_world());
/// let mcp: ToolAnnotations = serde_json::from_value(serde_json::json!({"readOnlyHint": true}))?;
/// assert!(mcp.read_only());
/// # Ok::<(), serde_json::Error>(())
/// ```
#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct ToolAnnotations {
    /// A human-readable title for the tool.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub title: Option<String>,
    /// Whether the tool changes nothing in its environment.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub read_only_hint: Option<bool>,
    /// Whether a tool that changes things may also destroy or overwrite
    /// what was there (rather than only add). Meaningless for a read-only
    /// tool.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub destructive_hint: Option<bool>,
    /// Whether calling the tool again with the same arguments has no
    /// further effect. Meaningless for a read-only tool.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub idempotent_hint: Option<bool>,
    /// Whether the tool reaches beyond a closed set of things, such as the
    /// web or a shell; `false` for one that works on a known store, such
    /// as the project's files.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub open_world_hint: Option<bool>,
}

impl ToolAnnotations {
    /// Whether nothing is stated.
    pub fn is_empty(&self) -> bool {
        *self == Self::default()
    }

    /// Whether the tool changes nothing: the hint, else `false`.
    pub fn read_only(&self) -> bool {
        self.read_only_hint.unwrap_or(false)
    }

    /// Whether the tool may destroy or overwrite something: never for a
    /// read-only tool, else the hint, else `true`.
    pub fn destructive(&self) -> bool {
        !self.read_only() && self.destructive_hint.unwrap_or(true)
    }

    /// Whether repeating a call has no further effect: always for a
    /// read-only tool, else the hint, else `false`.
    pub fn idempotent(&self) -> bool {
        self.read_only() || self.idempotent_hint.unwrap_or(false)
    }

    /// Whether the tool reaches an open world: the hint, else `true`.
    pub fn open_world(&self) -> bool {
        self.open_world_hint.unwrap_or(true)
    }

    /// The same annotations with a title.
    pub fn with_title(mut self, title: impl Into<String>) -> Self {
        self.title = Some(title.into());
        self
    }

    /// The same annotations stating whether the tool is read-only.
    pub fn with_read_only(mut self, read_only: bool) -> Self {
        self.read_only_hint = Some(read_only);
        self
    }

    /// The same annotations stating whether the tool is destructive.
    pub fn with_destructive(mut self, destructive: bool) -> Self {
        self.destructive_hint = Some(destructive);
        self
    }

    /// The same annotations stating whether the tool is idempotent.
    pub fn with_idempotent(mut self, idempotent: bool) -> Self {
        self.idempotent_hint = Some(idempotent);
        self
    }

    /// The same annotations stating whether the tool reaches an open world.
    pub fn with_open_world(mut self, open_world: bool) -> Self {
        self.open_world_hint = Some(open_world);
        self
    }
}

/// Provider-native tool definition.
///
/// Stored under `additional_params.tools` and forwarded by providers that support
/// provider-managed tools.
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
pub struct ProviderToolDefinition {
    /// Tool type/kind name as expected by the target provider (for example `web_search`).
    #[serde(rename = "type")]
    pub kind: String,
    /// Additional provider-specific configuration for this hosted tool.
    #[serde(flatten, default, skip_serializing_if = "serde_json::Map::is_empty")]
    pub config: serde_json::Map<String, serde_json::Value>,
}

impl ProviderToolDefinition {
    /// Creates a provider-hosted tool definition by type.
    pub fn new(kind: impl Into<String>) -> Self {
        Self {
            kind: kind.into(),
            config: serde_json::Map::new(),
        }
    }

    /// Adds a provider-specific configuration key/value.
    pub fn with_config(mut self, key: impl Into<String>, value: serde_json::Value) -> Self {
        self.config.insert(key.into(), value);
        self
    }
}

/// Normalized generation ending. Unmapped provider values remain in [`Self::Other`].
/// Failure statuses may accompany parseable output; callers must decide whether
/// such output is usable rather than treating every response as successful.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum FinishReason {
    /// Natural end of the response.
    Stop,
    /// The response hit the output-token limit.
    Length,
    /// The model stopped to call one or more tools.
    ToolCalls,
    /// The provider filtered the content.
    ContentFilter,
    /// A provider-specific reason outside the normalized vocabulary, carried
    /// verbatim in the provider's own wire spelling.
    Other(String),
}

impl FinishReason {
    /// Changes [`Self::Stop`] to [`Self::ToolCalls`] when output contains a tool
    /// call. All other reasons remain unchanged. Response builders and streaming
    /// aggregation apply this reconciliation.
    pub fn reconcile_with_output(self, has_tool_call: bool) -> Self {
        if has_tool_call && matches!(self, Self::Stop) {
            Self::ToolCalls
        } else {
            self
        }
    }

    /// Returns whether the reason is [`Self::Length`] or [`Self::ContentFilter`].
    /// These reasons permit answerless turns without treating absent content as
    /// a malformed response. Unknown reasons are not classified as truncation.
    pub fn truncated_output(&self) -> bool {
        matches!(self, Self::Length | Self::ContentFilter)
    }

    /// Formats an answerless-turn diagnostic with budget or filtering advice
    /// for known truncation reasons, and a generic explanation otherwise.
    pub fn no_answer_message(&self) -> String {
        let remedy = match self {
            Self::Length => {
                "the turn ran out of output budget before producing one — \
                 raise max_tokens for this request"
            }
            Self::ContentFilter => {
                "the provider filtered the response — the content, not the \
                 budget, is what it objected to"
            }
            _ => "the turn ended before producing one",
        };
        format!(
            "the model produced no answer and stopped with \
             finish_reason={self:?}; {remedy}"
        )
    }
}

/// Assistant content and normalized completion metadata. The choice may be
/// empty, including for truncated or filtered turns. Provider-specific data is
/// available through [`Self::raw`] without retaining a concrete model type.
///
/// A response goes straight back into the conversation as the assistant
/// turn: `history.extend(response.message())`.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(from = "CompletionResponseRepr")]
pub struct CompletionResponse {
    /// Assistant content returned by the provider, one block per provider
    /// output item, in provider order. Possibly empty.
    pub choice: Vec<AssistantContent>,
    /// Tokens used during prompting and responding
    pub usage: Usage,
    /// The wire, provider and requested model that produced the response,
    /// with the model and response id the provider reported.
    pub origin: Origin,
    /// The provider's report that the turn failed, such as a refusal's
    /// explanation. The turn's message then ends in [`StopReason::Error`]
    /// and is never replayed.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub error: Option<String>,
    /// Why the reply stopped before the provider ended it, when the caller
    /// stopped reading: the turn's message then ends in
    /// [`StopReason::Aborted`] and is replayed as its text alone.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub aborted: Option<String>,
    /// Request identifier from HTTP headers or SDK metadata, not the body's
    /// response ID. `None` when the provider reports none.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub provider_request_id: Option<String>,
    /// Reported finish reason, reconciled by the setters with tool-call output.
    /// Read through [`Self::finish_reason`].
    #[serde(default)]
    finish_reason: Option<FinishReason>,
    /// Whether [`FinishReason::Other`] ends the turn as a normal stop. Read
    /// through [`Self::accepts_unknown_finish_reasons`].
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    accepts_unknown_finish_reasons: bool,
    /// The calls the provider ended the reply in the middle of. Read
    /// through [`Self::unfinished_calls`].
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    unfinished_calls: Vec<CallId>,
    /// Provider response document for typed inspection through deserialization.
    /// Parsed wire types may omit unmodeled fields. This data does not override
    /// normalized fields; callers constructing responses must supply it.
    pub raw: serde_json::Value,
}

/// Distinct response and transport identifiers for one model call.
/// Unreported identifiers remain `None`.
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct ResponseIdentity {
    /// Response-wide ID.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub response_id: Option<String>,
    /// Transport request ID from HTTP headers or SDK metadata.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub provider_request_id: Option<String>,
}

impl CompletionResponse {
    /// Create a response from its required parts; optional metadata starts
    /// unset. `raw` is the provider's own document for this response,
    /// serialized; see [`Self::raw`].
    pub fn new(
        choice: Vec<AssistantContent>,
        usage: Usage,
        origin: Origin,
        raw: serde_json::Value,
    ) -> Self {
        Self {
            choice,
            usage,
            origin,
            error: None,
            aborted: None,
            provider_request_id: None,
            finish_reason: None,
            accepts_unknown_finish_reasons: false,
            unfinished_calls: Vec::new(),
            raw,
        }
    }

    /// The provider descriptor name (`"openai"`).
    pub fn provider(&self) -> &str {
        &self.origin.provider
    }

    /// `P`'s typed view of [`Self::raw`]. `None` unless `P` is the provider
    /// that produced the reply.
    ///
    /// # Errors
    ///
    /// The inner result fails when `raw` does not hold `P`'s extras.
    pub fn extras<P: ProviderExtension>(&self) -> Option<Result<P::Extras, serde_json::Error>> {
        (self.origin.provider == P::PROVIDER)
            .then(|| P::Extras::from_reply(&self.origin.api, &self.raw))
    }

    /// `P`'s typed view of [`Self::raw`], or the empty view (every field
    /// `None`) when it cannot be read: when another provider produced the
    /// reply, or when `raw` does not hold `P`'s extras. A decode failure is
    /// logged at `debug`; use [`Self::extras`] to tell the cases apart.
    pub fn extras_lossy<P: ProviderExtension>(&self) -> P::Extras
    where
        P::Extras: Default,
    {
        match self.extras::<P>() {
            Some(Ok(extras)) => extras,
            Some(Err(error)) => {
                tracing::debug!(
                    provider = P::PROVIDER,
                    api = %self.origin.api,
                    %error,
                    "reply extras did not decode; reading them as empty"
                );
                P::Extras::default()
            }
            None => P::Extras::default(),
        }
    }

    /// The model the provider reported, when it reported one.
    pub fn model(&self) -> Option<&str> {
        self.origin.response_model.as_deref()
    }

    /// The provider's response id, when it sent one.
    pub fn response_id(&self) -> Option<&str> {
        self.origin.response_id.as_deref()
    }

    /// Why the model stopped generating, when the provider reported it.
    pub fn finish_reason(&self) -> Option<FinishReason> {
        self.finish_reason.clone()
    }

    /// Whether a finish reason outside the normalized vocabulary ends the
    /// turn as a normal stop, as the request asked
    /// ([`CompletionRequest::accept_unknown_finish_reasons`]).
    ///
    /// [`CompletionRequest::accept_unknown_finish_reasons`]: field@CompletionRequest::accept_unknown_finish_reasons
    pub fn accepts_unknown_finish_reasons(&self) -> bool {
        self.accepts_unknown_finish_reasons
    }

    /// The tool calls the provider ended the reply in the middle of (their
    /// arguments as far as they came), in the order they opened, such as a
    /// call cut by [`FinishReason::Length`]. Empty when every call in
    /// [`Self::choice`] was finished.
    pub fn unfinished_calls(&self) -> impl Iterator<Item = &ToolCall> {
        self.tool_calls()
            .filter(|call| self.unfinished_calls.contains(&call.id))
    }

    /// The same response, `calls` (ids of calls in [`Self::choice`]) being
    /// the ones the provider ended the reply in the middle of.
    pub fn with_unfinished_calls(mut self, calls: impl IntoIterator<Item = CallId>) -> Self {
        self.unfinished_calls = calls.into_iter().collect();
        self
    }

    /// Accept, or refuse, [`FinishReason::Other`] as a normal stop in
    /// [`Self::stop`]. Filtered content and a reported failure still fail.
    pub fn accept_unknown_finish_reasons(mut self, accept: bool) -> Self {
        self.accepts_unknown_finish_reasons = accept;
        self
    }

    /// How the turn ended, for history. It fails closed: only a natural
    /// stop, the token limit and a stop to call tools are successes. A
    /// reported failure, filtered content and any finish reason outside
    /// that set are [`StopReason::Error`], unless the response accepts
    /// unknown reasons ([`Self::accepts_unknown_finish_reasons`]), which then
    /// stop like [`FinishReason::Stop`]. A reply the caller stopped reading
    /// is [`StopReason::Aborted`].
    pub fn stop(&self) -> StopReason {
        if let Some(error) = &self.error {
            return StopReason::Error(error.clone());
        }
        if let Some(reason) = &self.aborted {
            return StopReason::Aborted(reason.clone());
        }
        match &self.finish_reason {
            Some(FinishReason::Length) => StopReason::Length,
            Some(FinishReason::ToolCalls) => StopReason::ToolUse,
            Some(FinishReason::ContentFilter) => {
                StopReason::Error("Provider finish_reason: content_filter".to_owned())
            }
            Some(FinishReason::Other(reason)) if !self.accepts_unknown_finish_reasons => {
                StopReason::Error(format!("Provider finish_reason: {reason}"))
            }
            Some(FinishReason::Stop | FinishReason::Other(_)) | None
                if self.tool_calls().next().is_some() =>
            {
                StopReason::ToolUse
            }
            Some(FinishReason::Stop | FinishReason::Other(_)) | None => StopReason::Stop,
        }
    }

    /// This response's identity metadata as one [`ResponseIdentity`] carrier.
    pub fn identity(&self) -> ResponseIdentity {
        ResponseIdentity {
            response_id: self.origin.response_id.clone(),
            provider_request_id: self.provider_request_id.clone(),
        }
    }

    /// Attach the normalized finish reason, reconciled against the choice via
    /// [`FinishReason::reconcile_with_output`].
    pub fn with_finish_reason(self, finish_reason: FinishReason) -> Self {
        self.with_optional_finish_reason(Some(finish_reason))
    }

    /// The text parts of [`Self::choice`], concatenated in order.
    pub fn text(&self) -> String {
        self.choice
            .iter()
            .filter_map(|part| match part {
                AssistantContent::Text(text) => Some(text.text.as_str()),
                _ => None,
            })
            .collect()
    }

    /// The reasoning text of [`Self::choice`], concatenated in order.
    /// Redacted reasoning has no text.
    pub fn reasoning(&self) -> String {
        self.choice
            .iter()
            .filter_map(|part| match part {
                AssistantContent::Reasoning(reasoning) => Some(reasoning.text.as_str()),
                _ => None,
            })
            .collect()
    }

    /// The assistant turn to append to the conversation: [`Self::choice`] in
    /// order with its origin and stop, or `None` for an
    /// empty choice.
    pub fn message(&self) -> Option<Message> {
        if self.choice.is_empty() {
            return None;
        }
        Some(Message::Assistant(AssistantMessage {
            content: self.choice.clone(),
            ..self.head()
        }))
    }

    /// The turn this response began, holding `content`, for a runtime that
    /// cut the reply short and answers its calls itself (an agent rolling a
    /// turn back over an invalid call). It keeps the origin, and stops to
    /// call tools, since the runtime answers them. A block keeps its provider
    /// item only when this response holds the same block with it. A response
    /// the provider did not end, or one the consumer has not wholly taken,
    /// holds no provider item, so its turn replays canonically.
    pub fn continued(&self, content: Vec<AssistantContent>) -> AssistantMessage {
        let content = content
            .into_iter()
            .map(|block| {
                if self.choice.contains(&block) {
                    block
                } else {
                    crate::operation::completion::canonical(block)
                }
            })
            .collect();
        AssistantMessage::rolled_back(Some(self.origin.clone()), content)
    }

    /// The turn's origin and stop with no content, for a
    /// runtime that carries the content separately.
    pub fn head(&self) -> AssistantMessage {
        AssistantMessage {
            content: Vec::new(),
            origin: Some(self.origin.clone()),
            stop: Some(self.stop()),
        }
    }

    /// The tool calls in [`Self::choice`], in order.
    pub fn tool_calls(&self) -> impl Iterator<Item = &ToolCall> {
        self.choice.iter().filter_map(|part| match part {
            AssistantContent::ToolCall(call) => Some(call),
            _ => None,
        })
    }

    /// Sets or clears the finish reason, reconciling a present reason with the choice.
    pub fn with_optional_finish_reason(mut self, finish_reason: Option<FinishReason>) -> Self {
        let has_tool_call = self
            .choice
            .iter()
            .any(|content| matches!(content, AssistantContent::ToolCall(_)));
        self.finish_reason =
            finish_reason.map(|reason| reason.reconcile_with_output(has_tool_call));
        self
    }
}

/// Deserialization shape routed through builders for finish-reason reconciliation
/// and empty-identifier normalization.
#[derive(Deserialize)]
struct CompletionResponseRepr {
    choice: Vec<AssistantContent>,
    usage: Usage,
    origin: Origin,
    #[serde(default)]
    error: Option<String>,
    #[serde(default)]
    aborted: Option<String>,
    #[serde(default)]
    provider_request_id: Option<String>,
    #[serde(default)]
    finish_reason: Option<FinishReason>,
    #[serde(default)]
    accepts_unknown_finish_reasons: bool,
    #[serde(default)]
    unfinished_calls: Vec<CallId>,
    raw: serde_json::Value,
}

impl From<CompletionResponseRepr> for CompletionResponse {
    fn from(repr: CompletionResponseRepr) -> Self {
        let CompletionResponseRepr {
            choice,
            usage,
            mut origin,
            error,
            aborted,
            provider_request_id,
            finish_reason,
            accepts_unknown_finish_reasons,
            unfinished_calls,
            raw,
        } = repr;
        use crate::provider_response::reported;
        origin.response_id = reported(origin.response_id);
        origin.response_model = reported(origin.response_model);
        let mut response =
            Self::new(choice, usage, origin, raw).with_optional_finish_reason(finish_reason);
        response.error = error;
        response.aborted = aborted;
        response.provider_request_id = reported(provider_request_id);
        response.accepts_unknown_finish_reasons = accepts_unknown_finish_reasons;
        response.unfinished_calls = unfinished_calls;
        response
    }
}

/// The token usage a provider reported for one completion.
///
/// Every provider mapping keeps one contract, so the counters read the same
/// way on every provider:
///
/// - `cached_input_tokens + cache_creation_input_tokens <= input_tokens`:
///   input counts every prompt token, cache reads and writes included.
/// - `reasoning_tokens <= output_tokens`: output counts every generated
///   token, reasoning included.
/// - `total_tokens == input_tokens + output_tokens`, absent unless both are
///   reported.
///
/// A counter the provider did not send is `None`; a reported zero is
/// `Some(0)`. Serialized as the same keys, absent when `None`.
///
/// ```
/// use rig_core::completion::Usage;
///
/// let usage = Usage::new().input_tokens(12).output_tokens(3).total_tokens(15);
/// assert_eq!(usage.input_tokens, Some(12));
/// assert!(usage.cost.is_none());
/// ```
#[non_exhaustive]
#[derive(Debug, Default, PartialEq, Clone, Copy, Serialize, Deserialize)]
pub struct Usage {
    /// Every input token of the request: uncached, read from a cache,
    /// written to a cache, and any prompt a provider's hosted tools added.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub input_tokens: Option<u64>,
    /// Every output token, reasoning included.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub output_tokens: Option<u64>,
    /// `input_tokens + output_tokens`; absent unless both are reported.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub total_tokens: Option<u64>,
    /// The part of `input_tokens` read from a provider-managed cache.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cached_input_tokens: Option<u64>,
    /// The part of `input_tokens` written to a provider-managed cache.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cache_creation_input_tokens: Option<u64>,
    /// The part of `input_tokens` a provider's hosted tools added to the prompt.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub tool_use_prompt_tokens: Option<u64>,
    /// The part of `output_tokens` spent on internal reasoning ("thinking",
    /// "thoughts").
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub reasoning_tokens: Option<u64>,
    /// What the turn cost in USD, when known. Never derived from the token
    /// counters here, and none of them is derived from it. A cost the
    /// provider reports is its figure. One priced from the model's catalog
    /// spec ([`Pricing::cost`](crate::catalog::Pricing::cost), from the
    /// facts the wire was connected with) is the
    /// standard-tier list price of the counted tokens: it leaves out the
    /// service tier, long-context price tiers and hosted-tool fees (web
    /// search, code execution), so it can be lower than the bill.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cost: Option<Cost>,
}

impl Usage {
    /// No counter and no cost reported.
    pub const fn new() -> Self {
        Self {
            input_tokens: None,
            output_tokens: None,
            total_tokens: None,
            cached_input_tokens: None,
            cache_creation_input_tokens: None,
            tool_use_prompt_tokens: None,
            reasoning_tokens: None,
            cost: None,
        }
    }

    /// Whether the provider reported any counter or a cost.
    pub fn is_reported(&self) -> bool {
        *self != Self::default()
    }

    /// The tokens the call read and wrote, what a conversation's next
    /// request sends again: [`Self::total_tokens`](field@Self::total_tokens),
    /// else the input and output tokens. `None` without input tokens.
    pub fn context_tokens(&self) -> Option<u64> {
        self.total_tokens.or_else(|| {
            Some(
                self.input_tokens?
                    .saturating_add(self.output_tokens.unwrap_or(0)),
            )
        })
    }

    /// Set, or with `None` clear, [`Self::input_tokens`](field@Self::input_tokens).
    pub fn input_tokens(mut self, tokens: impl Into<Option<u64>>) -> Self {
        self.input_tokens = tokens.into();
        self
    }

    /// Set, or with `None` clear, [`Self::output_tokens`](field@Self::output_tokens).
    pub fn output_tokens(mut self, tokens: impl Into<Option<u64>>) -> Self {
        self.output_tokens = tokens.into();
        self
    }

    /// Set, or with `None` clear, [`Self::total_tokens`](field@Self::total_tokens).
    pub fn total_tokens(mut self, tokens: impl Into<Option<u64>>) -> Self {
        self.total_tokens = tokens.into();
        self
    }

    /// Set, or with `None` clear,
    /// [`Self::cached_input_tokens`](field@Self::cached_input_tokens).
    pub fn cached_input_tokens(mut self, tokens: impl Into<Option<u64>>) -> Self {
        self.cached_input_tokens = tokens.into();
        self
    }

    /// Set, or with `None` clear,
    /// [`Self::cache_creation_input_tokens`](field@Self::cache_creation_input_tokens).
    pub fn cache_creation_input_tokens(mut self, tokens: impl Into<Option<u64>>) -> Self {
        self.cache_creation_input_tokens = tokens.into();
        self
    }

    /// Set, or with `None` clear,
    /// [`Self::tool_use_prompt_tokens`](field@Self::tool_use_prompt_tokens).
    pub fn tool_use_prompt_tokens(mut self, tokens: impl Into<Option<u64>>) -> Self {
        self.tool_use_prompt_tokens = tokens.into();
        self
    }

    /// Set, or with `None` clear, [`Self::reasoning_tokens`](field@Self::reasoning_tokens).
    pub fn reasoning_tokens(mut self, tokens: impl Into<Option<u64>>) -> Self {
        self.reasoning_tokens = tokens.into();
        self
    }

    /// Set, or with `None` clear, [`Self::cost`](field@Self::cost).
    pub fn cost(mut self, cost: impl Into<Option<Cost>>) -> Self {
        self.cost = cost.into();
        self
    }
}

/// What one or more turns cost, in USD. `total` is what was charged, or
/// when [`Self::is_complete`] is `false`, a lower bound of it.
///
/// A part is `None` when its source does not give it: a provider that
/// reports only a total leaves every part `None`, and one that reports
/// input and output leaves the cache parts `None`. A cost computed from
/// the catalog ([`Pricing::cost`](crate::catalog::Pricing::cost)) leaves a
/// cache part `None` when the catalog lists no rate for it and the usage
/// has such tokens; its `total` then sums the known parts only, and it is
/// not complete. A part is never filled with a placeholder `0.0`. Summing
/// costs keeps a part only when every side has it, and is complete only
/// when every side is. A `None` part is left out when serialized, and an
/// absent one reads back as `None`.
#[non_exhaustive]
#[derive(Clone, Copy, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct Cost {
    /// Uncached input tokens.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub input: Option<f64>,
    /// Output tokens, reasoning included.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub output: Option<f64>,
    /// Input tokens read from a cache.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cache_read: Option<f64>,
    /// Input tokens written to a cache.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cache_write: Option<f64>,
    /// The whole charge, or a lower bound of it when the cost is not
    /// complete.
    pub total: f64,
    /// Whether a part with tokens had no price, so `total` leaves it out.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    incomplete: bool,
}

impl Cost {
    /// Whether [`Self::total`](field@Self::total) is the whole charge.
    /// `false` when a part the usage has tokens for had no known price, so
    /// `total` is a lower bound.
    pub fn is_complete(&self) -> bool {
        !self.incomplete
    }

    /// A cost from the catalog's prices, where `None` marks a part whose
    /// tokens had no price: `total` sums the known parts, and the cost is
    /// complete only when no part is `None`.
    pub(crate) fn priced(
        input: f64,
        output: f64,
        cache_read: Option<f64>,
        cache_write: Option<f64>,
    ) -> Self {
        Self {
            input: Some(input),
            output: Some(output),
            cache_read,
            cache_write,
            total: input + output + cache_read.unwrap_or(0.0) + cache_write.unwrap_or(0.0),
            incomplete: cache_read.is_none() || cache_write.is_none(),
        }
    }

    /// A cost split into its parts, each known; `total` is their sum.
    pub fn from_parts(input: f64, output: f64, cache_read: f64, cache_write: f64) -> Self {
        Self {
            input: Some(input),
            output: Some(output),
            cache_read: Some(cache_read),
            cache_write: Some(cache_write),
            total: input + output + cache_read + cache_write,
            incomplete: false,
        }
    }

    /// A cost known only as its total; every part is `None`.
    pub fn from_total(total: f64) -> Self {
        Self {
            input: None,
            output: None,
            cache_read: None,
            cache_write: None,
            total,
            incomplete: false,
        }
    }

    /// Set, or with `None` clear, [`Self::input`](field@Self::input).
    /// `total` is left as it is.
    pub fn input(mut self, input: impl Into<Option<f64>>) -> Self {
        self.input = input.into();
        self
    }

    /// Set, or with `None` clear, [`Self::output`](field@Self::output).
    /// `total` is left as it is.
    pub fn output(mut self, output: impl Into<Option<f64>>) -> Self {
        self.output = output.into();
        self
    }

    /// Set, or with `None` clear, [`Self::cache_read`](field@Self::cache_read).
    /// `total` is left as it is.
    pub fn cache_read(mut self, cache_read: impl Into<Option<f64>>) -> Self {
        self.cache_read = cache_read.into();
        self
    }

    /// Set, or with `None` clear, [`Self::cache_write`](field@Self::cache_write).
    /// `total` is left as it is.
    pub fn cache_write(mut self, cache_write: impl Into<Option<f64>>) -> Self {
        self.cache_write = cache_write.into();
        self
    }
}

/// Sum one part of two costs: unknown when either side's is unknown, since
/// a known part plus an unknown one is not known.
fn add_part(lhs: Option<f64>, rhs: Option<f64>) -> Option<f64> {
    Some(lhs? + rhs?)
}

/// `total` always sums. Each part sums only when both sides know it, and is
/// `None` otherwise, so a summed part never understates what it covers. The
/// sum is complete only when both sides are.
impl Add for Cost {
    type Output = Self;

    fn add(self, other: Self) -> Self::Output {
        Self {
            input: add_part(self.input, other.input),
            output: add_part(self.output, other.output),
            cache_read: add_part(self.cache_read, other.cache_read),
            cache_write: add_part(self.cache_write, other.cache_write),
            total: self.total + other.total,
            incomplete: self.incomplete || other.incomplete,
        }
    }
}

/// Sum two counters where an unreported side does not turn a reported one
/// into "unreported".
fn add_counter(lhs: Option<u64>, rhs: Option<u64>) -> Option<u64> {
    match (lhs, rhs) {
        (None, None) => None,
        (lhs, rhs) => Some(lhs.unwrap_or(0) + rhs.unwrap_or(0)),
    }
}

impl Add for Usage {
    type Output = Self;

    fn add(mut self, other: Self) -> Self::Output {
        self += other;
        self
    }
}

/// Token counters add where an unreported side adds nothing. Cost sums only
/// when both sides have one: a turn whose cost is unknown makes the sum
/// unknown, rather than too low. A side that reports nothing at all
/// ([`Usage::is_reported`] is `false`) is the identity, so a fold from
/// [`Usage::default`] keeps its first turn's cost.
impl AddAssign for Usage {
    fn add_assign(&mut self, other: Self) {
        if !other.is_reported() {
            return;
        }
        if !self.is_reported() {
            *self = other;
            return;
        }
        self.cost = match (self.cost, other.cost) {
            (Some(lhs), Some(rhs)) => Some(lhs + rhs),
            _ => None,
        };
        self.input_tokens = add_counter(self.input_tokens, other.input_tokens);
        self.output_tokens = add_counter(self.output_tokens, other.output_tokens);
        self.total_tokens = add_counter(self.total_tokens, other.total_tokens);
        self.cached_input_tokens = add_counter(self.cached_input_tokens, other.cached_input_tokens);
        self.cache_creation_input_tokens = add_counter(
            self.cache_creation_input_tokens,
            other.cache_creation_input_tokens,
        );
        self.tool_use_prompt_tokens =
            add_counter(self.tool_use_prompt_tokens, other.tool_use_prompt_tokens);
        self.reasoning_tokens = add_counter(self.reasoning_tokens, other.reasoning_tokens);
    }
}

/// Many calls' [`Usage`] summed for a running account: the token counters,
/// the known cost, and how many calls the sum holds and how many of them
/// were not fully priced.
///
/// ```
/// use rig_core::completion::{Usage, UsageTotals};
///
/// let mut totals = UsageTotals::default();
/// totals.record(&Usage::new().input_tokens(100).output_tokens(20).total_tokens(120));
/// assert_eq!((totals.calls, totals.unpriced, totals.uncached_input()), (1, 1, 100));
/// ```
#[derive(Clone, Copy, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct UsageTotals {
    /// The token counters summed, with no cost: a call that did not
    /// report a counter adds nothing to it.
    pub tokens: Usage,
    /// The known costs summed, in USD.
    pub cost: f64,
    /// The calls whose cost is not known, or known only in part, so
    /// [`Self::cost`](field@Self::cost) is a lower bound when any.
    pub unpriced: u64,
    /// The calls summed.
    pub calls: u64,
}

impl UsageTotals {
    /// Adds a finished call's `usage`.
    pub fn record(&mut self, usage: &Usage) {
        self.calls += 1;
        match usage.cost {
            Some(cost) => {
                self.cost += cost.total;
                if !cost.is_complete() {
                    self.unpriced += 1;
                }
            }
            None => self.unpriced += 1,
        }
        self.tokens += usage.cost(None);
    }

    /// Adds what `other` summed.
    pub fn add(&mut self, other: &UsageTotals) {
        self.tokens += other.tokens;
        self.cost += other.cost;
        self.unpriced += other.unpriced;
        self.calls += other.calls;
    }

    /// Input tokens neither read from nor written to a cache.
    pub fn uncached_input(&self) -> u64 {
        self.tokens
            .input_tokens
            .unwrap_or(0)
            .saturating_sub(self.tokens.cached_input_tokens.unwrap_or(0))
            .saturating_sub(self.tokens.cache_creation_input_tokens.unwrap_or(0))
    }

    /// The tokens read and written, cached input included.
    pub fn total_tokens(&self) -> u64 {
        self.tokens
            .input_tokens
            .unwrap_or(0)
            .saturating_add(self.tokens.output_tokens.unwrap_or(0))
    }

    /// The cost as `$0.123`, ending in `+` when some calls were not priced,
    /// or `None` when no call was.
    pub fn cost_label(&self) -> Option<String> {
        if self.unpriced >= self.calls {
            return None;
        }
        let more = if self.unpriced > 0 { "+" } else { "" };
        Some(format!("{}{more}", dollars_label(self.cost)))
    }

    /// The [cost](Self::cost_label), or as `1.2M tokens` when no call was
    /// priced, such as a local or subscription model's.
    pub fn cost_or_tokens(&self) -> String {
        self.cost_label()
            .unwrap_or_else(|| format!("{} tokens", tokens_label(self.total_tokens())))
    }
}

/// One line for a person or a log: the calls, the tokens by kind and the
/// cost.
impl std::fmt::Display for UsageTotals {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self.calls {
            1 => f.write_str("1 model call")?,
            calls => write!(f, "{calls} model calls")?,
        }
        write!(f, ": {} in", tokens_label(self.uncached_input()))?;
        if let Some(read) = self.tokens.cached_input_tokens.filter(|read| *read > 0) {
            write!(f, ", {} cache read", tokens_label(read))?;
        }
        if let Some(written) = self
            .tokens
            .cache_creation_input_tokens
            .filter(|written| *written > 0)
        {
            write!(f, ", {} cache written", tokens_label(written))?;
        }
        write!(
            f,
            ", {} out",
            tokens_label(self.tokens.output_tokens.unwrap_or(0))
        )?;
        if let Some(thought) = self.tokens.reasoning_tokens.filter(|thought| *thought > 0) {
            write!(f, " ({} reasoning)", tokens_label(thought))?;
        }
        let cost = self.cost_label();
        write!(f, "; {}", cost.as_deref().unwrap_or("cost unknown"))
    }
}

/// The context a conversation's next request sends, against the model's
/// input limit.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct ContextUse {
    /// Tokens in use.
    pub tokens: u64,
    /// The model's input limit, when known.
    pub limit: Option<u32>,
}

impl ContextUse {
    /// The share of the input limit in use, in percent, when the limit is
    /// known.
    pub fn percent(&self) -> Option<u64> {
        self.limit
            .filter(|limit| *limit > 0)
            .map(|limit| self.tokens.saturating_mul(100) / u64::from(limit))
    }
}

/// `45k/200k (22%)`, or `45k` when the input limit is not known.
impl std::fmt::Display for ContextUse {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match (self.limit, self.percent()) {
            (Some(limit), Some(percent)) => write!(
                f,
                "{}/{} ({percent}%)",
                tokens_label(self.tokens),
                tokens_label(u64::from(limit))
            ),
            _ => f.write_str(&tokens_label(self.tokens)),
        }
    }
}

/// A token count in at most four characters plus a unit: `999`, `1.2k`,
/// `45k`, `1.2M`.
pub fn tokens_label(count: u64) -> String {
    // Shown rounded, so the float conversion's precision does not matter.
    let scaled = |unit: f64| count as f64 / unit;
    match count {
        0..1_000 => count.to_string(),
        1_000..10_000 => format!("{:.1}k", scaled(1e3)),
        10_000..1_000_000 => format!("{:.0}k", scaled(1e3)),
        1_000_000..10_000_000 => format!("{:.1}M", scaled(1e6)),
        _ => format!("{:.0}M", scaled(1e6)),
    }
}

/// A cost in USD: tenths of a cent below a dollar, cents above.
fn dollars_label(cost: f64) -> String {
    if cost < 1.0 {
        format!("${cost:.3}")
    } else {
        format!("${cost:.2}")
    }
}

/// Model capabilities used by runtimes when preparing requests.
/// Defaults are conservative; construct through [`Self::new`] and setters.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
pub struct ProviderCapabilities {
    /// Whether native structured output can remain enabled with tool calls
    /// without suppressing them. Defaults to `false`.
    pub composes_native_output_with_tools: bool,
    /// Whether the model answers a forced tool choice (`Required` or
    /// `Specific`) with an error. Rig then does not force the output tool
    /// of its own structured-output flow (the extractor). Defaults to `false`.
    #[serde(default, skip_serializing_if = "crate::json_utils::is_false")]
    pub rejects_forced_tool_choice: bool,
}

impl ProviderCapabilities {
    /// Create the conservative capability set used by default.
    pub const fn new() -> Self {
        Self {
            composes_native_output_with_tools: false,
            rejects_forced_tool_choice: false,
        }
    }

    /// Declare whether native structured output composes with tool calls.
    pub const fn with_native_output_tool_composition(mut self, supported: bool) -> Self {
        self.composes_native_output_with_tools = supported;
        self
    }

    /// Declare whether the model rejects a forced tool choice.
    pub const fn with_forced_tool_choice_rejected(mut self, rejected: bool) -> Self {
        self.rejects_forced_tool_choice = rejected;
        self
    }
}

/// A completion request to any provider's model.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct CompletionRequest {
    /// Optional model override for this request.
    pub model: Option<String>,
    /// The chat history to be sent to the completion model provider.
    /// The very last message is the prompt.
    ///
    /// It must hold at least one message, and every user and assistant
    /// message must carry content. The field is public, so this is a rule
    /// rather than a type guarantee: [`Self::validate_message_content`]
    /// checks it at the request boundary.
    ///
    /// Each message is shared, with the conversation it came from and the
    /// records of the request, so copying a request copies pointers.
    pub chat_history: Vec<Arc<Message>>,
    /// The documents to be sent to the completion model provider
    pub documents: Vec<Document>,
    /// The tools to be sent to the completion model provider, each shared,
    /// so copying a request copies pointers.
    pub tools: Vec<Arc<ToolDefinition>>,
    /// The temperature to be sent to the completion model provider
    pub temperature: Option<f64>,
    /// The max tokens to be sent to the completion model provider
    pub max_tokens: Option<u64>,
    /// Which tools the model may or must call before it answers.
    pub tool_choice: Option<ToolChoice>,
    /// Additional provider-specific parameters to be sent to the completion model provider
    pub additional_params: Option<serde_json::Value>,
    /// Optional JSON Schema for structured output. When set, providers that support
    /// native structured outputs will constrain the model's response to match this schema.
    pub output_schema: Option<schemars::Schema>,
    /// Opt-in for sensitive request, response, and tool-content telemetry.
    /// Defaults to `false` and is excluded from serialization. Enabling it can
    /// expose prompts, context, tool results, and model output in span attributes
    /// and increase telemetry storage costs. Requires explicit caller consent.
    /// Agent drivers record normalized content; direct provider coverage varies,
    /// especially for streams consumed after the provider returns.
    #[serde(skip)]
    pub record_telemetry_content: bool,
    /// Whether a finish reason outside the normalized vocabulary
    /// ([`FinishReason::Other`]) ends the turn as a normal stop instead of a
    /// failure. Defaults to `false`. The response carries the choice, so its
    /// [`CompletionResponse::stop`], the runtimes and history replay agree.
    /// `Other` also holds genuine failures, such as a malformed tool call or a
    /// recitation block, so with this set the tool calls of such a reply run.
    /// [`FinishReason::ContentFilter`] still fails the turn.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub accept_unknown_finish_reasons: bool,
    /// Send other models' reasoning in the history as reasoning where the
    /// target reads it ([`Accepts::foreign_reasoning`]), instead of as plain
    /// text. Defaults to `false`.
    ///
    /// [`Accepts::foreign_reasoning`]: crate::completion::Accepts::foreign_reasoning
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub foreign_reasoning: bool,
    /// Portable generation options. Precedence, lowest first: the mapped
    /// options, then [`Self::provider_options`], then `additional_params`.
    #[serde(default, skip_serializing_if = "GenerationOptions::is_default")]
    pub options: GenerationOptions,
    /// Typed per-provider options. The wire reads only the entry of its own
    /// provider, above the mapped options and below `additional_params`.
    #[serde(default, skip_serializing_if = "ProviderOptions::is_empty")]
    pub provider_options: ProviderOptions,
    /// Where a provider that caches prompts by marker (Anthropic's Messages
    /// family, OpenAI's Responses API from GPT-5.6 on) may mark the end of a
    /// stable prefix that later requests repeat, beside its own markers, so
    /// content after it (per-turn memory, a reminder) does not cost the
    /// cached prefix. A provider that takes fewer markers keeps the points
    /// furthest into the request; one that caches prefixes without markers
    /// ignores them. A provider that marks only some parts of a request moves
    /// a point back to the last part it can mark. Empty marks nothing.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub cache_points: Vec<CachePoint>,
}

/// A point in a [`CompletionRequest`] that ends a stable prefix, for
/// [`CompletionRequest::cache_points`]. Prefixes run in the order a request
/// is sent: tools, then the system prompt, then the messages.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum CachePoint {
    /// After the tool definitions.
    Tools,
    /// After the system prompt.
    System,
    /// After the first `n` user and assistant messages. System messages
    /// are not counted, wherever they sit; `Messages(0)` is [`Self::System`].
    /// The point names the request's messages as written: adapting them
    /// for a wire, which drops some and joins adjacent user messages, moves
    /// the point with them, inside a joined message when it ends there.
    Messages(usize),
    /// After the first `items` content items of the user or assistant
    /// message at `message`, counted as [`Self::Messages`] counts them.
    Within {
        /// The message, from 0, system messages not counted.
        message: usize,
        /// How many of its content items the prefix holds.
        items: usize,
    },
}

impl CompletionRequest {
    /// The system instructions of this request: the content of the leading
    /// [`Message::System`] in `chat_history`, which is where
    /// [`Self::preamble`] places it.
    pub fn system_instructions(&self) -> Option<&str> {
        match self.chat_history.first().map(Arc::as_ref) {
            Some(Message::System { content }) => Some(content.as_str()),
            _ => None,
        }
    }

    /// Reject a request with no messages, a user or assistant message with no
    /// content, or a tool result with no content blocks. The error is
    /// [`ProviderError::Request`] and names the role and index of the first
    /// offending message.
    ///
    /// Every wire rejects an empty turn, so this turns a remote 400 into a
    /// local error. It checks the request direction only: a provider may
    /// return empty assistant content, which the reply keeps and the
    /// runtime judges. `System` content is a
    /// `String` and is not checked. A tool result holding one empty text
    /// block is not empty.
    ///
    /// [`Model::call`](crate::driver::Model::call),
    /// [`Model::stream`](crate::driver::Model::stream) and their `_observed`
    /// twins run it before encoding, so it covers
    /// [`DynModel`](crate::DynModel), every model a handler serves and the
    /// agent runtimes built on them. The OpenAI Responses websocket session
    /// sends without the driver and runs it on each send. Code that encodes
    /// a request some other way should call it first.
    pub fn validate_message_content(&self) -> Result<(), ProviderError> {
        if self.chat_history.is_empty() {
            return Err(ProviderError::request(
                "request has an empty chat history; providers require at least one message",
            ));
        }

        let empty_message = |role: &str, index: usize| {
            ProviderError::request(format!(
                "{role} message at index {index} has no content; \
                 providers reject empty content blocks"
            ))
        };

        for (index, message) in self.chat_history.iter().enumerate() {
            match &**message {
                Message::System { .. } => {}
                Message::Assistant(AssistantMessage { content, .. }) => {
                    if content.is_empty() {
                        return Err(empty_message("assistant", index));
                    }
                }
                Message::User { content } => {
                    if content.is_empty() {
                        return Err(empty_message("user", index));
                    }
                }
            }
        }

        Ok(())
    }

    /// The output schema's `"title"`, else `"response_schema"`: a name for
    /// providers that need one beside the JSON Schema (such as OpenAI).
    pub fn output_schema_name(&self) -> Option<String> {
        self.output_schema.as_ref().map(|schema| {
            schema
                .as_object()
                .and_then(|o| o.get("title"))
                .and_then(|v| v.as_str())
                .unwrap_or("response_schema")
                .to_string()
        })
    }

    /// Returns documents normalized into a message (if any).
    /// Most providers do not accept documents directly as input, so it needs to convert into a
    /// `Message` so that it can be incorporated into `chat_history`.
    pub fn normalized_documents(&self) -> Option<Message> {
        Self::normalized_documents_from(&self.documents)
    }

    fn normalized_documents_from(documents: &[Document]) -> Option<Message> {
        if documents.is_empty() {
            return None;
        }

        let content = documents
            .iter()
            .map(|doc| UserContent::document_text(doc.to_string(), Some(DocumentMediaType::TXT)))
            .collect();

        Some(Message::User { content })
    }
}

/// Place the documents message `message` at the first non-system position,
/// so document context lands after any leading system messages. A user
/// message already there takes the documents at its front instead, so the
/// history keeps alternating roles. Telemetry and the sent request must
/// agree on this placement.
pub(crate) fn insert_after_leading_system(chat_history: &mut Vec<Arc<Message>>, message: Message) {
    let insert_at = chat_history
        .iter()
        .position(|message| !matches!(&**message, Message::System { .. }))
        .unwrap_or(chat_history.len());
    let joins =
        |at: &&mut Arc<Message>| matches!(&***at, Message::User { content } if !content.is_empty());
    match (
        chat_history
            .get_mut(insert_at)
            .filter(joins)
            .map(Arc::make_mut),
        message,
    ) {
        (Some(Message::User { content }), Message::User { content: documents }) => {
            content.splice(0..0, documents);
        }
        (_, message) => chat_history.insert(insert_at, Arc::new(message)),
    }
}

fn merge_provider_tools_into_additional_params(
    additional_params: Option<serde_json::Value>,
    provider_tools: Vec<ProviderToolDefinition>,
) -> Option<serde_json::Value> {
    if provider_tools.is_empty() {
        return additional_params;
    }

    let mut provider_tools_json = provider_tools
        .into_iter()
        .map(|ProviderToolDefinition { kind, mut config }| {
            // Force the provider tool type from the strongly-typed field.
            config.insert("type".to_string(), serde_json::Value::String(kind));
            serde_json::Value::Object(config)
        })
        .collect::<Vec<_>>();

    let mut params_map = match additional_params {
        Some(serde_json::Value::Object(map)) => map,
        Some(serde_json::Value::Bool(stream)) => {
            let mut map = serde_json::Map::new();
            map.insert("stream".to_string(), serde_json::Value::Bool(stream));
            map
        }
        _ => serde_json::Map::new(),
    };

    let mut merged_tools = match remove_preserving_order(&mut params_map, "tools") {
        Some(serde_json::Value::Array(existing)) => existing,
        _ => Vec::new(),
    };
    merged_tools.append(&mut provider_tools_json);
    params_map.insert("tools".to_string(), serde_json::Value::Array(merged_tools));
    Some(serde_json::Value::Object(params_map))
}

impl CompletionRequest {
    /// A request whose conversation is the one user message `prompt`, with
    /// no preamble, documents or tools. The setters below add to it and
    /// check nothing; [`Self::validate_message_content`] checks the content
    /// when the request is sent.
    ///
    /// Each setter changes the request's public fields as it is called, so
    /// order matters where two setters touch the same field: a second
    /// [`Self::preamble`] adds a second system message, and
    /// [`Self::additional_params`] with a `tools` key (or `None`) replaces
    /// provider tools added before it. Set `additional_params` first.
    ///
    /// ```
    /// use rig_core::completion::CompletionRequest;
    ///
    /// let request = CompletionRequest::new("Who are you?")
    ///     .preamble("You are a concise assistant.")
    ///     .temperature(0.5);
    /// assert_eq!(request.chat_history.len(), 2);
    /// assert_eq!(request.temperature, Some(0.5));
    /// ```
    pub fn new(prompt: impl Into<Message>) -> Self {
        Self::conversation(vec![Arc::new(prompt.into())])
    }

    /// A request for `chat_history` as given, with nothing else set.
    fn conversation(chat_history: Vec<Arc<Message>>) -> Self {
        Self {
            model: None,
            chat_history,
            documents: Vec::new(),
            tools: Vec::new(),
            temperature: None,
            max_tokens: None,
            tool_choice: None,
            additional_params: None,
            output_schema: None,
            record_telemetry_content: false,
            accept_unknown_finish_reasons: false,
            foreign_reasoning: false,
            options: GenerationOptions::default(),
            provider_options: ProviderOptions::default(),
            cache_points: Vec::new(),
        }
    }

    /// Put `preamble` first in the conversation, as a [`Message::System`],
    /// ahead of any system message already there.
    pub fn preamble(mut self, preamble: impl Into<String>) -> Self {
        self.chat_history
            .insert(0, Arc::new(Message::system(preamble.into())));
        self
    }

    /// Override the model for this request.
    pub fn model<S: Into<String>>(mut self, model: impl Into<Option<S>>) -> Self {
        self.model = model.into().map(Into::into);
        self.warn_if_shadowed("model", self.model.is_some());
        self
    }

    /// Add `message` to the conversation, before the prompt (its last
    /// message).
    pub fn message(self, message: impl Into<Arc<Message>>) -> Self {
        self.messages([message])
    }

    /// Add `messages` to the conversation in order, before the prompt (its
    /// last message).
    pub fn messages(mut self, messages: impl IntoIterator<Item = impl Into<Arc<Message>>>) -> Self {
        let prompt = self.chat_history.pop();
        self.chat_history
            .extend(messages.into_iter().map(Into::into));
        self.chat_history.extend(prompt);
        self
    }

    /// Add a document.
    pub fn document(mut self, document: Document) -> Self {
        self.documents.push(document);
        self
    }

    /// Add documents in order.
    pub fn documents(mut self, documents: impl IntoIterator<Item = Document>) -> Self {
        self.documents.extend(documents);
        self
    }

    /// Add a tool.
    pub fn tool(self, tool: impl Into<Arc<ToolDefinition>>) -> Self {
        self.tools([tool])
    }

    /// Add tools in order.
    pub fn tools(
        mut self,
        tools: impl IntoIterator<Item = impl Into<Arc<ToolDefinition>>>,
    ) -> Self {
        let first = self.tools.is_empty();
        self.tools.extend(tools.into_iter().map(Into::into));
        self.warn_if_shadowed("tools", first && !self.tools.is_empty());
        self
    }

    /// Add a provider-hosted tool: appended to `additional_params.tools`,
    /// so a later [`Self::additional_params`] with a `tools` key replaces
    /// it.
    pub fn provider_tool(self, tool: ProviderToolDefinition) -> Self {
        self.provider_tools(vec![tool])
    }

    /// Add provider-hosted tools in order: appended to
    /// `additional_params.tools`.
    pub fn provider_tools(mut self, tools: Vec<ProviderToolDefinition>) -> Self {
        self.additional_params =
            merge_provider_tools_into_additional_params(self.additional_params.take(), tools);
        self
    }

    /// Merge provider-specific parameters into the request's, key by key;
    /// `None` clears them, provider tools included. Provider conversion
    /// determines precedence over typed fields, and a key that overrides a
    /// typed field this request sets is logged.
    pub fn additional_params(
        mut self,
        additional_params: impl Into<Option<serde_json::Value>>,
    ) -> Self {
        let additional_params = additional_params.into();
        for key in shadowed_typed_fields(
            additional_params.as_ref(),
            &[
                ("temperature", self.temperature.is_some()),
                ("max_tokens", self.max_tokens.is_some()),
                ("tool_choice", self.tool_choice.is_some()),
                ("model", self.model.is_some()),
                ("tools", !self.tools.is_empty()),
                ("response_format", self.output_schema.is_some()),
            ],
        ) {
            warn_shadowed(key);
        }
        self.additional_params =
            json_utils::merge_params(self.additional_params.take(), additional_params);
        self
    }

    /// Set, or with `None` clear, the temperature.
    pub fn temperature(mut self, temperature: impl Into<Option<f64>>) -> Self {
        self.temperature = temperature.into();
        self.warn_if_shadowed("temperature", self.temperature.is_some());
        self
    }

    /// Set, or with `None` clear, the output-token limit. Provider-specific
    /// defaults and requirements apply.
    pub fn max_tokens(mut self, max_tokens: impl Into<Option<u64>>) -> Self {
        self.max_tokens = max_tokens.into();
        self.warn_if_shadowed("max_tokens", self.max_tokens.is_some());
        self
    }

    /// Set the tool-selection policy.
    pub fn tool_choice(mut self, tool_choice: ToolChoice) -> Self {
        self.tool_choice = Some(tool_choice);
        self.warn_if_shadowed("tool_choice", true);
        self
    }

    /// Set, or with `None` clear, a native structured-output schema for
    /// providers that support one. The returned content is not
    /// deserialized.
    pub fn output_schema(mut self, schema: impl Into<Option<schemars::Schema>>) -> Self {
        self.output_schema = schema.into();
        self.warn_if_shadowed("response_format", self.output_schema.is_some());
        self
    }

    /// Opt in to sensitive content telemetry, off by default. See
    /// [`Self::record_telemetry_content`] for what that exposes.
    pub fn record_content_telemetry(mut self, enabled: bool) -> Self {
        self.record_telemetry_content = enabled;
        self
    }

    /// Accept, or with `false` refuse, finish reasons outside the normalized
    /// vocabulary as a normal stop. See
    /// [`Self::accept_unknown_finish_reasons`] for what that lets through.
    ///
    /// [`Self::accept_unknown_finish_reasons`]: field@Self::accept_unknown_finish_reasons
    pub fn accept_unknown_finish_reasons(mut self, accept: bool) -> Self {
        self.accept_unknown_finish_reasons = accept;
        self
    }

    /// Replace the portable generation options with `options`, a reusable
    /// value. Calls apply in order: this replaces every field, so a
    /// shortcut such as [`Self::seed`] called before it is lost, and one
    /// called after it sets its one field on top.
    ///
    /// ```
    /// use rig_core::completion::{CompletionRequest, Effort, GenerationOptions};
    ///
    /// let shared = GenerationOptions::new().reasoning(Effort::High).seed(1);
    /// let request = CompletionRequest::new("hi").seed(7).options(shared.clone()).seed(2);
    /// assert_eq!(request.options, shared.seed(2));
    /// ```
    pub fn options(mut self, options: GenerationOptions) -> Self {
        self.options = options;
        self
    }

    /// Set the reasoning level or budget in [`Self::options`](field@Self::options), as
    /// [`GenerationOptions::reasoning`](GenerationOptions::reasoning) does,
    /// keeping its other fields. See
    /// [`Self::options`](method@Self::options) for the order of calls.
    pub fn reasoning(mut self, reasoning: impl Into<Reasoning>) -> Self {
        self.options = std::mem::take(&mut self.options).reasoning(reasoning);
        self
    }

    /// Set the cache retention in [`Self::options`](field@Self::options), as
    /// [`GenerationOptions::cache`](GenerationOptions::cache) does,
    /// keeping its other fields. See
    /// [`Self::options`](method@Self::options) for the order of calls.
    pub fn cache(mut self, cache: CacheRetention) -> Self {
        self.options = std::mem::take(&mut self.options).cache(cache);
        self
    }

    /// Set the service tier in [`Self::options`](field@Self::options), as
    /// [`GenerationOptions::service_tier`](GenerationOptions::service_tier) does,
    /// keeping its other fields. See
    /// [`Self::options`](method@Self::options) for the order of calls.
    pub fn service_tier(mut self, tier: ServiceTier) -> Self {
        self.options = std::mem::take(&mut self.options).service_tier(tier);
        self
    }

    /// Set the answer verbosity in [`Self::options`](field@Self::options), as
    /// [`GenerationOptions::verbosity`](GenerationOptions::verbosity) does,
    /// keeping its other fields. See
    /// [`Self::options`](method@Self::options) for the order of calls.
    pub fn verbosity(mut self, verbosity: Verbosity) -> Self {
        self.options = std::mem::take(&mut self.options).verbosity(verbosity);
        self
    }

    /// Set whether the model may call several tools in one turn in
    /// [`Self::options`](field@Self::options), as
    /// [`GenerationOptions::parallel_tool_calls`] does, keeping its other
    /// fields. See
    /// [`Self::options`](method@Self::options) for the order of calls.
    pub fn parallel_tool_calls(mut self, parallel: bool) -> Self {
        self.options = std::mem::take(&mut self.options).parallel_tool_calls(parallel);
        self
    }

    /// Set the nucleus sampling probability mass in [`Self::options`](field@Self::options), as
    /// [`GenerationOptions::top_p`](GenerationOptions::top_p) does,
    /// keeping its other fields. See
    /// [`Self::options`](method@Self::options) for the order of calls.
    pub fn top_p(mut self, top_p: f64) -> Self {
        self.options = std::mem::take(&mut self.options).top_p(top_p);
        self
    }

    /// Set the sampling seed in [`Self::options`](field@Self::options), as
    /// [`GenerationOptions::seed`](GenerationOptions::seed) does,
    /// keeping its other fields. See
    /// [`Self::options`](method@Self::options) for the order of calls.
    pub fn seed(mut self, seed: u64) -> Self {
        self.options = std::mem::take(&mut self.options).seed(seed);
        self
    }

    /// Set the stop sequences in [`Self::options`](field@Self::options), as
    /// [`GenerationOptions::stop`](GenerationOptions::stop) does,
    /// keeping its other fields. See
    /// [`Self::options`](method@Self::options) for the order of calls.
    pub fn stop<S: Into<String>>(mut self, stop: impl IntoIterator<Item = S>) -> Self {
        self.options = std::mem::take(&mut self.options).stop(stop);
        self
    }

    /// Set what happens to an option the wire or model cannot honour in
    /// [`Self::options`](field@Self::options), as
    /// [`GenerationOptions::on_unsupported`] does, keeping its other fields. See
    /// [`Self::options`](method@Self::options) for the order of calls.
    pub fn on_unsupported(mut self, policy: OnUnsupported) -> Self {
        self.options = std::mem::take(&mut self.options).on_unsupported(policy);
        self
    }

    /// Replace the typed per-provider options.
    ///
    /// Calls apply in order: this replaces every entry, so an entry set by
    /// an earlier [`Self::provider_option`] is lost, and a later
    /// [`Self::provider_option`] replaces its provider's entry on top.
    pub fn provider_options(mut self, options: ProviderOptions) -> Self {
        self.provider_options = options;
        self
    }

    /// Store `options` as the entry of their provider
    /// ([`ExtensionOptions::Ext`]), replacing that provider's entry and
    /// keeping every other, as [`ProviderOptions::set`] does. Options that
    /// do not serialize fail the request's encode.
    ///
    /// The entry is always stored under `O::Ext`'s key, the built-in
    /// provider the options type belongs to. A third-party provider whose
    /// extension reuses a built-in options type (say `OpenAiOptions` for an
    /// OpenAI-compatible gateway) must store them with
    /// [`ProviderOptions::with::<P>`](ProviderOptions::with) instead, or its
    /// wire never reads them.
    ///
    /// ```
    /// use rig_core::completion::{CompletionRequest, ProviderOptions};
    /// use rig_core::providers::openrouter::extension::{
    ///     OpenRouterExt, OpenRouterOptions, ProviderPreferences,
    /// };
    ///
    /// let request = CompletionRequest::new("hi").provider_option(
    ///     OpenRouterOptions::new().provider(ProviderPreferences::new().allow_fallbacks(false)),
    /// );
    /// assert!(request.provider_options.contains::<OpenRouterExt>());
    /// ```
    pub fn provider_option<O: ExtensionOptions>(mut self, options: O) -> Self {
        self.provider_options = std::mem::take(&mut self.provider_options).set(options);
        self
    }

    /// The input messages telemetry records: the conversation with the
    /// documents inserted after any leading system messages.
    pub fn messages_for_telemetry(&self) -> Vec<Arc<Message>> {
        let mut messages = self.chat_history.clone();
        if let Some(documents) = self.normalized_documents() {
            insert_after_leading_system(&mut messages, documents);
        }
        messages
    }

    /// Log a typed field `key` that `additional_params` already overrides.
    fn warn_if_shadowed(&self, key: &'static str, set: bool) {
        if !shadowed_typed_fields(self.additional_params.as_ref(), &[(key, set)]).is_empty() {
            warn_shadowed(key);
        }
    }
}

fn warn_shadowed(key: &str) {
    if matches!(key, "tools" | "response_format") {
        tracing::warn!(
            key,
            "additional_params also carries `{key}`; the provider decides how it combines with the typed field"
        );
    } else {
        tracing::warn!(
            key,
            "additional_params overrides the typed `{key}` field set on the same request"
        );
    }
}

impl From<&str> for CompletionRequest {
    fn from(prompt: &str) -> Self {
        Self::new(prompt)
    }
}

impl From<String> for CompletionRequest {
    fn from(prompt: String) -> Self {
        Self::new(prompt)
    }
}

impl From<Message> for CompletionRequest {
    fn from(prompt: Message) -> Self {
        Self::new(prompt)
    }
}

/// The conversation as given, ending with the prompt. An empty one fails
/// [`CompletionRequest::validate_message_content`].
impl From<Vec<Message>> for CompletionRequest {
    fn from(chat_history: Vec<Message>) -> Self {
        Self::conversation(chat_history.into_iter().map(Arc::new).collect())
    }
}

/// The passthrough keys that will override a typed field the caller also set.
/// The override itself is the documented precedence (see
/// [`CompletionRequest::additional_params`]); naming the collisions
/// makes an accidental one visible instead of silent.
pub(crate) fn shadowed_typed_fields<'a>(
    additional_params: Option<&serde_json::Value>,
    typed: &[(&'a str, bool)],
) -> Vec<&'a str> {
    let Some(serde_json::Value::Object(params)) = additional_params else {
        return Vec::new();
    };
    typed
        .iter()
        .filter(|(key, set)| *set && params.contains_key(*key))
        .map(|(key, _)| *key)
        .collect()
}

#[cfg(test)]
mod tests;

#[cfg(test)]
mod response_identity_tests;

#[cfg(test)]
mod plain_value_tests;