dynamo_protocols/types/

chat.rs

// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0
//
// Re-exports upstream async-openai chat types and defines inference-serving
// extensions on top. Types prefixed with `Dynamo` or entirely absent from the
// upstream spec are documented with the rationale for the extension.

use std::pin::Pin;

use derive_builder::Builder;
use futures::Stream;
use serde::{Deserialize, Serialize};
use url::Url;
use uuid::Uuid;

use crate::error::OpenAIError;

// ---------------------------------------------------------------------------
// Re-exports from upstream async-openai (unchanged types)
// ---------------------------------------------------------------------------
// These types are structurally identical to the upstream definitions.
// Consumers should use them via `dynamo_protocols::types::*` as before.

pub use async_openai::types::chat::{
    ChatCompletionAudio, ChatCompletionAudioFormat, ChatCompletionAudioVoice,
    ChatCompletionFunctionCall, ChatCompletionFunctions, ChatCompletionFunctionsArgs,
    ChatCompletionRequestAssistantMessageAudio, ChatCompletionRequestAssistantMessageContent,
    ChatCompletionRequestAssistantMessageContentPart, ChatCompletionRequestDeveloperMessage,
    ChatCompletionRequestDeveloperMessageArgs, ChatCompletionRequestDeveloperMessageContent,
    ChatCompletionRequestFunctionMessage, ChatCompletionRequestFunctionMessageArgs,
    ChatCompletionRequestMessageContentPartAudio, ChatCompletionRequestMessageContentPartRefusal,
    ChatCompletionRequestMessageContentPartText, ChatCompletionRequestSystemMessageContent,
    ChatCompletionRequestSystemMessageContentPart, ChatCompletionResponseMessageAudio, Choice,
    CompletionFinishReason, CompletionTokensDetails, CompletionUsage, FunctionObject,
    FunctionObjectArgs, ImageDetail, InputAudio, InputAudioFormat, Logprobs, PredictionContent,
    PredictionContentContent, Prompt, PromptTokensDetails, ResponseFormat,
    ResponseFormatJsonSchema, Role, ServiceTier, TopLogprobs, WebSearchContextSize,
    WebSearchLocation, WebSearchOptions, WebSearchUserLocation, WebSearchUserLocationType,
};

/// OpenAI stop configuration, with Dynamo's token-id stop extension.
///
/// The standard OpenAI shape accepts a string or string array. Dynamo also
/// accepts an integer array, e.g. `"stop": [576]`, to express token-id stop
/// conditions for tokenized in/out workflows. Strings like `"token_id:576"`
/// remain ordinary string stops; the `token_id:<id>` format is only an output
/// display format for logprobs.
#[derive(Debug, Deserialize, Serialize, Clone, PartialEq)]
#[serde(untagged)]
pub enum Stop {
    String(String),
    StringArray(Vec<String>),
    TokenIdArray(Vec<u32>),
}

impl Stop {
    pub fn strings(&self) -> Option<Vec<String>> {
        match self {
            Stop::String(s) => Some(vec![s.clone()]),
            Stop::StringArray(arr) => Some(arr.clone()),
            Stop::TokenIdArray(_) => None,
        }
    }

    pub fn token_ids(&self) -> Option<Vec<u32>> {
        match self {
            Stop::TokenIdArray(arr) => Some(arr.clone()),
            Stop::String(_) | Stop::StringArray(_) => None,
        }
    }
}

impl From<String> for Stop {
    fn from(value: String) -> Self {
        Stop::String(value)
    }
}

impl From<&str> for Stop {
    fn from(value: &str) -> Self {
        Stop::String(value.to_string())
    }
}

impl From<Vec<String>> for Stop {
    fn from(value: Vec<String>) -> Self {
        Stop::StringArray(value)
    }
}

impl From<Vec<u32>> for Stop {
    fn from(value: Vec<u32>) -> Self {
        Stop::TokenIdArray(value)
    }
}

impl From<async_openai::types::chat::StopConfiguration> for Stop {
    fn from(value: async_openai::types::chat::StopConfiguration) -> Self {
        match value {
            async_openai::types::chat::StopConfiguration::String(value) => Stop::String(value),
            async_openai::types::chat::StopConfiguration::StringArray(value) => {
                Stop::StringArray(value)
            }
        }
    }
}

// Upstream renamed FinishReason (streaming) -- re-export
pub use async_openai::types::chat::FinishReason;

// Upstream uses FunctionType where we used ChatCompletionToolType.
// Re-export both names for compatibility.
pub use async_openai::types::chat::FunctionType;

/// Reasoning effort values accepted by OpenAI-compatible clients.
///
/// async-openai versions used by some Dynamo builds do not include `max`, but
/// DeepSeek-V4 compatible clients may send it by default. Keep this local enum
/// wire-compatible with upstream values and include `max`.
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum ReasoningEffort {
    None,
    Minimal,
    Low,
    Medium,
    High,
    Xhigh,
    Max,
}

impl From<async_openai::types::chat::ReasoningEffort> for ReasoningEffort {
    fn from(value: async_openai::types::chat::ReasoningEffort) -> Self {
        match value {
            async_openai::types::chat::ReasoningEffort::None => ReasoningEffort::None,
            async_openai::types::chat::ReasoningEffort::Minimal => ReasoningEffort::Minimal,
            async_openai::types::chat::ReasoningEffort::Low => ReasoningEffort::Low,
            async_openai::types::chat::ReasoningEffort::Medium => ReasoningEffort::Medium,
            async_openai::types::chat::ReasoningEffort::High => ReasoningEffort::High,
            async_openai::types::chat::ReasoningEffort::Xhigh => ReasoningEffort::Xhigh,
        }
    }
}

// ---------------------------------------------------------------------------
// Flexible `arguments` deserialisation helpers
// ---------------------------------------------------------------------------
// Some agent frameworks (e.g. LangChain, custom harnesses) send tool-call
// arguments as a pre-parsed JSON object instead of the canonical JSON
// string.  The helpers below normalise both representations to a `String` so
// downstream code never needs to branch on the wire format.

fn deserialize_arguments<'de, D>(deserializer: D) -> Result<String, D::Error>
where
    D: serde::Deserializer<'de>,
{
    use serde::de::Error;
    let value = serde_json::Value::deserialize(deserializer)?;
    match value {
        serde_json::Value::String(s) => Ok(s),
        v @ serde_json::Value::Object(_) => {
            // serde_json::to_string on a Value is infallible
            Ok(serde_json::to_string(&v).unwrap())
        }
        other => Err(D::Error::custom(format!(
            "expected string or object for `arguments`, got {other}"
        ))),
    }
}

fn deserialize_arguments_opt<'de, D>(deserializer: D) -> Result<Option<String>, D::Error>
where
    D: serde::Deserializer<'de>,
{
    use serde::de::Error;
    let value = Option::<serde_json::Value>::deserialize(deserializer)?;
    match value {
        None => Ok(None),
        Some(serde_json::Value::String(s)) => Ok(Some(s)),
        Some(v @ serde_json::Value::Object(_)) => serde_json::to_string(&v)
            .map(Some)
            .map_err(|e| D::Error::custom(e.to_string())),
        Some(other) => Err(D::Error::custom(format!(
            "expected string or object for `arguments`, got {other}"
        ))),
    }
}

/// Deserializes an optional media object, treating `{"url": ""}` as absent.
///
/// vLLM's OpenAI-compatible schema requires the media object to be present, so
/// UUID-cache clients emit an empty URL where Dynamo's canonical form is `null`.
/// Normalizing at the type boundary leaves `(url, uuid)` validation to consumers.
fn deserialize_optional_media<'de, D, T>(deserializer: D) -> Result<Option<T>, D::Error>
where
    D: serde::Deserializer<'de>,
    T: serde::de::DeserializeOwned,
{
    use serde::de::Error;
    match Option::<serde_json::Value>::deserialize(deserializer)? {
        None => Ok(None),
        Some(value) if value.get("url").and_then(serde_json::Value::as_str) == Some("") => Ok(None),
        Some(value) => serde_json::from_value(value)
            .map(Some)
            .map_err(D::Error::custom),
    }
}

// ---------------------------------------------------------------------------
// FunctionCall / FunctionCallStream — local definitions with flexible deser
// ---------------------------------------------------------------------------
// Upstream `async-openai` only accepts a JSON string for `arguments`.
// We define these locally so we can attach `#[serde(deserialize_with)]` and
// accept both string and object representations on the wire.

/// The name and arguments of a function that should be called.
///
/// Accepts `arguments` as either a JSON string (`"{\"key\":\"value\"}"`) or a
/// JSON object (`{"key": "value"}`); both are normalised to a JSON string
/// on deserialisation so callers always see the canonical form.
#[derive(Debug, Deserialize, Serialize, Clone, PartialEq, Default)]
pub struct FunctionCall {
    pub name: String,
    #[serde(deserialize_with = "deserialize_arguments")]
    pub arguments: String,
}

/// Streaming variant of [`FunctionCall`] where both fields are optional.
/// Continuation chunks carry only `arguments`; `name` is omitted rather
/// than serialized as `null`, matching OpenAI output.
#[derive(Debug, Deserialize, Serialize, Clone, PartialEq, Default)]
pub struct FunctionCallStream {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    #[serde(
        default,
        skip_serializing_if = "Option::is_none",
        deserialize_with = "deserialize_arguments_opt"
    )]
    pub arguments: Option<String>,
}

/// Streaming tool-call chunk.
///
/// Defined locally (instead of re-exporting from upstream) because its
/// `function` field references our local [`FunctionCallStream`] with the
/// flexible `arguments` deserialiser.
#[derive(Debug, Deserialize, Serialize, Clone, PartialEq, Default)]
pub struct ChatCompletionMessageToolCallChunk {
    pub index: u32,
    /// Only `index` is required by the spec; `id`, `type`, and `function`
    /// are omitted on continuation chunks, matching OpenAI output.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub r#type: Option<FunctionType>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub function: Option<FunctionCallStream>,
}

// ---------------------------------------------------------------------------
// Types with structural differences from upstream (kept locally)
// ---------------------------------------------------------------------------

/// Image content part.
///
/// vLLM's OpenAI-compatible server accepts an optional top-level `uuid` on the
/// media content part. For cache-hit-only requests, `uuid` carries the cache
/// key and the canonical `image_url` is null. Clients constrained by vLLM's
/// request schema may instead send `{"url": ""}`, which deserializes to the
/// same representation. This is a vLLM extension, not part of the OpenAI Chat
/// Completions API.
#[derive(Debug, Serialize, Deserialize, Clone, Builder, PartialEq)]
#[builder(name = "ChatCompletionRequestMessageContentPartImageArgs")]
#[builder(pattern = "mutable")]
#[builder(setter(into, strip_option))]
#[builder(derive(Debug))]
#[builder(build_fn(error = "OpenAIError"))]
pub struct ChatCompletionRequestMessageContentPartImage {
    #[builder(default)]
    #[serde(default, deserialize_with = "deserialize_optional_media")]
    pub image_url: Option<ImageUrl>,
    #[builder(default)]
    #[serde(skip_serializing_if = "Option::is_none")]
    /// vLLM-only multimodal processor-cache identity.
    pub uuid: Option<String>,
}

/// Image URL with `url::Url` type and a legacy optional UUID.
///
/// New callers should put vLLM processor-cache identities on
/// [`ChatCompletionRequestMessageContentPartImage::uuid`].
#[derive(Debug, Serialize, Deserialize, Clone, Builder, PartialEq)]
#[builder(name = "ImageUrlArgs")]
#[builder(pattern = "mutable")]
#[builder(setter(into, strip_option))]
#[builder(derive(Debug))]
#[builder(build_fn(error = "OpenAIError"))]
pub struct ImageUrl {
    pub url: Url,
    pub detail: Option<ImageDetail>,
    #[deprecated(note = "use the content-part `uuid` field for vLLM cache identities")]
    #[serde(skip_serializing_if = "Option::is_none")]
    pub uuid: Option<Uuid>,
}

/// Tool message content part with media observation support.
///
/// OpenAI's schema currently limits tool content parts to text, but
/// OpenAI-compatible multimodal backends also accept image, video, and audio
/// observations returned by tools.
#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)]
#[serde(tag = "type")]
#[serde(rename_all = "snake_case")]
pub enum ChatCompletionRequestToolMessageContentPart {
    Text(ChatCompletionRequestMessageContentPartText),
    ImageUrl(ChatCompletionRequestMessageContentPartImage),
    VideoUrl(ChatCompletionRequestMessageContentPartVideo),
    AudioUrl(ChatCompletionRequestMessageContentPartAudioUrl),
}

/// Tool message content, extended to preserve media observations.
#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)]
#[serde(untagged)]
pub enum ChatCompletionRequestToolMessageContent {
    Text(String),
    Array(Vec<ChatCompletionRequestToolMessageContentPart>),
}

impl Default for ChatCompletionRequestToolMessageContent {
    fn default() -> Self {
        Self::Text(String::new())
    }
}

impl From<&str> for ChatCompletionRequestToolMessageContent {
    fn from(value: &str) -> Self {
        Self::Text(value.into())
    }
}

impl From<String> for ChatCompletionRequestToolMessageContent {
    fn from(value: String) -> Self {
        Self::Text(value)
    }
}

/// Tool message using Dynamo's media-capable content type.
#[derive(Debug, Serialize, Deserialize, Default, Clone, Builder, PartialEq)]
#[builder(name = "ChatCompletionRequestToolMessageArgs")]
#[builder(pattern = "mutable")]
#[builder(setter(into, strip_option), default)]
#[builder(derive(Debug))]
#[builder(build_fn(error = "OpenAIError"))]
pub struct ChatCompletionRequestToolMessage {
    pub content: ChatCompletionRequestToolMessageContent,
    pub tool_call_id: String,
}

#[derive(Debug, Deserialize, Serialize, Clone, PartialEq)]
pub struct ChatChoiceLogprobs {
    pub content: Option<Vec<ChatCompletionTokenLogprob>>,
    pub refusal: Option<Vec<ChatCompletionTokenLogprob>>,
}

/// Token logprob entry with optional backend token ID.
///
/// Some inference backends can report both the rendered token string and its
/// vocabulary ID. Keeping this optional preserves the upstream OpenAI shape
/// when token IDs are unavailable.
#[derive(Debug, Deserialize, Serialize, Clone, PartialEq)]
pub struct ChatCompletionTokenLogprob {
    pub token: String,
    pub logprob: f32,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub token_id: Option<u32>,
    pub bytes: Option<Vec<u8>>,
    pub top_logprobs: Vec<TopLogprobs>,
}

#[derive(Clone, Serialize, Default, Debug, Deserialize, PartialEq)]
#[serde(rename_all = "lowercase")]
pub enum ChatCompletionToolType {
    #[default]
    Function,
}

#[derive(Clone, Serialize, Default, Debug, Deserialize, PartialEq)]
pub struct FunctionName {
    pub name: String,
}

#[derive(Clone, Serialize, Default, Debug, Deserialize, PartialEq)]
pub struct ChatCompletionNamedToolChoice {
    pub r#type: ChatCompletionToolType,
    pub function: FunctionName,
}

fn default_function_type() -> FunctionType {
    FunctionType::Function
}

/// Tool call kept locally to preserve `type: "function"` in unary request/response payloads.
///
/// Differs from upstream: `type` is serialized by default and also defaults to
/// `function` when omitted during deserialization, preserving compatibility with
/// both Dynamo's historical wire format and upstream spec-compliant inputs.
#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
pub struct ChatCompletionMessageToolCall {
    pub id: String,
    #[serde(default = "default_function_type")]
    pub r#type: FunctionType,
    pub function: FunctionCall,
}

/// Tool choice enum kept locally because upstream changed variant names.
#[derive(Clone, Serialize, Default, Debug, Deserialize, PartialEq)]
#[serde(rename_all = "lowercase")]
pub enum ChatCompletionToolChoiceOption {
    #[default]
    None,
    Auto,
    Required,
    #[serde(untagged)]
    Named(ChatCompletionNamedToolChoice),
}

#[derive(Clone, Serialize, Default, Debug, Builder, Deserialize, PartialEq)]
#[builder(name = "ChatCompletionToolArgs")]
#[builder(pattern = "mutable")]
#[builder(setter(into, strip_option), default)]
#[builder(derive(Debug))]
#[builder(build_fn(error = "OpenAIError"))]
pub struct ChatCompletionTool {
    #[builder(default = "ChatCompletionToolType::Function")]
    pub r#type: ChatCompletionToolType,
    pub function: FunctionObject,
}

// ---------------------------------------------------------------------------
// Inference-serving extensions (not in upstream)
// ---------------------------------------------------------------------------

/// Matched stop condition from the backend.
///
/// Inference backends (vLLM, SGLang) report which stop condition triggered:
/// - `String`: a matched user-provided stop sequence
/// - `Int`: a matched stop token ID
/// - `IntArray`: matched stop token IDs reported as a sequence
#[derive(Debug, Deserialize, Serialize, Clone, PartialEq)]
#[serde(untagged)]
pub enum StopReason {
    String(String),
    Int(i64),
    IntArray(Vec<i64>),
}

/// Reasoning content from a previous assistant turn.
///
/// Deserializes from either:
/// - A plain string: `"reasoning_content": "thinking..."` -> `Text("thinking...")`
/// - An array of strings: `"reasoning_content": ["seg1", "seg2"]` -> `Segments(["seg1", "seg2"])`
///
/// The `Segments` variant preserves interleaved reasoning order needed for KV cache-correct
/// context reconstruction. `segments[i]` is the reasoning that preceded `tool_calls[i]`;
/// `segments[tool_calls.len()]` is any trailing reasoning after the last tool call.
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
#[serde(untagged)]
pub enum ReasoningContent {
    /// Flat string -- single reasoning block or legacy backward-compat form.
    Text(String),
    /// Interleaved segments. segments[i] precedes tool_calls[i];
    /// segments[N] is trailing reasoning after the last tool call.
    Segments(Vec<String>),
}

impl ReasoningContent {
    /// Join all segments (or return text as-is) into a single flat string.
    pub fn to_flat_string(&self) -> String {
        match self {
            ReasoningContent::Text(s) => s.clone(),
            ReasoningContent::Segments(segs) => segs
                .iter()
                .filter(|s| !s.is_empty())
                .cloned()
                .collect::<Vec<_>>()
                .join("\n"),
        }
    }

    /// Returns the segments if this is the `Segments` variant, `None` for `Text`.
    pub fn segments(&self) -> Option<&[String]> {
        match self {
            ReasoningContent::Segments(segs) => Some(segs),
            ReasoningContent::Text(_) => None,
        }
    }
}

// -- Multimodal content types for responses (not in upstream) --

/// Response content part for text in assistant messages
#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
pub struct ChatCompletionResponseContentPartText {
    pub text: String,
}

/// Response content part for image URLs in assistant messages
#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
pub struct ChatCompletionResponseContentPartImageUrl {
    pub image_url: ImageUrlResponse,
}

/// Response content part for video URLs in assistant messages
#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
pub struct ChatCompletionResponseContentPartVideoUrl {
    pub video_url: VideoUrlResponse,
}

/// Response content part for audio URLs in assistant messages
#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
pub struct ChatCompletionResponseContentPartAudioUrl {
    pub audio_url: AudioUrlResponse,
}

#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
pub struct ImageUrlResponse {
    pub url: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub detail: Option<String>,
}

#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
pub struct VideoUrlResponse {
    pub url: String,
}

#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
pub struct AudioUrlResponse {
    pub url: String,
}

/// Content parts for assistant responses supporting multiple modalities
#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum ChatCompletionResponseContentPart {
    Text(ChatCompletionResponseContentPartText),
    ImageUrl(ChatCompletionResponseContentPartImageUrl),
    VideoUrl(ChatCompletionResponseContentPartVideoUrl),
    AudioUrl(ChatCompletionResponseContentPartAudioUrl),
}

/// Assistant message content -- can be a simple string or multimodal content parts.
///
/// Upstream uses `Option<String>` for the content field. We extend this to
/// support multimodal responses (text + images + video + audio) from backends
/// like vLLM that can return non-text content.
#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
#[serde(untagged)]
pub enum ChatCompletionMessageContent {
    /// Simple text content (backward compatible)
    Text(String),
    /// Array of content parts (for multimodal responses)
    Parts(Vec<ChatCompletionResponseContentPart>),
}

// -- Multimodal input types (video/audio URL support, not in upstream) --

#[derive(Debug, Serialize, Deserialize, Clone, Builder, PartialEq)]
#[builder(name = "VideoUrlArgs")]
#[builder(pattern = "mutable")]
#[builder(setter(into, strip_option))]
#[builder(derive(Debug))]
#[builder(build_fn(error = "OpenAIError"))]
pub struct VideoUrl {
    pub url: Url,
    pub detail: Option<ImageDetail>,
    #[deprecated(note = "use the content-part `uuid` field for vLLM cache identities")]
    #[serde(skip_serializing_if = "Option::is_none")]
    pub uuid: Option<Uuid>,
}

#[derive(Debug, Serialize, Deserialize, Clone, Builder, PartialEq)]
#[builder(name = "ChatCompletionRequestMessageContentPartVideoArgs")]
#[builder(pattern = "mutable")]
#[builder(setter(into, strip_option))]
#[builder(derive(Debug))]
#[builder(build_fn(error = "OpenAIError"))]
pub struct ChatCompletionRequestMessageContentPartVideo {
    #[builder(default)]
    #[serde(default, deserialize_with = "deserialize_optional_media")]
    pub video_url: Option<VideoUrl>,
    #[builder(default)]
    #[serde(skip_serializing_if = "Option::is_none")]
    /// vLLM-only multimodal processor-cache identity.
    pub uuid: Option<String>,
}

#[derive(Debug, Serialize, Deserialize, Clone, Builder, PartialEq)]
#[builder(name = "AudioUrlArgs")]
#[builder(pattern = "mutable")]
#[builder(setter(into, strip_option))]
#[builder(derive(Debug))]
#[builder(build_fn(error = "OpenAIError"))]
pub struct AudioUrl {
    pub url: Url,
    #[deprecated(note = "use the content-part `uuid` field for vLLM cache identities")]
    #[serde(skip_serializing_if = "Option::is_none")]
    pub uuid: Option<Uuid>,
}

#[derive(Debug, Serialize, Deserialize, Clone, Builder, PartialEq)]
#[builder(name = "ChatCompletionRequestMessageContentPartAudioUrlArgs")]
#[builder(pattern = "mutable")]
#[builder(setter(into, strip_option))]
#[builder(derive(Debug))]
#[builder(build_fn(error = "OpenAIError"))]
pub struct ChatCompletionRequestMessageContentPartAudioUrl {
    #[builder(default)]
    #[serde(default, deserialize_with = "deserialize_optional_media")]
    pub audio_url: Option<AudioUrl>,
    #[builder(default)]
    #[serde(skip_serializing_if = "Option::is_none")]
    /// vLLM-only multimodal processor-cache identity.
    pub uuid: Option<String>,
}

// -- Extended request/response types --

/// User message content -- references our extended content part enum.
#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)]
#[serde(untagged)]
pub enum ChatCompletionRequestUserMessageContent {
    Text(String),
    Array(Vec<ChatCompletionRequestUserMessageContentPart>),
}

#[derive(Debug, Serialize, Deserialize, Default, Clone, Builder, PartialEq)]
#[builder(name = "ChatCompletionRequestUserMessageArgs")]
#[builder(pattern = "mutable")]
#[builder(setter(into, strip_option), default)]
#[builder(derive(Debug))]
#[builder(build_fn(error = "OpenAIError"))]
pub struct ChatCompletionRequestUserMessage {
    pub content: ChatCompletionRequestUserMessageContent,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
}

impl Default for ChatCompletionRequestUserMessageContent {
    fn default() -> Self {
        Self::Text(String::new())
    }
}

impl From<&str> for ChatCompletionRequestUserMessageContent {
    fn from(value: &str) -> Self {
        Self::Text(value.into())
    }
}

impl From<String> for ChatCompletionRequestUserMessageContent {
    fn from(value: String) -> Self {
        Self::Text(value)
    }
}

impl From<Vec<ChatCompletionRequestUserMessageContentPart>>
    for ChatCompletionRequestUserMessageContent
{
    fn from(value: Vec<ChatCompletionRequestUserMessageContentPart>) -> Self {
        Self::Array(value)
    }
}

/// User message content part with video and audio URL support.
///
/// Extends upstream `ChatCompletionRequestUserMessageContentPart` with:
/// - `VideoUrl`: video input for multimodal models
/// - `AudioUrl`: audio URL input (distinct from base64 InputAudio)
#[derive(Debug, Serialize, Deserialize, Clone, PartialEq)]
#[serde(tag = "type")]
#[serde(rename_all = "snake_case")]
pub enum ChatCompletionRequestUserMessageContentPart {
    Text(ChatCompletionRequestMessageContentPartText),
    ImageUrl(ChatCompletionRequestMessageContentPartImage),
    VideoUrl(ChatCompletionRequestMessageContentPartVideo),
    AudioUrl(ChatCompletionRequestMessageContentPartAudioUrl),
    InputAudio(ChatCompletionRequestMessageContentPartAudio),
}

/// System message with dynamic tool metadata support.
///
/// Extends upstream `ChatCompletionRequestSystemMessage` with:
/// - `content`: still required in the public Rust type. On the wire only,
///   Kimi-style messages may omit it (or send `null`) when they declare
///   non-empty `tools`; deserialization canonicalizes that shape to empty text.
///   Every other content-less system message is still rejected with upstream's
///   `missing field \`content\`` error, so spec-conformant clients and non-Kimi
///   models see no behavior change. Without this guard a bare
///   `{"role": "system"}` would reach ordinary HF jinja templates and render
///   an empty system turn instead of failing the request.
/// - `tools`: passthrough field for model-specific tool metadata rendered by the
///   chat template. Dynamo does not interpret this field; it is preserved
///   verbatim for downstream chat-template rendering.
///
/// `Default` (and therefore the builder's unset state) uses empty-string
/// `content`, matching upstream. Keeping `content` non-optional also prevents
/// programmatic callers from constructing a content-less, tool-less message.
#[derive(Debug, Serialize, Clone, Builder, PartialEq, Default)]
#[builder(name = "ChatCompletionRequestSystemMessageArgs")]
#[builder(pattern = "mutable")]
#[builder(setter(into, strip_option), default)]
#[builder(derive(Debug))]
#[builder(build_fn(error = "OpenAIError"))]
pub struct ChatCompletionRequestSystemMessage {
    pub content: ChatCompletionRequestSystemMessageContent,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// Kimi-style dynamic tool metadata carried on a system message.
    ///
    /// Moonshot treats omitted, null, and empty `content` as no system text;
    /// renderers enforce that non-empty `content` and `tools` are mutually
    /// exclusive and that `tools` is non-empty. The list shape is typed here
    /// so non-array values are rejected at deserialization.
    ///
    /// Entries stay raw JSON rather than a typed schema on purpose: this crate
    /// only needs to *preserve* them for downstream chat-template rendering,
    /// which reads them back as generic JSON by key. A typed entry (e.g.
    /// `FunctionObject`) would silently drop vendor-specific keys serde doesn't
    /// know about on round-trip, whereas `serde_json::Value` is structurally
    /// lossless (JSON structure and unknown keys survive; whitespace, number
    /// spelling, and duplicate keys do not).
    ///
    /// Kimi's `encoding_k3.py` renders this through the same tool-declare path
    /// as the top-level `tools` field and never inspects individual entries, so
    /// the canonical shape is the same OpenAI wrapped form,
    /// `{"type": "function", "function": {...}}`. Clients that send bare
    /// function-schema objects (`{"name": ..., "parameters": ...}`) are passed
    /// through unchanged as well; this crate takes no position on the shape.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tools: Option<Vec<serde_json::Value>>,
}

impl<'de> Deserialize<'de> for ChatCompletionRequestSystemMessage {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        use serde::de::Error;

        /// Wire shape with `content` relaxed solely for recognizing Kimi's
        /// tools-only form. Deserialized first so field-level errors (bad
        /// `content` shape, non-array `tools`) keep serde's own messages.
        #[derive(Deserialize)]
        struct Wire {
            content: Option<ChatCompletionRequestSystemMessageContent>,
            name: Option<String>,
            tools: Option<Vec<serde_json::Value>>,
        }

        let Wire {
            content,
            name,
            tools,
        } = Wire::deserialize(deserializer)?;
        let content = match content {
            Some(content) => content,
            None if tools.as_ref().is_some_and(|tools| !tools.is_empty()) => {
                ChatCompletionRequestSystemMessageContent::Text(String::new())
            }
            None => {
                return Err(D::Error::custom(
                    "missing field `content`: a system message needs `content` unless it \
                     declares non-empty Kimi-style `tools`",
                ));
            }
        };
        Ok(Self {
            content,
            name,
            tools,
        })
    }
}

/// Assistant message with reasoning content support.
///
/// Extends upstream `ChatCompletionRequestAssistantMessage` with:
/// - `reasoning_content`: interleaved reasoning segments for KV cache correctness
///   (DeepSeek-R1, QwQ models)
/// - `partial`: Kimi-style prefill flag marking an assistant turn as an
///   incomplete continuation seed rather than a finished turn
#[derive(Debug, Serialize, Deserialize, Default, Clone, Builder, PartialEq)]
#[builder(name = "ChatCompletionRequestAssistantMessageArgs")]
#[builder(pattern = "mutable")]
#[builder(setter(into, strip_option), default)]
#[builder(derive(Debug))]
#[builder(build_fn(error = "OpenAIError"))]
pub struct ChatCompletionRequestAssistantMessage {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub content: Option<ChatCompletionRequestAssistantMessageContent>,
    /// Reasoning content from a previous assistant turn.
    /// Accept both `reasoning_content` (DeepSeek /
    /// SGLang / TRT-LLM / Vercel AI SDK openai-compatible / LangChain / LiteLLM
    /// canonical) and `reasoning` (vLLM native / OpenRouter / OpenAI GPT-OSS
    /// guidance) on inbound assistant messages, normalizing both to this field.
    #[serde(default, alias = "reasoning", skip_serializing_if = "Option::is_none")]
    pub reasoning_content: Option<ReasoningContent>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub refusal: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub audio: Option<ChatCompletionRequestAssistantMessageAudio>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tool_calls: Option<Vec<ChatCompletionMessageToolCall>>,
    #[deprecated]
    #[serde(skip_serializing_if = "Option::is_none")]
    pub function_call: Option<FunctionCall>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub partial: Option<bool>,
}

/// Chat completion request message enum.
///
/// Redefined to use our extended `ChatCompletionRequestAssistantMessage`
/// (with reasoning_content) and `ChatCompletionRequestUserMessage`
/// (which references our extended content parts with video/audio).
///
/// Deserialization rejects Kimi-specific fields on roles that cannot carry
/// them (`tools` off `system`, `partial` off `assistant`) instead of letting
/// serde's ignore-unknown-fields default drop them silently; Moonshot's
/// negative tests expect a request error for these shapes.
#[derive(Debug, Serialize, Clone, PartialEq)]
#[serde(tag = "role")]
#[serde(rename_all = "lowercase")]
pub enum ChatCompletionRequestMessage {
    Developer(ChatCompletionRequestDeveloperMessage),
    System(ChatCompletionRequestSystemMessage),
    User(ChatCompletionRequestUserMessage),
    Assistant(ChatCompletionRequestAssistantMessage),
    Tool(ChatCompletionRequestToolMessage),
    Function(ChatCompletionRequestFunctionMessage),
}

impl<'de> Deserialize<'de> for ChatCompletionRequestMessage {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        use serde::de::Error;

        #[derive(Deserialize)]
        struct ForbidToolsAndPartial<T> {
            tools: Option<serde::de::IgnoredAny>,
            partial: Option<serde::de::IgnoredAny>,
            #[serde(flatten)]
            message: T,
        }

        #[derive(Deserialize)]
        struct ForbidTools<T> {
            tools: Option<serde::de::IgnoredAny>,
            #[serde(flatten)]
            message: T,
        }

        #[derive(Deserialize)]
        struct ForbidPartial<T> {
            partial: Option<serde::de::IgnoredAny>,
            #[serde(flatten)]
            message: T,
        }

        #[derive(Deserialize)]
        #[serde(tag = "role")]
        #[serde(rename_all = "lowercase")]
        enum Wire {
            Developer(ForbidToolsAndPartial<ChatCompletionRequestDeveloperMessage>),
            System(ForbidPartial<ChatCompletionRequestSystemMessage>),
            User(ForbidToolsAndPartial<ChatCompletionRequestUserMessage>),
            Assistant(ForbidTools<ChatCompletionRequestAssistantMessage>),
            Tool(ForbidToolsAndPartial<ChatCompletionRequestToolMessage>),
            Function(ForbidToolsAndPartial<ChatCompletionRequestFunctionMessage>),
        }

        fn reject_forbidden<E: Error>(
            value: Option<serde::de::IgnoredAny>,
            field: &str,
            allowed_role: &str,
            actual_role: &str,
        ) -> Result<(), E> {
            if value.is_some() {
                return Err(E::custom(format!(
                    "`{field}` is only accepted on {allowed_role} messages, not on role {actual_role}"
                )));
            }
            Ok(())
        }

        let wire = Wire::deserialize(deserializer)?;
        Ok(match wire {
            Wire::Developer(ForbidToolsAndPartial {
                tools,
                partial,
                message,
            }) => {
                reject_forbidden::<D::Error>(tools, "tools", "system", "developer")?;
                reject_forbidden::<D::Error>(partial, "partial", "assistant", "developer")?;
                ChatCompletionRequestMessage::Developer(message)
            }
            Wire::System(ForbidPartial { partial, message }) => {
                reject_forbidden::<D::Error>(partial, "partial", "assistant", "system")?;
                ChatCompletionRequestMessage::System(message)
            }
            Wire::User(ForbidToolsAndPartial {
                tools,
                partial,
                message,
            }) => {
                reject_forbidden::<D::Error>(tools, "tools", "system", "user")?;
                reject_forbidden::<D::Error>(partial, "partial", "assistant", "user")?;
                ChatCompletionRequestMessage::User(message)
            }
            Wire::Assistant(ForbidTools { tools, message }) => {
                reject_forbidden::<D::Error>(tools, "tools", "system", "assistant")?;
                ChatCompletionRequestMessage::Assistant(message)
            }
            Wire::Tool(ForbidToolsAndPartial {
                tools,
                partial,
                message,
            }) => {
                reject_forbidden::<D::Error>(tools, "tools", "system", "tool")?;
                reject_forbidden::<D::Error>(partial, "partial", "assistant", "tool")?;
                ChatCompletionRequestMessage::Tool(message)
            }
            Wire::Function(ForbidToolsAndPartial {
                tools,
                partial,
                message,
            }) => {
                reject_forbidden::<D::Error>(tools, "tools", "system", "function")?;
                reject_forbidden::<D::Error>(partial, "partial", "assistant", "function")?;
                ChatCompletionRequestMessage::Function(message)
            }
        })
    }
}

/// Backward-compatible name for the service tier reported in responses.
pub type ServiceTierResponse = ServiceTier;

/// Chat completion response message with multimodal content and reasoning.
///
/// Extends upstream `ChatCompletionResponseMessage` with:
/// - `content`: `Option<ChatCompletionMessageContent>` (multimodal) instead of `Option<String>`
/// - `reasoning_content`: model reasoning output (DeepSeek-R1, QwQ)
#[derive(Debug, Deserialize, Serialize, Clone, PartialEq)]
pub struct ChatCompletionResponseMessage {
    /// Always serialized (as `null` when None) so clients can rely on the
    /// `content` key being present alongside `reasoning_content` or
    /// `tool_calls`. Matches the upstream OpenAI API shape (DGH-651).
    pub content: Option<ChatCompletionMessageContent>,
    /// Always serialized (as `null` when None): the spec marks `refusal` as
    /// required-and-nullable, and OpenAI emits `"refusal": null` on every
    /// non-refusal response.
    pub refusal: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tool_calls: Option<Vec<ChatCompletionMessageToolCall>>,
    pub role: Role,
    #[serde(skip_serializing_if = "Option::is_none")]
    #[deprecated]
    pub function_call: Option<FunctionCall>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub audio: Option<ChatCompletionResponseMessageAudio>,
    /// Reasoning content produced by the model (DeepSeek-R1, QwQ).
    /// Accepts either `reasoning_content` (DeepSeek / SGLang / TRT-LLM
    /// canonical) or `reasoning` (vLLM native / OpenRouter / OpenAI GPT-OSS)
    /// on input via the alias; output-side key selection is handled at the
    /// HTTP boundary by ai-dynamo/dynamo#11464's `RoutedReasoning` wrapper.
    /// Not part of the OpenAI spec, so it is omitted entirely when absent.
    #[serde(default, alias = "reasoning", skip_serializing_if = "Option::is_none")]
    pub reasoning_content: Option<String>,
}

/// Stream options with per-chunk usage reporting.
///
/// Extends upstream `ChatCompletionStreamOptions` with:
/// - `continuous_usage_stats`: emit usage in every chunk, not just the final one
#[derive(Debug, Serialize, Deserialize, Clone, Copy, PartialEq)]
pub struct ChatCompletionStreamOptions {
    pub include_usage: bool,
    /// When true, usage statistics are included in every streaming chunk.
    /// Backends like vLLM/SGLang support this for real-time token counting.
    #[serde(default)]
    pub continuous_usage_stats: bool,
}

/// Chat completion request with multimodal processor support.
///
/// Extends upstream `CreateChatCompletionRequest` with:
/// - `mm_processor_kwargs`: multimodal processor configuration (vLLM-specific)
/// - Uses our extended `ChatCompletionRequestMessage` (with reasoning, video/audio)
/// - Uses our extended `ChatCompletionStreamOptions` (with continuous_usage_stats)
#[derive(Clone, Serialize, Default, Debug, Builder, Deserialize, PartialEq)]
#[builder(name = "CreateChatCompletionRequestArgs")]
#[builder(pattern = "mutable")]
#[builder(setter(into, strip_option), default)]
#[builder(derive(Debug))]
#[builder(build_fn(error = "OpenAIError"))]
pub struct CreateChatCompletionRequest {
    pub messages: Vec<ChatCompletionRequestMessage>,
    pub model: String,
    /// Multimodal processor configuration (vLLM-specific)
    #[serde(skip_serializing_if = "Option::is_none")]
    pub mm_processor_kwargs: Option<serde_json::Value>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub store: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub reasoning_effort: Option<ReasoningEffort>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub metadata: Option<serde_json::Value>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub frequency_penalty: Option<f32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub logit_bias: Option<std::collections::HashMap<String, serde_json::Value>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub logprobs: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub top_logprobs: Option<u8>,
    #[deprecated]
    #[serde(skip_serializing_if = "Option::is_none")]
    pub max_tokens: Option<u32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub max_completion_tokens: Option<u32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub n: Option<u8>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub modalities: Option<Vec<async_openai::types::chat::ResponseModalities>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub prediction: Option<PredictionContent>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub audio: Option<ChatCompletionAudio>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub presence_penalty: Option<f32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub response_format: Option<ResponseFormat>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub seed: Option<i64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub service_tier: Option<ServiceTier>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub stop: Option<Stop>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub stream: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub stream_options: Option<ChatCompletionStreamOptions>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub temperature: Option<f32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub top_p: Option<f32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tools: Option<Vec<ChatCompletionTool>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tool_choice: Option<ChatCompletionToolChoiceOption>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub parallel_tool_calls: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub user: Option<String>,
    /// OpenAI cache-affinity hint: requests sharing a prompt prefix send the
    /// same key (Kimi Code CLI sends its session id on every request).
    ///
    /// NOTICE: accepted and preserved only. Nothing in this crate or in Dynamo
    /// acts on it yet — Dynamo's KV-aware router keys on prompt-prefix block
    /// hashes, not on this value.
    // TODO(routing): decide whether `prompt_cache_key` should feed router
    // affinity (e.g. as a tie-breaker or session pin) and plumb it through.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub prompt_cache_key: Option<String>,
    #[deprecated]
    #[serde(skip_serializing_if = "Option::is_none")]
    pub function_call: Option<ChatCompletionFunctionCall>,
    #[deprecated]
    #[serde(skip_serializing_if = "Option::is_none")]
    pub functions: Option<Vec<ChatCompletionFunctions>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub web_search_options: Option<WebSearchOptions>,
}

impl CreateChatCompletionRequest {
    /// Kimi-style dynamic tools declared on `system` messages, in message order.
    ///
    /// Kimi defines these as coexisting with the top-level `tools` list: a
    /// dynamic declaration keeps its position in the message history so the
    /// prompt prefix (and any KV cache built on it) stays intact. Do not fold
    /// them into `tools`; reason about the union with
    /// [`Self::has_effective_tools`] and [`Self::effective_tool_contains`].
    ///
    /// Only `system` messages can carry `tools` in the typed schema; the
    /// `developer` message is the upstream type and has no such field.
    pub fn dynamic_system_tools(&self) -> impl Iterator<Item = &serde_json::Value> {
        self.messages
            .iter()
            .filter_map(|message| match message {
                ChatCompletionRequestMessage::System(system) => system.tools.as_deref(),
                _ => None,
            })
            .flatten()
    }

    /// Whether the request declares any tool, either top-level or through a
    /// dynamic system-message declaration.
    ///
    /// Gates that decide whether model output may be interpreted as tool
    /// calls must use this rather than `tools` alone, or a call to a
    /// dynamically declared tool is stripped from the response.
    pub fn has_effective_tools(&self) -> bool {
        self.tools.as_ref().is_some_and(|tools| !tools.is_empty())
            || self.dynamic_system_tools().next().is_some()
    }

    /// Names of every tool the model can see: top-level `tools` first, then
    /// dynamic system-message tools in message order.
    pub fn effective_tool_names(&self) -> impl Iterator<Item = &str> {
        self.tools
            .iter()
            .flatten()
            .map(|tool| tool.function.name.as_str())
            .chain(self.dynamic_system_tools().filter_map(dynamic_tool_name))
    }

    /// Whether `name` is declared anywhere in the effective tool set.
    ///
    /// Use this to validate a named `tool_choice` so a forced call to a
    /// dynamically declared tool is not rejected as "not present in tools".
    pub fn effective_tool_contains(&self, name: &str) -> bool {
        self.effective_tool_names().any(|tool| tool == name)
    }
}

/// Name of a dynamic system-message tool entry.
///
/// Accepts both the OpenAI wrapped form
/// `{"type": "function", "function": {"name": ...}}` and the bare
/// function-schema form `{"name": ...}` that some Kimi clients send. Returns
/// `None` for entries with no string name.
pub fn dynamic_tool_name(tool: &serde_json::Value) -> Option<&str> {
    tool.get("function")
        .and_then(serde_json::Value::as_object)
        .and_then(|function| function.get("name"))
        .or_else(|| tool.get("name"))
        .and_then(serde_json::Value::as_str)
}

/// Chat choice with extended response message.
///
/// Uses our `ChatCompletionResponseMessage` (multimodal content + reasoning).
#[derive(Debug, Deserialize, Serialize, Clone, PartialEq)]
pub struct ChatChoice {
    pub index: u32,
    pub message: ChatCompletionResponseMessage,
    pub finish_reason: Option<FinishReason>,
    pub logprobs: Option<ChatChoiceLogprobs>,
}

/// Serializes `usage` through a shadow struct that omits absent optional
/// fields.
///
/// Upstream async-openai derives serialize `None` usage-details fields as
/// explicit `null` (e.g. `"audio_tokens": null`), but the spec marks every
/// usage-details field optional and non-nullable, so absent fields must be
/// omitted (OpenAI emits `"audio_tokens": 0`, never `null`). The shadow
/// keeps upstream `CompletionUsage` in the public API — replacing it with a
/// same-named local type would break callers that pass upstream values.
fn serialize_usage_omitting_absent<S>(
    usage: &Option<CompletionUsage>,
    serializer: S,
) -> Result<S::Ok, S::Error>
where
    S: serde::Serializer,
{
    #[derive(Serialize)]
    struct PromptDetailsShadow {
        #[serde(skip_serializing_if = "Option::is_none")]
        audio_tokens: Option<u32>,
        #[serde(skip_serializing_if = "Option::is_none")]
        cached_tokens: Option<u32>,
    }

    #[derive(Serialize)]
    struct CompletionDetailsShadow {
        #[serde(skip_serializing_if = "Option::is_none")]
        accepted_prediction_tokens: Option<u32>,
        #[serde(skip_serializing_if = "Option::is_none")]
        audio_tokens: Option<u32>,
        #[serde(skip_serializing_if = "Option::is_none")]
        reasoning_tokens: Option<u32>,
        #[serde(skip_serializing_if = "Option::is_none")]
        rejected_prediction_tokens: Option<u32>,
    }

    #[derive(Serialize)]
    struct UsageShadow {
        prompt_tokens: u32,
        completion_tokens: u32,
        total_tokens: u32,
        #[serde(skip_serializing_if = "Option::is_none")]
        prompt_tokens_details: Option<PromptDetailsShadow>,
        #[serde(skip_serializing_if = "Option::is_none")]
        completion_tokens_details: Option<CompletionDetailsShadow>,
    }

    match usage {
        None => serializer.serialize_none(),
        Some(u) => UsageShadow {
            prompt_tokens: u.prompt_tokens,
            completion_tokens: u.completion_tokens,
            total_tokens: u.total_tokens,
            prompt_tokens_details: u
                .prompt_tokens_details
                .as_ref()
                .map(|d| PromptDetailsShadow {
                    audio_tokens: d.audio_tokens,
                    cached_tokens: d.cached_tokens,
                }),
            completion_tokens_details: u.completion_tokens_details.as_ref().map(|d| {
                CompletionDetailsShadow {
                    accepted_prediction_tokens: d.accepted_prediction_tokens,
                    audio_tokens: d.audio_tokens,
                    reasoning_tokens: d.reasoning_tokens,
                    rejected_prediction_tokens: d.rejected_prediction_tokens,
                }
            }),
        }
        .serialize(serializer),
    }
}

/// Non-streaming chat completion response.
///
/// `service_tier`, `system_fingerprint`, and `usage` are optional in the
/// spec and omitted (not serialized as `null`) when absent, matching
/// OpenAI output. `choices[].finish_reason` and `choices[].logprobs` stay
/// always-present: the spec marks them required (nullable for `logprobs`).
#[derive(Debug, Deserialize, Clone, PartialEq, Serialize)]
pub struct CreateChatCompletionResponse {
    pub id: String,
    pub choices: Vec<ChatChoice>,
    pub created: u32,
    pub model: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub service_tier: Option<ServiceTierResponse>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub system_fingerprint: Option<String>,
    pub object: String,
    #[serde(
        skip_serializing_if = "Option::is_none",
        serialize_with = "serialize_usage_omitting_absent"
    )]
    pub usage: Option<CompletionUsage>,
}

pub type ChatCompletionResponseStream =
    Pin<Box<dyn Stream<Item = Result<CreateChatCompletionStreamResponse, OpenAIError>> + Send>>;

/// Streaming delta with reasoning content.
///
/// Extends upstream `ChatCompletionStreamResponseDelta` with:
/// - `content`: `Option<ChatCompletionMessageContent>` (multimodal) instead of `Option<String>`
/// - `reasoning_content`: streaming reasoning tokens (DeepSeek-R1, QwQ)
#[derive(Debug, Deserialize, Serialize, Clone, PartialEq)]
pub struct ChatCompletionStreamResponseDelta {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub content: Option<ChatCompletionMessageContent>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub function_call: Option<ChatCompletionStreamResponseDeltaFunctionCall>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tool_calls: Option<Vec<ChatCompletionMessageToolCallChunk>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub role: Option<Role>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub refusal: Option<String>,
    /// Streaming reasoning content (DeepSeek-R1, QwQ models).
    /// Accepts either `reasoning_content` (DeepSeek / SGLang / TRT-LLM
    /// canonical) or `reasoning` (vLLM native / OpenRouter / OpenAI GPT-OSS)
    /// on input via the alias; output-side key selection is handled at the
    /// HTTP boundary by ai-dynamo/dynamo#11464's `RoutedReasoning` wrapper.
    #[serde(default, alias = "reasoning", skip_serializing_if = "Option::is_none")]
    pub reasoning_content: Option<String>,
}

#[derive(Debug, Deserialize, Serialize, Clone, PartialEq)]
pub struct ChatCompletionStreamResponseDeltaFunctionCall {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    #[serde(
        default,
        deserialize_with = "deserialize_arguments_opt",
        skip_serializing_if = "Option::is_none"
    )]
    pub arguments: Option<String>,
}

/// Streaming chat choice.
#[derive(Debug, Deserialize, Clone, PartialEq, Serialize)]
pub struct ChatChoiceStream {
    pub index: u32,
    pub delta: ChatCompletionStreamResponseDelta,
    pub finish_reason: Option<FinishReason>,
    pub logprobs: Option<ChatChoiceLogprobs>,
}

/// Streaming chat completion response with extended choices.
///
/// `service_tier`, `system_fingerprint`, and `usage` are optional in the
/// spec and omitted (not serialized as `null`) when absent. Note: with
/// `stream_options.include_usage`, OpenAI emits `"usage": null` on every
/// chunk before the final one; callers needing that exact shape must
/// inject the key at the HTTP boundary.
#[derive(Debug, Deserialize, Clone, PartialEq, Serialize)]
pub struct CreateChatCompletionStreamResponse {
    pub id: String,
    pub choices: Vec<ChatChoiceStream>,
    pub created: u32,
    pub model: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub service_tier: Option<ServiceTierResponse>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub system_fingerprint: Option<String>,
    pub object: String,
    #[serde(
        skip_serializing_if = "Option::is_none",
        serialize_with = "serialize_usage_omitting_absent"
    )]
    pub usage: Option<CompletionUsage>,
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn stop_accepts_token_id_array() {
        let stop: Stop = serde_json::from_value(serde_json::json!([32, 34])).unwrap();

        assert_eq!(stop, Stop::TokenIdArray(vec![32, 34]));
    }

    #[test]
    fn stop_accepts_string_and_string_array() {
        let stop: Stop = serde_json::from_value(serde_json::json!(" The")).unwrap();

        assert_eq!(stop, Stop::String(" The".to_string()));

        let stop: Stop = serde_json::from_value(serde_json::json!(["A", "B"])).unwrap();

        assert_eq!(
            stop,
            Stop::StringArray(vec!["A".to_string(), "B".to_string()])
        );
    }

    #[test]
    fn stop_token_id_display_string_remains_string_stop() {
        let stop: Stop = serde_json::from_value(serde_json::json!("token_id:576")).unwrap();

        assert_eq!(stop, Stop::String("token_id:576".to_string()));

        let stop: Stop = serde_json::from_value(serde_json::json!(["token_id:576"])).unwrap();

        assert_eq!(stop, Stop::StringArray(vec!["token_id:576".to_string()]));
    }

    #[test]
    fn stop_rejects_single_token_id() {
        let result = serde_json::from_value::<Stop>(serde_json::json!(576));

        assert!(result.is_err());
    }

    #[test]
    fn stop_converts_from_upstream_stop_configuration() {
        let upstream =
            async_openai::types::chat::StopConfiguration::StringArray(vec!["END".to_string()]);

        assert_eq!(
            Stop::from(upstream),
            Stop::StringArray(vec!["END".to_string()])
        );
    }

    #[test]
    fn request_builder_accepts_upstream_reasoning_effort() {
        let request = CreateChatCompletionRequestArgs::default()
            .reasoning_effort(async_openai::types::chat::ReasoningEffort::High)
            .build()
            .unwrap();

        assert_eq!(request.reasoning_effort, Some(ReasoningEffort::High));
    }

    #[test]
    fn tool_call_defaults_type_on_deserialize() {
        let tool_call: ChatCompletionMessageToolCall = serde_json::from_value(serde_json::json!({
            "id": "call_123",
            "function": {
                "name": "get_weather",
                "arguments": "{\"location\":\"SF\"}"
            }
        }))
        .unwrap();

        assert_eq!(tool_call.r#type, FunctionType::Function);
    }

    #[test]
    fn tool_call_serializes_type_for_wire_compat() {
        let tool_call = ChatCompletionMessageToolCall {
            id: "call_123".into(),
            r#type: FunctionType::Function,
            function: FunctionCall {
                name: "get_weather".into(),
                arguments: "{\"location\":\"SF\"}".into(),
            },
        };

        let json = serde_json::to_value(tool_call).unwrap();
        assert_eq!(json["type"], "function");
    }

    // -- dict-format arguments tests --

    #[test]
    fn function_call_accepts_string_arguments() {
        let fc: FunctionCall = serde_json::from_value(serde_json::json!({
            "name": "get_weather",
            "arguments": "{\"location\":\"SF\"}"
        }))
        .unwrap();
        assert_eq!(fc.arguments, "{\"location\":\"SF\"}");
    }

    #[test]
    fn function_call_accepts_dict_arguments() {
        let fc: FunctionCall = serde_json::from_value(serde_json::json!({
            "name": "get_weather",
            "arguments": {"location": "SF"}
        }))
        .unwrap();
        assert_eq!(fc.arguments, "{\"location\":\"SF\"}");
    }

    #[test]
    fn function_call_rejects_integer_arguments() {
        let result = serde_json::from_value::<FunctionCall>(serde_json::json!({
            "name": "f",
            "arguments": 42
        }));
        assert!(result.is_err());
    }

    #[test]
    fn function_call_rejects_boolean_arguments() {
        let result = serde_json::from_value::<FunctionCall>(serde_json::json!({
            "name": "f",
            "arguments": true
        }));
        assert!(result.is_err());
    }

    #[test]
    fn function_call_rejects_null_arguments() {
        let result = serde_json::from_value::<FunctionCall>(serde_json::json!({
            "name": "f",
            "arguments": null
        }));
        assert!(result.is_err());
    }

    #[test]
    fn function_call_rejects_array_arguments() {
        let result = serde_json::from_value::<FunctionCall>(serde_json::json!({
            "name": "f",
            "arguments": [1, 2, 3]
        }));
        assert!(result.is_err());
    }

    #[test]
    fn function_call_stream_null_arguments_produces_none() {
        let fcs: FunctionCallStream = serde_json::from_value(serde_json::json!({
            "name": "f",
            "arguments": null
        }))
        .unwrap();
        assert_eq!(fcs.arguments, None);
    }

    #[test]
    fn function_call_stream_rejects_integer_arguments() {
        let result = serde_json::from_value::<FunctionCallStream>(serde_json::json!({
            "name": "f",
            "arguments": 42
        }));
        assert!(result.is_err());
    }

    #[test]
    fn function_call_stream_rejects_boolean_arguments() {
        let result = serde_json::from_value::<FunctionCallStream>(serde_json::json!({
            "name": "f",
            "arguments": true
        }));
        assert!(result.is_err());
    }

    #[test]
    fn function_call_stream_accepts_dict_arguments() {
        let fcs: FunctionCallStream = serde_json::from_value(serde_json::json!({
            "name": "get_weather",
            "arguments": {"location": "SF"}
        }))
        .unwrap();
        assert_eq!(fcs.arguments.as_deref(), Some("{\"location\":\"SF\"}"));
    }

    #[test]
    fn function_call_stream_accepts_null_arguments() {
        let fcs: FunctionCallStream = serde_json::from_value(serde_json::json!({
            "name": "get_weather"
        }))
        .unwrap();
        assert_eq!(fcs.arguments, None);
    }

    #[test]
    fn tool_call_with_dict_arguments_roundtrip() {
        let tc: ChatCompletionMessageToolCall = serde_json::from_value(serde_json::json!({
            "id": "call_abc",
            "type": "function",
            "function": {
                "name": "search",
                "arguments": {"query": "hello", "limit": 10}
            }
        }))
        .unwrap();
        // Compare as parsed JSON values since key order is non-deterministic
        let parsed: serde_json::Value = serde_json::from_str(&tc.function.arguments).unwrap();
        assert_eq!(parsed, serde_json::json!({"query": "hello", "limit": 10}));
        // Re-serialisation produces a string, not an object
        let json = serde_json::to_value(&tc).unwrap();
        assert!(json["function"]["arguments"].is_string());
    }

    #[test]
    fn stream_delta_function_call_accepts_dict_arguments() {
        let delta: ChatCompletionStreamResponseDeltaFunctionCall =
            serde_json::from_value(serde_json::json!({
                "name": "get_weather",
                "arguments": {"location": "SF"}
            }))
            .unwrap();
        assert_eq!(delta.arguments.as_deref(), Some("{\"location\":\"SF\"}"));
    }

    fn parse_content_part(json: serde_json::Value) -> ChatCompletionRequestUserMessageContentPart {
        serde_json::from_value(json).expect("content part deserialization failed")
    }

    #[test]
    fn image_url_url_and_top_level_uuid() {
        let part = parse_content_part(serde_json::json!({
            "type": "image_url",
            "image_url": {"url": "https://x.example/y.png"},
            "uuid": "image-123"
        }));

        match part {
            ChatCompletionRequestUserMessageContentPart::ImageUrl(part) => {
                assert_eq!(part.uuid.as_deref(), Some("image-123"));
                assert_eq!(
                    part.image_url.as_ref().map(|image| image.url.as_str()),
                    Some("https://x.example/y.png")
                );
            }
            _ => panic!("expected image_url part"),
        }
    }

    #[test]
    fn image_url_null_and_top_level_uuid() {
        let part = parse_content_part(serde_json::json!({
            "type": "image_url",
            "image_url": null,
            "uuid": "sku-1234-a"
        }));

        match part {
            ChatCompletionRequestUserMessageContentPart::ImageUrl(part) => {
                assert!(part.image_url.is_none());
                assert_eq!(part.uuid.as_deref(), Some("sku-1234-a"));
            }
            _ => panic!("expected image_url part"),
        }
    }

    #[test]
    fn empty_media_urls_deserialize_as_uuid_only() {
        for (part_type, media_field, uuid) in [
            ("image_url", "image_url", "image-cache-key"),
            ("video_url", "video_url", "video-cache-key"),
            ("audio_url", "audio_url", "audio-cache-key"),
        ] {
            let part = parse_content_part(serde_json::json!({
                "type": part_type,
                (media_field): {"url": ""},
                "uuid": uuid
            }));
            let json = serde_json::to_value(part).unwrap();

            assert!(json[media_field].is_null());
            assert_eq!(json["uuid"], uuid);
        }
    }

    #[test]
    fn image_url_null_without_uuid_deserializes_for_use_site_validation() {
        let part = parse_content_part(serde_json::json!({
            "type": "image_url",
            "image_url": null
        }));

        match part {
            ChatCompletionRequestUserMessageContentPart::ImageUrl(part) => {
                assert!(part.image_url.is_none());
                assert!(part.uuid.is_none());
            }
            _ => panic!("expected image_url part"),
        }
    }

    #[test]
    fn image_url_serialize_uuid_only_uses_null_image_url() {
        let part = ChatCompletionRequestMessageContentPartImage {
            image_url: None,
            uuid: Some("image-123".to_string()),
        };
        let json = serde_json::to_value(part).unwrap();

        assert!(json["image_url"].is_null());
        assert_eq!(json["uuid"], "image-123");
    }

    #[test]
    fn cached_media_builders_allow_omitting_urls() {
        let image = ChatCompletionRequestMessageContentPartImageArgs::default()
            .uuid("image-123")
            .build()
            .unwrap();
        let video = ChatCompletionRequestMessageContentPartVideoArgs::default()
            .uuid("video-123")
            .build()
            .unwrap();
        let audio = ChatCompletionRequestMessageContentPartAudioUrlArgs::default()
            .uuid("audio-123")
            .build()
            .unwrap();

        let image_json = serde_json::to_value(image).unwrap();
        let video_json = serde_json::to_value(video).unwrap();
        let audio_json = serde_json::to_value(audio).unwrap();
        assert!(image_json["image_url"].is_null());
        assert!(video_json["video_url"].is_null());
        assert!(audio_json["audio_url"].is_null());
    }

    #[test]
    fn image_url_uuid_accepts_opaque_string() {
        let part = parse_content_part(serde_json::json!({
            "type": "image_url",
            "image_url": {"url": "https://x.example/y.png"},
            "uuid": "img-ac3921de680bb217"
        }));

        match part {
            ChatCompletionRequestUserMessageContentPart::ImageUrl(part) => {
                assert_eq!(part.uuid.as_deref(), Some("img-ac3921de680bb217"));
            }
            _ => panic!("expected image_url part"),
        }
    }

    #[test]
    fn url_conversions_preserve_required_urls() {
        let image: ImageUrl = "https://x.example/image.png".into();
        let video: VideoUrl = "https://x.example/video.mp4".into();
        let audio: AudioUrl = "https://x.example/audio.wav".into();

        assert_eq!(image.url.as_str(), "https://x.example/image.png");
        assert_eq!(video.url.as_str(), "https://x.example/video.mp4");
        assert_eq!(audio.url.as_str(), "https://x.example/audio.wav");
    }

    #[test]
    fn invalid_media_urls_remain_rejected() {
        for (part_type, media_field) in [
            ("image_url", "image_url"),
            ("video_url", "video_url"),
            ("audio_url", "audio_url"),
        ] {
            let result = serde_json::from_value::<ChatCompletionRequestUserMessageContentPart>(
                serde_json::json!({
                    "type": part_type,
                    (media_field): {"url": "not a url"},
                    "uuid": "cache-key"
                }),
            );

            assert!(result.is_err(), "{part_type} accepted an invalid URL");
        }
    }

    #[test]
    fn legacy_nested_media_uuids_remain_accepted() {
        let legacy_uuid = "92b888ad-e64a-478f-b688-5091e16544e3";

        for (part_type, media_field, url) in [
            ("image_url", "image_url", "https://x.example/image.png"),
            ("video_url", "video_url", "https://x.example/video.mp4"),
            ("audio_url", "audio_url", "https://x.example/audio.wav"),
        ] {
            let part = parse_content_part(serde_json::json!({
                "type": part_type,
                (media_field): {"url": url, "uuid": legacy_uuid}
            }));
            let json = serde_json::to_value(part).unwrap();

            assert_eq!(json[media_field]["url"], url);
            assert_eq!(json[media_field]["uuid"], legacy_uuid);
            assert!(json.get("uuid").is_none());
        }
    }

    #[test]
    fn video_url_null_and_top_level_uuid() {
        let part = parse_content_part(serde_json::json!({
            "type": "video_url",
            "video_url": null,
            "uuid": "video-cache-key"
        }));

        match part {
            ChatCompletionRequestUserMessageContentPart::VideoUrl(part) => {
                assert!(part.video_url.is_none());
                assert_eq!(part.uuid.as_deref(), Some("video-cache-key"));
            }
            _ => panic!("expected video_url part"),
        }
    }

    #[test]
    fn audio_url_null_and_top_level_uuid() {
        let part = parse_content_part(serde_json::json!({
            "type": "audio_url",
            "audio_url": null,
            "uuid": "audio-cache-key"
        }));

        match part {
            ChatCompletionRequestUserMessageContentPart::AudioUrl(part) => {
                assert!(part.audio_url.is_none());
                assert_eq!(part.uuid.as_deref(), Some("audio-cache-key"));
            }
            _ => panic!("expected audio_url part"),
        }
    }

    #[test]
    fn message_content_array_preserves_uuid_alignment() {
        let payload = serde_json::json!({
            "role": "user",
            "content": [
                {"type": "text", "text": "describe these"},
                {
                    "type": "image_url",
                    "image_url": {"url": "https://x.example/img1.png"},
                    "uuid": "image-1"
                },
                {"type": "image_url", "image_url": null, "uuid": "image-1"}
            ]
        });
        let message: ChatCompletionRequestUserMessage = serde_json::from_value(payload).unwrap();
        let ChatCompletionRequestUserMessageContent::Array(parts) = message.content else {
            panic!("expected content array");
        };

        assert_eq!(parts.len(), 3);
        match &parts[1] {
            ChatCompletionRequestUserMessageContentPart::ImageUrl(part) => {
                assert!(
                    part.image_url
                        .as_ref()
                        .map(|image| image.url.as_str())
                        .is_some()
                );
                assert_eq!(part.uuid.as_deref(), Some("image-1"));
            }
            _ => panic!("parts[1] should be image_url"),
        }
        match &parts[2] {
            ChatCompletionRequestUserMessageContentPart::ImageUrl(part) => {
                assert!(part.image_url.is_none());
                assert_eq!(part.uuid.as_deref(), Some("image-1"));
            }
            _ => panic!("parts[2] should be image_url"),
        }
    }

    #[test]
    fn tool_message_accepts_media_content() {
        let message: ChatCompletionRequestMessage = serde_json::from_value(serde_json::json!({
            "role": "tool",
            "tool_call_id": "call_media",
            "content": [
                {"type": "text", "text": "Screenshot captured"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "data:image/png;base64,aGVsbG8="
                    }
                },
                {
                    "type": "video_url",
                    "video_url": {
                        "url": "https://example.com/clip.mp4"
                    }
                },
                {
                    "type": "audio_url",
                    "audio_url": {
                        "url": "https://example.com/audio.wav"
                    }
                }
            ]
        }))
        .unwrap();

        let ChatCompletionRequestMessage::Tool(tool) = message else {
            panic!("expected tool message");
        };
        let ChatCompletionRequestToolMessageContent::Array(parts) = tool.content else {
            panic!("expected array content");
        };
        assert!(matches!(
            parts[1],
            ChatCompletionRequestToolMessageContentPart::ImageUrl(_)
        ));
        assert!(matches!(
            parts[2],
            ChatCompletionRequestToolMessageContentPart::VideoUrl(_)
        ));
        assert!(matches!(
            parts[3],
            ChatCompletionRequestToolMessageContentPart::AudioUrl(_)
        ));
    }

    #[test]
    fn chat_logprob_serializes_token_id_when_present() {
        let logprob = ChatCompletionTokenLogprob {
            token: " hello".into(),
            logprob: -0.12,
            token_id: Some(123),
            bytes: Some(vec![32, 104, 101, 108, 108, 111]),
            top_logprobs: vec![],
        };

        let json = serde_json::to_value(logprob).unwrap();

        assert_eq!(json["token_id"], 123);
    }

    #[test]
    fn chat_logprob_deserializes_optional_fields() {
        let choice_logprobs: ChatChoiceLogprobs = serde_json::from_value(serde_json::json!({
            "content": [{
                "token": " hello",
                "logprob": -0.12,
                "top_logprobs": []
            }]
        }))
        .unwrap();
        let token_logprob: ChatCompletionTokenLogprob = serde_json::from_value(serde_json::json!({
            "token": " hello",
            "logprob": -0.12,
            "token_id": 123,
            "bytes": [32, 104, 101, 108, 108, 111],
            "top_logprobs": []
        }))
        .unwrap();

        assert_eq!(choice_logprobs.content.as_ref().unwrap()[0].token_id, None);
        assert!(choice_logprobs.refusal.is_none());
        assert_eq!(token_logprob.token_id, Some(123));
        assert_eq!(token_logprob.bytes, Some(vec![32, 104, 101, 108, 108, 111]));
    }

    #[test]
    fn chat_logprob_preserves_nullable_fields() {
        let choice_logprobs = ChatChoiceLogprobs {
            content: None,
            refusal: None,
        };
        let token_logprob = ChatCompletionTokenLogprob {
            token: " hello".into(),
            logprob: -0.12,
            token_id: None,
            bytes: None,
            top_logprobs: vec![],
        };

        let choice_json = serde_json::to_value(choice_logprobs).unwrap();
        let token_json = serde_json::to_value(token_logprob).unwrap();

        assert_eq!(choice_json["content"], serde_json::Value::Null);
        assert_eq!(choice_json["refusal"], serde_json::Value::Null);
        assert!(token_json.get("token_id").is_none());
        assert_eq!(token_json["bytes"], serde_json::Value::Null);
    }

    #[test]
    #[allow(deprecated)]
    fn chat_response_omits_absent_optional_fields() {
        let response = CreateChatCompletionResponse {
            id: "chatcmpl_dummy".into(),
            choices: vec![ChatChoice {
                index: 0,
                message: ChatCompletionResponseMessage {
                    content: Some(ChatCompletionMessageContent::Text("hello".into())),
                    refusal: None,
                    tool_calls: None,
                    role: Role::Assistant,
                    function_call: None,
                    audio: None,
                    reasoning_content: None,
                },
                finish_reason: Some(FinishReason::Stop),
                logprobs: None,
            }],
            created: 0,
            model: "dummy-model".into(),
            service_tier: None,
            system_fingerprint: None,
            object: "chat.completion".into(),
            usage: None,
        };

        let json = serde_json::to_value(response).unwrap();

        for absent in ["usage", "service_tier", "system_fingerprint"] {
            assert!(json.get(absent).is_none(), "{absent} should be omitted");
        }
        let choice = &json["choices"][0];
        assert_eq!(choice["finish_reason"], "stop");
        assert_eq!(choice["logprobs"], serde_json::Value::Null);
        let message = &choice["message"];
        assert_eq!(message["refusal"], serde_json::Value::Null);
        for absent in ["tool_calls", "function_call", "audio", "reasoning_content"] {
            assert!(
                message.get(absent).is_none(),
                "message.{absent} should be omitted"
            );
        }
    }

    #[test]
    fn stream_response_omits_absent_optional_fields() {
        let chunk = CreateChatCompletionStreamResponse {
            id: "chatcmpl_dummy".into(),
            choices: vec![ChatChoiceStream {
                index: 0,
                delta: ChatCompletionStreamResponseDelta {
                    content: Some(ChatCompletionMessageContent::Text("hello".into())),
                    function_call: None,
                    tool_calls: None,
                    role: None,
                    refusal: None,
                    reasoning_content: None,
                },
                finish_reason: None,
                logprobs: None,
            }],
            created: 0,
            model: "dummy-model".into(),
            service_tier: None,
            system_fingerprint: None,
            object: "chat.completion.chunk".into(),
            usage: None,
        };

        let json = serde_json::to_value(chunk).unwrap();

        for absent in ["usage", "service_tier", "system_fingerprint"] {
            assert!(json.get(absent).is_none(), "{absent} should be omitted");
        }
    }

    #[test]
    fn stream_tool_call_continuation_chunk_omits_absent_fields() {
        let chunk = ChatCompletionMessageToolCallChunk {
            index: 0,
            id: None,
            r#type: None,
            function: Some(FunctionCallStream {
                name: None,
                arguments: Some("{\"a\":".into()),
            }),
        };

        let json = serde_json::to_value(chunk).unwrap();

        assert!(json.get("id").is_none());
        assert!(json.get("type").is_none());
        assert!(json["function"].get("name").is_none());
        assert_eq!(json["function"]["arguments"], "{\"a\":");
    }

    #[test]
    fn stream_delta_function_call_omits_absent_fields() {
        let function_call = ChatCompletionStreamResponseDeltaFunctionCall {
            name: None,
            arguments: Some("{}".into()),
        };

        let json = serde_json::to_value(function_call).unwrap();

        assert!(json.get("name").is_none());
        assert_eq!(json["arguments"], "{}");
    }

    #[test]
    fn usage_details_omit_absent_fields() {
        let response = CreateChatCompletionResponse {
            id: "chatcmpl_dummy".into(),
            choices: vec![],
            created: 0,
            model: "dummy-model".into(),
            service_tier: None,
            system_fingerprint: None,
            object: "chat.completion".into(),
            usage: Some(CompletionUsage {
                prompt_tokens: 10,
                completion_tokens: 25,
                total_tokens: 35,
                prompt_tokens_details: Some(PromptTokensDetails {
                    audio_tokens: None,
                    cached_tokens: Some(0),
                }),
                completion_tokens_details: Some(CompletionTokensDetails {
                    reasoning_tokens: Some(5),
                    ..Default::default()
                }),
            }),
        };

        let json = serde_json::to_value(&response).unwrap();
        let usage = &json["usage"];

        assert_eq!(usage["total_tokens"], 35);
        assert_eq!(usage["prompt_tokens_details"]["cached_tokens"], 0);
        assert!(
            usage["prompt_tokens_details"].get("audio_tokens").is_none(),
            "audio_tokens should be omitted, not null"
        );
        assert_eq!(usage["completion_tokens_details"]["reasoning_tokens"], 5);
        for absent in [
            "accepted_prediction_tokens",
            "audio_tokens",
            "rejected_prediction_tokens",
        ] {
            assert!(
                usage["completion_tokens_details"].get(absent).is_none(),
                "{absent} should be omitted"
            );
        }

        let roundtrip: CreateChatCompletionResponse = serde_json::from_value(json).unwrap();
        assert_eq!(roundtrip, response);
    }

    // -- Kimi-style system tools / assistant partial tests --

    #[test]
    fn effective_tool_set_unions_top_level_and_dynamic_system_tools() {
        let request: CreateChatCompletionRequest = serde_json::from_value(serde_json::json!({
            "model": "dummy-kimi-model",
            "tools": [{
                "type": "function",
                "function": {"name": "add", "parameters": {"type": "object"}}
            }],
            "messages": [
                {"role": "user", "content": "start"},
                {
                    "role": "system",
                    "tools": [
                        {
                            "type": "function",
                            "function": {"name": "lookup", "parameters": {"type": "object"}}
                        },
                        {"name": "search", "parameters": {"type": "object"}},
                        {"description": "no name, skipped"}
                    ]
                },
                {"role": "user", "content": "continue"}
            ]
        }))
        .unwrap();

        assert!(request.has_effective_tools());
        assert_eq!(request.dynamic_system_tools().count(), 3);
        assert_eq!(
            request.effective_tool_names().collect::<Vec<_>>(),
            ["add", "lookup", "search"],
            "top-level first, then dynamic in message order; wrapped and bare shapes both resolve"
        );
        for name in ["add", "lookup", "search"] {
            assert!(
                request.effective_tool_contains(name),
                "{name} should be found"
            );
        }
        assert!(!request.effective_tool_contains("missing"));
        assert!(
            !request.effective_tool_contains("no name, skipped"),
            "a description is not a name"
        );
    }

    #[test]
    fn effective_tool_set_is_empty_without_any_declaration() {
        for payload in [
            serde_json::json!({
                "model": "m",
                "messages": [{"role": "user", "content": "hi"}]
            }),
            serde_json::json!({
                "model": "m",
                "tools": [],
                "messages": [{"role": "system", "content": "plain system text"}]
            }),
        ] {
            let request: CreateChatCompletionRequest = serde_json::from_value(payload).unwrap();
            assert!(!request.has_effective_tools());
            assert_eq!(request.effective_tool_names().count(), 0);
            assert!(!request.effective_tool_contains("anything"));
        }
    }

    #[test]
    fn dynamic_system_tools_alone_count_as_effective_tools() {
        let request: CreateChatCompletionRequest = serde_json::from_value(serde_json::json!({
            "model": "dummy-kimi-model",
            "messages": [
                {"role": "system", "tools": [{"name": "lookup"}]},
                {"role": "user", "content": "go"}
            ]
        }))
        .unwrap();

        assert!(
            request.tools.is_none(),
            "nothing was folded into top-level tools"
        );
        assert!(request.has_effective_tools());
        assert!(request.effective_tool_contains("lookup"));
    }

    #[test]
    fn dynamic_tool_name_handles_wrapped_bare_and_invalid_shapes() {
        assert_eq!(
            dynamic_tool_name(&serde_json::json!({"type": "function", "function": {"name": "a"}})),
            Some("a")
        );
        assert_eq!(
            dynamic_tool_name(&serde_json::json!({"name": "b"})),
            Some("b")
        );
        assert_eq!(dynamic_tool_name(&serde_json::json!({"name": 7})), None);
    }

    #[test]
    fn system_message_without_content_is_rejected_unless_it_declares_tools() {
        // Same leading text as upstream's derived error, so clients and
        // tests matching on "missing field `content`" keep working.
        for (label, message) in [
            ("nothing", serde_json::json!({"role": "system"})),
            (
                "empty tools",
                serde_json::json!({"role": "system", "tools": []}),
            ),
        ] {
            let error =
                serde_json::from_value::<ChatCompletionRequestMessage>(message).expect_err(label);
            assert!(
                error.to_string().starts_with("missing field `content`"),
                "{label}: unexpected error {error}"
            );
        }
    }

    #[test]
    fn system_message_guard_leaves_valid_shapes_alone() {
        for (label, message) in [
            (
                "content only",
                serde_json::json!({"role": "system", "content": "hi"}),
            ),
            (
                "content parts",
                serde_json::json!({"role": "system", "content": [{"type": "text", "text": "hi"}]}),
            ),
            (
                "tools only",
                serde_json::json!({"role": "system", "tools": [{"name": "lookup"}]}),
            ),
            (
                "content and tools (renderer decides)",
                serde_json::json!({"role": "system", "content": "hi", "tools": [{"name": "lookup"}]}),
            ),
        ] {
            let parsed: ChatCompletionRequestMessage =
                serde_json::from_value(message).unwrap_or_else(|e| panic!("{label}: {e}"));
            assert!(
                matches!(parsed, ChatCompletionRequestMessage::System(_)),
                "{label}"
            );
        }
    }

    #[test]
    fn message_rejects_tools_and_partial_on_wrong_roles() {
        let tools = serde_json::json!([{"name": "lookup"}]);
        for (label, message, needle) in [
            (
                "tools on user",
                serde_json::json!({"role": "user", "content": "hi", "tools": tools}),
                "`tools` is only accepted on system messages, not on role user",
            ),
            (
                "tools on assistant",
                serde_json::json!({"role": "assistant", "content": "hi", "tools": tools}),
                "`tools` is only accepted on system messages, not on role assistant",
            ),
            (
                // Upstream type without a `tools` field: accepting would drop them.
                "tools on developer",
                serde_json::json!({"role": "developer", "content": "hi", "tools": tools}),
                "`tools` is only accepted on system messages, not on role developer",
            ),
            (
                "partial on user",
                serde_json::json!({"role": "user", "content": "hi", "partial": true}),
                "`partial` is only accepted on assistant messages, not on role user",
            ),
            (
                "partial on system",
                serde_json::json!({"role": "system", "content": "hi", "partial": false}),
                "`partial` is only accepted on assistant messages, not on role system",
            ),
        ] {
            let error = serde_json::from_value::<ChatCompletionRequestMessage>(message)
                .expect_err(label)
                .to_string();
            assert!(error.contains(needle), "{label}: {error}");
        }

        for message in [
            serde_json::json!({"role": "user", "content": "hi", "tools": null}),
            serde_json::json!({"role": "user", "content": "hi", "partial": null}),
        ] {
            serde_json::from_value::<ChatCompletionRequestMessage>(message).unwrap();
        }

        for message in [
            serde_json::json!({"role": "system", "tools": tools}),
            serde_json::json!({"role": "assistant", "content": "seed", "partial": true}),
            serde_json::json!({"role": "user", "content": "hi", "x_vendor": 1}),
        ] {
            serde_json::from_value::<ChatCompletionRequestMessage>(message).unwrap();
        }
    }

    #[test]
    fn message_rejects_duplicate_top_level_keys() {
        for (label, raw) in [
            (
                "role twice",
                r#"{"role":"user","content":"hi","role":"system"}"#,
            ),
            (
                "content twice",
                r#"{"role":"user","content":"a","content":"b"}"#,
            ),
        ] {
            let error = serde_json::from_str::<ChatCompletionRequestMessage>(raw)
                .expect_err(label)
                .to_string();
            assert!(error.contains("duplicate field"), "{label}: {error}");
        }
    }

    #[test]
    fn message_rejects_duplicate_fields_in_nested_typed_objects() {
        let tool_call = r#"{
            "role":"assistant",
            "content":null,
            "tool_calls":[{
                "id":"first",
                "id":"second",
                "type":"function",
                "function":{"name":"lookup","arguments":"{}"}
            }]
        }"#;
        let error = serde_json::from_str::<ChatCompletionRequestMessage>(tool_call)
            .unwrap_err()
            .to_string();
        assert!(error.contains("duplicate field `id`"), "{error}");

        let content_part = r#"{
            "role":"user",
            "content":[{"type":"text","text":"first","text":"second"}]
        }"#;
        assert!(serde_json::from_str::<ChatCompletionRequestMessage>(content_part).is_err());
    }

    #[test]
    fn default_system_message_round_trips() {
        let message = ChatCompletionRequestSystemMessage::default();
        let json = serde_json::to_value(&message).unwrap();
        assert_eq!(json, serde_json::json!({"content": ""}));
        let back: ChatCompletionRequestSystemMessage = serde_json::from_value(json).unwrap();
        assert_eq!(back, message);

        let built = ChatCompletionRequestSystemMessageArgs::default()
            .name("ops")
            .build()
            .unwrap();
        let json = serde_json::to_value(&built).unwrap();
        assert_eq!(json, serde_json::json!({"content": "", "name": "ops"}));
        serde_json::from_value::<ChatCompletionRequestSystemMessage>(json).unwrap();
    }

    #[test]
    fn system_message_guard_keeps_field_level_errors() {
        let error = serde_json::from_value::<ChatCompletionRequestMessage>(serde_json::json!({
            "role": "system",
            "tools": "lookup"
        }))
        .unwrap_err();
        assert!(
            !error.to_string().starts_with("missing field `content`"),
            "field error expected, got {error}"
        );
    }

    #[test]
    fn system_message_canonicalizes_missing_content_with_tools() {
        let request: CreateChatCompletionRequest = serde_json::from_value(serde_json::json!({
            "model": "dummy-kimi-model",
            "messages": [
                {
                    "role": "system",
                    "tools": [
                        {
                            "name": "lookup",
                            "description": "dummy lookup tool",
                            "parameters": {
                                "type": "object",
                                "properties": {
                                    "query": { "type": "string" }
                                }
                            }
                        }
                    ]
                },
                {
                    "role": "assistant",
                    "content": "synthetic prefill",
                    "partial": true
                },
                {
                    "role": "user",
                    "content": "continue"
                }
            ]
        }))
        .unwrap();

        match &request.messages[0] {
            ChatCompletionRequestMessage::System(system) => {
                assert_eq!(
                    system.content,
                    ChatCompletionRequestSystemMessageContent::Text(String::new())
                );
                let tools = system.tools.as_ref().expect("tools should be present");
                assert_eq!(tools.len(), 1);
                assert_eq!(tools[0]["name"], "lookup");
            }
            other => panic!("expected system message, got {other:?}"),
        }

        match &request.messages[1] {
            ChatCompletionRequestMessage::Assistant(assistant) => {
                assert_eq!(assistant.partial, Some(true));
            }
            other => panic!("expected assistant message, got {other:?}"),
        }

        // Explicit null has the same wire meaning as omission. Both serialize
        // to the canonical required-content shape.
        let message: ChatCompletionRequestMessage = serde_json::from_value(serde_json::json!({
            "role": "system",
            "content": null,
            "tools": [{"name": "lookup"}]
        }))
        .unwrap();
        let ChatCompletionRequestMessage::System(system) = &message else {
            panic!("expected system message");
        };
        assert_eq!(
            system.content,
            ChatCompletionRequestSystemMessageContent::Text(String::new())
        );
        assert_eq!(
            serde_json::to_value(message).unwrap(),
            serde_json::json!({
                "role": "system",
                "content": "",
                "tools": [{"name": "lookup"}]
            })
        );
    }

    #[test]
    fn kimi_style_request_preserves_tools_and_canonicalizes_content() {
        let payload = serde_json::json!({
            "model": "dummy-kimi-model",
            "messages": [
                {
                    "role": "system",
                    "tools": [
                        {
                            "name": "lookup",
                            "description": "dummy lookup tool",
                            "parameters": {
                                "type": "object",
                                "properties": {
                                    "query": { "type": "string" }
                                }
                            },
                            "vendor_hint": { "priority": 3 }
                        }
                    ]
                },
                {
                    "role": "assistant",
                    "content": "synthetic prefill",
                    "partial": true
                },
                {
                    "role": "user",
                    "content": "continue"
                }
            ]
        });

        let request: CreateChatCompletionRequest = serde_json::from_value(payload.clone()).unwrap();
        let serialized = serde_json::to_value(request).unwrap();
        let mut canonical = payload;
        canonical["messages"][0]["content"] = serde_json::json!("");

        assert_eq!(serialized, canonical);
    }

    #[test]
    fn system_message_tools_preserve_official_wrapped_shape() {
        let payload = serde_json::json!({
            "model": "dummy-kimi-model",
            "messages": [
                {
                    "role": "system",
                    "tools": [
                        {
                            "type": "function",
                            "function": {
                                "name": "lookup",
                                "description": "dummy lookup tool",
                                "parameters": {
                                    "type": "object",
                                    "properties": {
                                        "query": { "type": "string" }
                                    },
                                    "required": ["query"]
                                },
                                "strict": true
                            }
                        }
                    ]
                },
                { "role": "user", "content": "continue" }
            ]
        });

        let request: CreateChatCompletionRequest = serde_json::from_value(payload.clone()).unwrap();
        match &request.messages[0] {
            ChatCompletionRequestMessage::System(system) => {
                let tools = system.tools.as_ref().expect("tools should be present");
                assert_eq!(tools[0]["type"], "function");
                assert_eq!(tools[0]["function"]["name"], "lookup");
            }
            other => panic!("expected system message, got {other:?}"),
        }

        let mut canonical = payload;
        canonical["messages"][0]["content"] = serde_json::json!("");
        assert_eq!(serde_json::to_value(request).unwrap(), canonical);
    }

    #[test]
    fn assistant_message_omits_partial_when_absent() {
        let assistant = ChatCompletionRequestAssistantMessageArgs::default()
            .content("hello")
            .build()
            .unwrap();

        assert_eq!(assistant.partial, None);
        let json = serde_json::to_value(&assistant).unwrap();
        assert!(
            json.get("partial").is_none(),
            "partial should be omitted when absent"
        );
    }

    #[test]
    fn assistant_message_serializes_partial_when_present() {
        let assistant = ChatCompletionRequestAssistantMessageArgs::default()
            .content("synthetic prefill")
            .partial(true)
            .build()
            .unwrap();

        let json = serde_json::to_value(&assistant).unwrap();
        assert_eq!(json["partial"], true);

        let roundtrip: ChatCompletionRequestAssistantMessage =
            serde_json::from_value(json).unwrap();
        assert_eq!(roundtrip, assistant);
    }

    #[test]
    fn system_message_from_upstream_preserves_content_and_leaves_tools_none() {
        let upstream = async_openai::types::chat::ChatCompletionRequestSystemMessage {
            content: async_openai::types::chat::ChatCompletionRequestSystemMessageContent::Text(
                "hi".into(),
            ),
            name: None,
        };

        let owned: ChatCompletionRequestSystemMessage = upstream.into();
        assert!(owned.tools.is_none());
        match owned.content {
            ChatCompletionRequestSystemMessageContent::Text(text) => assert_eq!(text, "hi"),
            other => panic!("expected text content, got {other:?}"),
        }
    }

    #[test]
    fn system_message_restores_upstream_convenience_conversions() {
        let from_content = ChatCompletionRequestSystemMessage::from(
            ChatCompletionRequestSystemMessageContent::Text("from content".into()),
        );
        let from_str = ChatCompletionRequestSystemMessage::from("from str");
        let from_string = ChatCompletionRequestSystemMessage::from(String::from("from string"));

        for (message, expected) in [
            (from_content, "from content"),
            (from_str, "from str"),
            (from_string, "from string"),
        ] {
            assert_eq!(
                message.content,
                ChatCompletionRequestSystemMessageContent::Text(expected.into())
            );
            assert!(message.name.is_none());
            assert!(message.tools.is_none());
        }
    }
}