openai-interface 0.13.0

//! vLLM's proprietary extensions to the OpenAI-compatible API.
//!
//! Everything in this module is gated on the `vllm` cargo feature.
//!
//! vLLM serves models behind OpenAI-compatible endpoints, but accepts a
//! large set of request parameters that OpenAI's API does not define, and
//! returns extra fields OpenAI never sends. With the official Python client
//! those parameters have to be smuggled through `extra_body`; here they are
//! typed.
//!
//! The types are split in two because the two text-generation endpoints do
//! not accept the same set:
//!
//! - [`SamplingParams`] — decoding knobs, accepted by both
//!   `/v1/chat/completions` and the legacy `/v1/completions`.
//! - [`ChatParams`] — chat-template rendering, structured outputs, KV
//!   transfer and scheduling, accepted by `/v1/chat/completions` only.
//!
//! Both are `#[serde(flatten)]`ed into their request bodies, so the wire
//! format is identical to what `extra_body` produces: every field lands at
//! the top level of the JSON body.
//!
//! ```rust
//! # #[cfg(feature = "vllm")] {
//! use openai_interface::chat::create::request::{Message, RequestBody};
//! use openai_interface::vllm::SamplingParams;
//!
//! let request = RequestBody {
//!     messages: vec![Message::user("Hello")],
//!     model: "Qwen/Qwen3-8B".to_string(),
//!     vllm_sampling: Some(SamplingParams {
//!         min_p: Some(0.1),
//!         repetition_penalty: Some(1.05),
//!         ..Default::default()
//!     }),
//!     ..Default::default()
//! };
//!
//! let json = serde_json::to_value(&request).unwrap();
//! assert_eq!(json["min_p"], serde_json::json!(0.1f32));
//! assert_eq!(json["repetition_penalty"], serde_json::json!(1.05f32));
//! # }
//! ```
//!
//! # Note on `top_k`
//!
//! `top_k` is not defined here: it is already a field of
//! [`RequestBody`](crate::chat::create::request::RequestBody), gated on
//! `any(feature = "qwen", feature = "vllm")` because Qwen and vLLM spell it
//! the same way. Defining it twice would emit the key twice.
//!
//! # Differences that need no extra field
//!
//! Some vLLM divergences are behavioural, and are documented where the
//! affected OpenAI-standard field lives:
//!
//! - `suffix` is rejected outright on `/v1/completions`.
//! - `image_url.detail` is rejected outright.
//! - `response_format.json_schema.strict` is parsed but has no effect:
//!   guided decoding always enforces the schema.
//! - When both `max_tokens` and `max_completion_tokens` are set,
//!   `max_tokens` wins.
//! - The chain of thought arrives as `reasoning`, not `reasoning_content` —
//!   see the `reasoning` fields on the response message and streamed delta.
//!
//! # Not implemented
//!
//! vLLM also exposes endpoints OpenAI has no equivalent of: `/v1/score`,
//! `/rerank`, `/pooling`, `/classify`, `/tokenize`, `/detokenize`, the
//! `POST /v1/{chat/completions,completions}/render` prompt-rendering
//! endpoints, `POST /v1/chat/completions/batch`, and the admin endpoints
//! (`/load`, `/sleep`, `/wake_up`, `/is_sleeping`, `/reset_prefix_cache`).
//! None of them are modelled by this crate; this feature covers the fields
//! vLLM adds to the OpenAI endpoints it does implement.
//!
//! See [vLLM's OpenAI-compatible server
//! docs](https://docs.vllm.ai/en/latest/serving/online_serving/openai_compatible_server/).
#![cfg(feature = "vllm")]

use serde::{Deserialize, Serialize};

/// Extra sampling parameters accepted by both `/v1/chat/completions` and
/// `/v1/completions` on a vLLM server.
///
/// Flattened into the request body; see the [module docs](crate::vllm).
/// Every field is optional and omitted from the JSON when unset, so vLLM
/// applies its own default.
#[derive(Serialize, Deserialize, Debug, Clone, Default)]
pub struct SamplingParams {
    /// Lower bound on the probability mass of the candidate tokens, relative
    /// to the most likely one. vLLM's default is `0.0` (disabled).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_p: Option<f32>,

    /// Multiplicative penalty applied to tokens that have already appeared.
    /// vLLM's default is `1.0` (no penalty). Not the same knob as OpenAI's
    /// `frequency_penalty` / `presence_penalty`; both may be combined.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub repetition_penalty: Option<f32>,

    /// Additional token IDs that end generation, on top of the model's own
    /// EOS token and any `stop` strings.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub stop_token_ids: Option<Vec<u32>>,

    /// Generate exactly `max_tokens` tokens, ignoring EOS. Useful for
    /// benchmarking; the output usually ends mid-sentence.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub ignore_eos: Option<bool>,

    /// Suppress EOS until at least this many tokens have been generated, so
    /// short outputs cannot be cut off early. vLLM's default is `0`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_tokens: Option<u32>,

    /// Strip special tokens from the decoded text. vLLM's default is `true`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub skip_special_tokens: Option<bool>,

    /// Keep a space between adjacent special tokens when decoding. vLLM's
    /// default is `true`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub spaces_between_special_tokens: Option<bool>,

    /// Include the matched `stop` string in the returned text instead of
    /// trimming it. vLLM's default is `false`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub include_stop_str_in_output: Option<bool>,

    /// Truncate the prompt to at most this many tokens. `-1` disables
    /// truncation (vLLM's default); any other value must be positive.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub truncate_prompt_tokens: Option<i64>,

    /// Which end of an over-long prompt `truncate_prompt_tokens` removes.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub truncation_side: Option<TruncationSide>,

    /// Number of most-likely prompt tokens to report log probabilities for,
    /// per prompt position. Returned in the response's `prompt_logprobs`
    /// field. OpenAI has no equivalent.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub prompt_logprobs: Option<u32>,

    /// Report the log probability of these specific token IDs at each
    /// generated position, in addition to the sampled token.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub logprob_token_ids: Option<Vec<u32>>,

    /// Restrict decoding to exactly these token IDs.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub allowed_token_ids: Option<Vec<u32>>,

    /// Substrings that must not appear in the output. Matching runs over the
    /// decoded text, so a bad word spanning a token boundary is still caught.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub bad_words: Option<Vec<String>>,

    /// Exponential length penalty applied when scoring sequences. Only
    /// meaningful for beam search; vLLM's default is `1.0`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub length_penalty: Option<f32>,

    /// Deprecated: beam search was removed from the vLLM engine. Accepted
    /// for wire compatibility only; do not rely on it.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub use_beam_search: Option<bool>,

    /// Embed an invisible watermark in the generated text. vLLM's default is
    /// `true` when the server was started with watermarking support.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub watermarking: Option<bool>,
}

/// Extra `/v1/chat/completions` parameters of a vLLM server: chat-template
/// rendering, structured output, KV transfer and scheduling.
///
/// Flattened into the request body; see the [module docs](crate::vllm).
/// Rejected by the legacy `/v1/completions` endpoint.
#[derive(Serialize, Deserialize, Debug, Clone, Default)]
pub struct ChatParams {
    /// Echo the rendered prompt back at the start of the completion.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub echo: Option<bool>,

    /// Append the template's generation prompt (e.g. `<|assistant|>`) after
    /// the last message. vLLM's default is `true`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub add_generation_prompt: Option<bool>,

    /// Instead of appending a generation prompt, continue the final message
    /// as if the assistant had already started it. Mutually exclusive with
    /// `add_generation_prompt`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub continue_final_message: Option<bool>,

    /// Prepend the tokenizer's BOS token to the rendered prompt. vLLM's
    /// default is `false`, because the chat template normally emits it.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub add_special_tokens: Option<bool>,

    /// Override the model's Jinja chat template with this one, for this
    /// request only.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub chat_template: Option<String>,

    /// Extra variables handed to the chat template. This is how
    /// template-defined switches are set — e.g. Qwen3's `enable_thinking`
    /// when the model is served by vLLM rather than by DashScope:
    /// `{"enable_thinking": false}`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub chat_template_kwargs: Option<serde_json::Map<String, serde_json::Value>>,

    /// Documents made available to templates that take a `documents`
    /// variable, as a list of string-to-string maps.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub documents: Option<Vec<std::collections::HashMap<String, String>>>,

    /// Per-request overrides for the multimodal processor (image resizing,
    /// video frame sampling, and similar model-specific knobs).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub mm_processor_kwargs: Option<serde_json::Map<String, serde_json::Value>>,

    /// Per-request overrides for the multimodal I/O layer, keyed by modality.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub media_io_kwargs: Option<serde_json::Map<String, serde_json::Value>>,

    /// Constrain decoding to a grammar. vLLM's successor to the deprecated
    /// top-level `guided_json` / `guided_regex` / `guided_choice` /
    /// `guided_grammar` keys.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub structured_outputs: Option<StructuredOutputsParams>,

    /// Scheduling priority; higher is served first. Requires the server to
    /// run with `--scheduling-policy priority`. The `X-Vllm-Priority`
    /// request header overrides this field.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub priority: Option<i64>,

    /// Caller-chosen request identifier, replacing the generated UUID. Must
    /// be unique or the server rejects the request.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub request_id: Option<String>,

    /// Session identifier, used to keep related requests on the same engine
    /// for KV-cache reuse.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub session_id: Option<String>,

    /// Prefix-cache isolation: requests with a different salt never reuse
    /// each other's cached blocks.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub cache_salt: Option<String>,

    /// Minimum number of generated tokens between streamed chunks, used to
    /// batch output and cut per-chunk overhead. `1` streams every token.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub stream_interval: Option<u32>,

    /// Parameters for disaggregated prefill (KV-cache transfer between
    /// instances). Echoed back on the response.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub kv_transfer_params: Option<serde_json::Map<String, serde_json::Value>>,

    /// Parameters for encoder-cache transfer between instances. Echoed back
    /// on the response.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub ec_transfer_params: Option<serde_json::Map<String, serde_json::Value>>,

    /// Report generated text as the literal token-ID strings
    /// (`token_id:1234`) instead of decoded text.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub return_tokens_as_token_ids: Option<bool>,

    /// Add a `token_ids` list to each choice, alongside the decoded text.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub return_token_ids: Option<bool>,

    /// Add per-token character offsets to the rendered prompt. Requires a
    /// fast tokenizer and text-only input.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub return_token_offsets: Option<bool>,

    /// Return the fully rendered prompt text in `prompt_text`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub return_prompt_text: Option<bool>,

    /// Abort generation when the output starts repeating an n-gram pattern.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub repetition_detection: Option<RepetitionDetectionParams>,

    /// Escape hatch for parameters vLLM added after this crate was released:
    /// string-keyed scalars or lists passed straight to the engine.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub vllm_xargs: Option<serde_json::Map<String, serde_json::Value>>,

    /// First prompt position for which to report per-token expert routing.
    /// Requires the server to run with `--enable-return-routed-experts`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub routed_experts_prompt_start: Option<u32>,
}

/// vLLM's `structured_outputs` parameter: constrains decoding to a grammar
/// so the output is guaranteed to parse.
///
/// Exactly one of `json`, `regex`, `choice`, `grammar`, `json_object` and
/// `structural_tag` must be set; the server rejects zero or more than one.
///
/// Replaces the deprecated top-level `guided_json`, `guided_regex`,
/// `guided_choice`, `guided_grammar`, `guided_decoding_backend`,
/// `guided_whitespace_pattern` and `structural_tag` keys, which current
/// vLLM no longer accepts at all — sending one is a `400` reporting the
/// unexpected keyword.
#[derive(Serialize, Deserialize, Debug, Clone, Default)]
pub struct StructuredOutputsParams {
    /// JSON Schema the output must validate against. vLLM accepts either an
    /// inline schema object or a schema serialized as a string.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub json: Option<serde_json::Value>,

    /// Regular expression the whole output must match.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub regex: Option<String>,

    /// Closed set of allowed outputs; the model must produce exactly one.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub choice: Option<Vec<String>>,

    /// Context-free grammar in EBNF, e.g. for a query language.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub grammar: Option<String>,

    /// Require syntactically valid JSON without constraining its schema.
    /// Equivalent to OpenAI's `response_format: {"type": "json_object"}`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub json_object: Option<bool>,

    /// A structural tag interleaving schema fragments with free text.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub structural_tag: Option<String>,

    /// Forbid whitespace between JSON tokens, producing compact output.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub disable_any_whitespace: Option<bool>,

    /// Reject input schemas that do not set
    /// `additionalProperties: false`, which guided decoding needs.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub disable_additional_properties: Option<bool>,

    /// Regex describing the whitespace allowed between JSON tokens.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub whitespace_pattern: Option<String>,
}

/// vLLM's `repetition_detection` parameter: aborts generation once the
/// output settles into a repeated n-gram.
///
/// Detection is off unless `max_pattern_size` is at least 1 and `min_count`
/// is at least 2; `min_pattern_size` must not exceed `max_pattern_size`.
#[derive(Serialize, Deserialize, Debug, Clone, Default)]
pub struct RepetitionDetectionParams {
    /// Largest n-gram size to look for. `0` disables detection.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub max_pattern_size: Option<u32>,

    /// Smallest n-gram size to look for. Defaults to `1` when `0`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_pattern_size: Option<u32>,

    /// How often an n-gram must repeat before generation is cut off.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub min_count: Option<u32>,
}

crate::wire_string_enum! {
    /// Which end of an over-long prompt `truncate_prompt_tokens` removes.
    pub enum TruncationSide {
        /// Drop tokens from the beginning, keeping the most recent context.
        Left => "left",
        /// Drop tokens from the end, keeping the earliest context.
        Right => "right",
    }
}

/// vLLM's log probability of one token at one position, as reported in the
/// `prompt_logprobs` response field.
///
/// OpenAI's logprob objects carry `token` / `logprob` / `bytes` /
/// `top_logprobs`; vLLM's prompt logprobs instead key each position's map by
/// token ID and report the vocabulary rank plus the decoded text.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
pub struct Logprob {
    /// The log probability of this token.
    pub logprob: f64,
    /// This token's rank in the vocabulary at this position, starting at 1.
    /// Omitted when the server did not compute it.
    pub rank: Option<u32>,
    /// The decoded text of this token.
    pub decoded_token: Option<String>,
}

/// Why generation stopped, as reported in vLLM's `stop_reason` response
/// field.
///
/// Not part of the OpenAI schema. It complements `finish_reason`, which only
/// says `stop`: `stop_reason` names the *specific* terminator that fired.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
#[serde(untagged)]
pub enum StopReason {
    /// The stop string that ended generation, when a `stop` entry matched.
    Text(String),
    /// The token ID that ended generation, when `stop_token_ids` or the
    /// model's own EOS token matched.
    TokenId(u32),
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::chat::create::request::{Message, RequestBody};

    /// The vLLM sampling parameters must land at the top level of the body,
    /// exactly where the official client's `extra_body` puts them.
    #[test]
    fn sampling_params_flatten_to_top_level() {
        let request = RequestBody {
            messages: vec![Message::user("Hello")],
            model: "Qwen/Qwen3-8B".to_string(),
            vllm_sampling: Some(SamplingParams {
                min_p: Some(0.1),
                repetition_penalty: Some(1.05),
                stop_token_ids: Some(vec![151645, 151643]),
                ignore_eos: Some(false),
                min_tokens: Some(16),
                truncate_prompt_tokens: Some(-1),
                truncation_side: Some(TruncationSide::Left),
                prompt_logprobs: Some(3),
                allowed_token_ids: Some(vec![1, 2, 3]),
                bad_words: Some(vec!["<|im_start|>".to_string()]),
                ..Default::default()
            }),
            ..Default::default()
        };

        let json = serde_json::to_value(&request).unwrap();
        assert_eq!(json["min_p"], serde_json::json!(0.1f32));
        assert_eq!(json["repetition_penalty"], serde_json::json!(1.05f32));
        assert_eq!(json["stop_token_ids"], serde_json::json!([151645, 151643]));
        assert_eq!(json["ignore_eos"], false);
        assert_eq!(json["min_tokens"], 16);
        assert_eq!(json["truncate_prompt_tokens"], -1);
        assert_eq!(json["truncation_side"], "left");
        assert_eq!(json["prompt_logprobs"], 3);
        assert_eq!(json["bad_words"], serde_json::json!(["<|im_start|>"]));
        // Unset fields stay off the wire so vLLM applies its own defaults.
        assert!(json.get("skip_special_tokens").is_none());
        assert!(json.get("watermarking").is_none());
    }

    /// The chat-only parameters, including the nested `structured_outputs`
    /// object and the free-form template kwargs.
    #[test]
    fn chat_params_flatten_to_top_level() {
        let request = RequestBody {
            messages: vec![Message::user("Hello")],
            model: "Qwen/Qwen3-8B".to_string(),
            vllm_chat: Some(ChatParams {
                chat_template_kwargs: Some(
                    serde_json::from_value(serde_json::json!({"enable_thinking": false})).unwrap(),
                ),
                structured_outputs: Some(StructuredOutputsParams {
                    choice: Some(vec!["positive".to_string(), "negative".to_string()]),
                    disable_any_whitespace: Some(true),
                    ..Default::default()
                }),
                priority: Some(10),
                kv_transfer_params: Some(
                    serde_json::from_value(serde_json::json!({"do_remote_decode": true})).unwrap(),
                ),
                ..Default::default()
            }),
            ..Default::default()
        };

        let json = serde_json::to_value(&request).unwrap();
        assert_eq!(json["chat_template_kwargs"]["enable_thinking"], false);
        assert_eq!(
            json["structured_outputs"],
            serde_json::json!({"choice": ["positive", "negative"], "disable_any_whitespace": true})
        );
        assert_eq!(json["priority"], 10);
        assert_eq!(json["kv_transfer_params"]["do_remote_decode"], true);
        assert!(json.get("echo").is_none());
    }

    /// Structured outputs accept a schema either inline or as a string.
    #[test]
    fn structured_outputs_json_accepts_object_and_string() {
        let inline = StructuredOutputsParams {
            json: Some(serde_json::json!({"type": "object"})),
            ..Default::default()
        };
        assert_eq!(
            serde_json::to_value(&inline).unwrap()["json"],
            serde_json::json!({"type": "object"})
        );

        let as_string = StructuredOutputsParams {
            json: Some(serde_json::json!(r#"{"type":"object"}"#)),
            ..Default::default()
        };
        assert_eq!(
            serde_json::to_value(&as_string).unwrap()["json"],
            serde_json::json!(r#"{"type":"object"}"#)
        );
    }

    /// A vLLM request body must survive a parse-then-serialize round trip
    /// without losing or duplicating any key — the crate is used to build
    /// proxies, and both flattened vLLM structs share the body with the
    /// `extra_body_map` catch-all.
    #[test]
    fn vllm_body_round_trips_without_duplicating_keys() {
        let json = r#"{
            "model": "Qwen/Qwen3-8B",
            "messages": [{"role": "user", "content": "Hello"}],
            "min_p": 0.1,
            "prompt_logprobs": 2,
            "chat_template_kwargs": {"enable_thinking": true},
            "structured_outputs": {"regex": "[a-z]+"},
            "some_future_vllm_field": 42
        }"#;

        let parsed: RequestBody = serde_json::from_str(json).unwrap();

        let sampling = parsed.vllm_sampling.as_ref().expect("vllm_sampling");
        assert_eq!(sampling.min_p, Some(0.1));
        assert_eq!(sampling.prompt_logprobs, Some(2));

        let chat = parsed.vllm_chat.as_ref().expect("vllm_chat");
        assert_eq!(
            chat.chat_template_kwargs
                .as_ref()
                .expect("chat_template_kwargs")["enable_thinking"],
            serde_json::json!(true)
        );
        assert_eq!(
            chat.structured_outputs
                .as_ref()
                .expect("structured_outputs")
                .regex
                .as_deref(),
            Some("[a-z]+")
        );

        // Only the genuinely unknown key may fall through to the catch-all;
        // if the flattened structs failed to claim their own keys, they
        // would appear here too and be serialized twice.
        let extra = parsed.extra_body_map.as_ref().expect("extra_body_map");
        assert_eq!(extra.len(), 1, "extra_body_map: {extra:?}");
        assert_eq!(extra["some_future_vllm_field"], 42);

        let reserialized = serde_json::to_string(&parsed).unwrap();
        let reparsed: serde_json::Value = serde_json::from_str(&reserialized).unwrap();
        assert_eq!(reparsed["min_p"], 0.1);
        assert_eq!(reparsed["prompt_logprobs"], 2);
        assert_eq!(reparsed["structured_outputs"]["regex"], "[a-z]+");
        assert_eq!(reparsed["some_future_vllm_field"], 42);
        // serde_json collapses duplicate keys silently, so count them in the
        // raw text instead.
        assert_eq!(
            reserialized.matches(r#""min_p""#).count(),
            1,
            "duplicated key in {reserialized}"
        );
        assert_eq!(
            reserialized.matches(r#""structured_outputs""#).count(),
            1,
            "duplicated key in {reserialized}"
        );
    }

    /// With no vLLM parameters set, the body must be byte-identical to a
    /// plain OpenAI request: nothing leaks onto the wire.
    #[test]
    fn unset_vllm_params_add_no_keys() {
        let request = RequestBody {
            messages: vec![Message::user("Hello")],
            model: "gpt-4.1".to_string(),
            vllm_sampling: Some(SamplingParams::default()),
            vllm_chat: Some(ChatParams::default()),
            ..Default::default()
        };

        let json = serde_json::to_string(&request).unwrap();
        assert_eq!(
            json,
            r#"{"messages":[{"role":"user","content":"Hello"}],"model":"gpt-4.1"}"#
        );
    }

    /// The legacy `/v1/completions` body takes the sampling parameters but
    /// not the chat-only ones.
    #[test]
    fn completions_body_takes_sampling_params_only() {
        let request = crate::completions::request::CompletionRequest {
            model: "Qwen/Qwen3-8B".to_string(),
            prompt: crate::completions::request::Prompt::PromptString("Hello".to_string()),
            vllm_sampling: Some(SamplingParams {
                min_p: Some(0.1),
                skip_special_tokens: Some(false),
                ..Default::default()
            }),
            ..Default::default()
        };

        let json = serde_json::to_value(&request).unwrap();
        assert_eq!(json["min_p"], serde_json::json!(0.1f32));
        assert_eq!(json["skip_special_tokens"], false);
    }

    /// A non-streaming vLLM response carrying every extra field: prompt
    /// logprobs keyed by token ID, the rendered prompt, `stop_reason` and
    /// the echoed KV-transfer parameters.
    #[test]
    fn non_streaming_response_extras_parse() {
        use crate::chat::ChatCompletion;

        let json = r#"{
            "id": "chatcmpl-abc123",
            "object": "chat.completion",
            "created": 1735113344,
            "model": "Qwen/Qwen3-8B",
            "choices": [{
                "index": 0,
                "message": {"role": "assistant", "content": "Hi"},
                "logprobs": null,
                "finish_reason": "stop",
                "stop_reason": "<|im_end|>",
                "token_ids": [9707, 151645]
            }],
            "usage": {"prompt_tokens": 4, "completion_tokens": 2, "total_tokens": 6},
            "prompt_logprobs": [
                null,
                {"9707": {"logprob": -0.001, "rank": 1, "decoded_token": "Hello"}}
            ],
            "prompt_token_ids": [151644, 8948, 198, 9707],
            "prompt_text": "<|im_start|>user\nHello<|im_end|>\n",
            "kv_transfer_params": {"do_remote_decode": true}
        }"#;

        let parsed: ChatCompletion = json.parse().expect("vLLM response must parse");

        assert_eq!(
            parsed.prompt_token_ids.unwrap(),
            vec![151644, 8948, 198, 9707]
        );
        assert!(parsed.prompt_text.unwrap().starts_with("<|im_start|>"));
        assert_eq!(
            parsed.kv_transfer_params.unwrap()["do_remote_decode"],
            serde_json::json!(true)
        );

        // Position 0 is unreported; position 1 maps token ID 9707 to its logprob.
        let prompt_logprobs = parsed.prompt_logprobs.expect("prompt_logprobs");
        assert_eq!(prompt_logprobs.len(), 2);
        assert!(prompt_logprobs[0].is_none());
        let entry = &prompt_logprobs[1].as_ref().expect("position 1")[&9707];
        assert_eq!(entry.rank, Some(1));
        assert_eq!(entry.decoded_token.as_deref(), Some("Hello"));
        assert!((entry.logprob - -0.001).abs() < 1e-9);

        let choice = &parsed.choices[0];
        assert_eq!(choice.token_ids.clone().unwrap(), vec![9707, 151645]);
        assert_eq!(
            choice.stop_reason,
            Some(StopReason::Text("<|im_end|>".to_string()))
        );
        assert_eq!(choice.finish_reason.as_str(), "stop");
    }

    /// `stop_reason` is `int | str` on the wire; both arms must parse, and
    /// so must a streamed chunk that carries the choice-level extras.
    #[test]
    fn stop_reason_accepts_token_id_and_string() {
        use crate::chat::create::response::streaming::ChatCompletionChunk;

        let by_id: ChatCompletionChunk = r#"{
            "id": "chatcmpl-abc123", "object": "chat.completion.chunk",
            "created": 1735113344, "model": "Qwen/Qwen3-8B",
            "prompt_token_ids": [151644, 9707],
            "choices": [{
                "index": 0, "delta": {"role": "assistant", "content": "Hi"},
                "logprobs": null, "finish_reason": "stop",
                "stop_reason": 151645, "token_ids": [9707]
            }]
        }"#
        .parse()
        .expect("chunk with an integer stop_reason must parse");

        assert_eq!(
            by_id.choices[0].stop_reason,
            Some(StopReason::TokenId(151645))
        );
        assert_eq!(by_id.choices[0].token_ids.clone().unwrap(), vec![9707]);
        assert_eq!(by_id.prompt_token_ids.clone().unwrap(), vec![151644, 9707]);
        assert!(by_id.prompt_text.is_none());

        let by_text: ChatCompletionChunk = r#"{
            "id": "chatcmpl-abc123", "object": "chat.completion.chunk",
            "created": 1735113344, "model": "Qwen/Qwen3-8B",
            "choices": [{
                "index": 0, "delta": {"content": "Hi"},
                "finish_reason": "stop", "stop_reason": "<|im_end|>"
            }]
        }"#
        .parse()
        .expect("chunk with a string stop_reason must parse");

        assert_eq!(
            by_text.choices[0].stop_reason,
            Some(StopReason::Text("<|im_end|>".to_string()))
        );
        assert!(by_text.prompt_token_ids.is_none());
    }

    /// An OpenAI response with none of the extras must still parse, leaving
    /// every vLLM field `None` — the feature must not break other providers.
    #[test]
    fn plain_openai_response_leaves_vllm_fields_none() {
        use crate::chat::ChatCompletion;

        let parsed: ChatCompletion = r#"{
            "id": "chatcmpl-1", "object": "chat.completion", "created": 1,
            "model": "gpt-4.1",
            "choices": [{
                "index": 0,
                "message": {"role": "assistant", "content": "Hi"},
                "finish_reason": "stop"
            }],
            "usage": {"prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2}
        }"#
        .parse()
        .expect("plain OpenAI response must parse with the vllm feature on");

        assert!(parsed.prompt_logprobs.is_none());
        assert!(parsed.prompt_token_ids.is_none());
        assert!(parsed.prompt_text.is_none());
        assert!(parsed.kv_transfer_params.is_none());
        assert!(parsed.ec_transfer_params.is_none());
        assert!(parsed.choices[0].stop_reason.is_none());
        assert!(parsed.choices[0].token_ids.is_none());
        assert!(parsed.choices[0].routed_experts.is_none());
    }

    /// vLLM streams the chain of thought as `reasoning`, not the
    /// cross-vendor `reasoning_content`; the accumulator must pick it up
    /// and keep it separate from the other key.
    #[test]
    fn reasoning_streams_under_vllm_key_and_accumulates() {
        use crate::chat::create::accumulator::ChatCompletionAccumulator;
        use crate::chat::create::response::streaming::ChatCompletionChunk;

        let chunks = [
            r#"{"id":"c","object":"chat.completion.chunk","created":1,"model":"m","choices":[{"index":0,"delta":{"role":"assistant","reasoning":"Let me "},"finish_reason":null}]}"#,
            r#"{"id":"c","object":"chat.completion.chunk","created":1,"model":"m","choices":[{"index":0,"delta":{"reasoning":"think."},"finish_reason":null}]}"#,
            r#"{"id":"c","object":"chat.completion.chunk","created":1,"model":"m","choices":[{"index":0,"delta":{"content":"Hi"},"finish_reason":"stop"}]}"#,
        ];

        let mut accumulator = ChatCompletionAccumulator::new();
        for chunk in chunks {
            let parsed: ChatCompletionChunk = chunk.parse().expect("chunk must parse");
            accumulator.push(&parsed);
        }

        assert_eq!(accumulator.reasoning(), "Let me think.");
        // The two keys are distinct fields; vLLM never fills the other one.
        assert_eq!(accumulator.reasoning_content(), "");
        assert_eq!(accumulator.content(), "Hi");

        let message = accumulator.into_message();
        assert_eq!(message.reasoning.as_deref(), Some("Let me think."));
        assert_eq!(message.reasoning_content, None);
        assert_eq!(message.content.as_deref(), Some("Hi"));
    }

    /// vLLM reports speculative-decoding hits in the usage breakdown, and
    /// prompt caching through the standard `prompt_tokens_details` rather
    /// than a field of its own.
    #[test]
    fn usage_extras_parse() {
        use crate::chat::ChatCompletion;

        let parsed: ChatCompletion = r#"{
            "id": "chatcmpl-1", "object": "chat.completion", "created": 1,
            "model": "Qwen/Qwen3-8B",
            "choices": [{
                "index": 0,
                "message": {"role": "assistant", "content": "Hi"},
                "finish_reason": "stop"
            }],
            "usage": {
                "prompt_tokens": 100, "completion_tokens": 20, "total_tokens": 120,
                "prompt_tokens_details": {"cached_tokens": 64},
                "completion_tokens_details": {
                    "reasoning_tokens": null,
                    "num_speculative_tokens": 8
                }
            }
        }"#
        .parse()
        .expect("vLLM usage must parse");

        let usage = parsed.usage.expect("usage");
        assert_eq!(
            usage
                .completion_tokens_details
                .as_ref()
                .expect("completion_tokens_details")
                .num_speculative_tokens,
            Some(8)
        );
        assert_eq!(
            usage
                .prompt_tokens_details
                .as_ref()
                .expect("prompt_tokens_details")
                .cached_tokens,
            Some(64)
        );
    }

    /// vLLM's `/v1/models` entries carry `root`, `parent` and
    /// `max_model_len` on top of the OpenAI model object.
    #[test]
    fn model_card_extras_parse() {
        let models: crate::models::list::response::ListModelsResponse = r#"{
            "object": "list",
            "data": [{
                "id": "Qwen/Qwen3-8B",
                "object": "model",
                "created": 1735113344,
                "owned_by": "vllm",
                "root": "Qwen/Qwen3-8B",
                "parent": null,
                "max_model_len": 131072
            }]
        }"#
        .parse()
        .expect("vLLM model list must parse");

        let model = &models.data[0];
        assert_eq!(model.root.as_deref(), Some("Qwen/Qwen3-8B"));
        assert_eq!(model.parent, None);
        assert_eq!(model.max_model_len, Some(131072));
        assert_eq!(model.owned_by, "vllm");
    }
}