inferencelayer 0.2.3

//! Wire types for the OpenAI-compatible surface of `lfm2-serve`, plus the validation that turns a
//! raw request into a normalized [`CommonParams`] the engine can consume.
//!
//! Everything here is pure (no GPU, no engine handle), so request validation — range checks, loud
//! rejection of unimplemented features, `stop`/`logit_bias` normalization, `n`/logprobs limits — is
//! unit-testable in isolation. The binary owns only the async plumbing that feeds `CommonParams`
//! into the scheduler and shapes the responses.

use std::collections::BTreeMap;

use serde::{Deserialize, Deserializer, Serialize};

use super::error::ApiError;

/// Ceiling on `top_logprobs` (OpenAI caps at 20).
pub const MAX_TOP_LOGPROBS: usize = 20;
/// OpenAI accepts at most four stop strings.
pub const MAX_STOP: usize = 4;
/// `n` (and the number of shared-prompt submits) is capped so one request cannot exhaust slots.
pub const MAX_N: usize = 8;

fn default_max_tokens() -> usize {
    64
}

/// `stop`: a single string or an array of up to [`MAX_STOP`] strings.
#[derive(Deserialize)]
#[serde(untagged)]
pub enum StopField {
    One(String),
    Many(Vec<String>),
}

impl StopField {
    /// Normalize to a plain `Vec` of stop strings.
    pub fn to_vec(&self) -> Vec<String> {
        match self {
            StopField::One(s) => vec![s.clone()],
            StopField::Many(v) => v.clone(),
        }
    }
}

/// `prompt`: a single string, or a one-element array of strings (multi-prompt batches are rejected
/// loudly — they are a distinct unimplemented feature, not silently collapsed).
#[derive(Deserialize)]
#[serde(untagged)]
pub enum PromptField {
    Text(String),
    Texts(Vec<String>),
}

/// `stream_options` (OpenAI): request a final usage-bearing chunk on a streamed response.
#[derive(Deserialize, Default)]
pub struct StreamOptions {
    #[serde(default)]
    pub include_usage: bool,
}

/// `content` accepts a string, or JSON `null` (OpenAI sends `content: null` on an assistant turn
/// that only carries `tool_calls`, and clients vary on tool results) → `""`. A missing field is
/// handled by `#[serde(default)]` on the call site.
fn de_null_string<'de, D>(d: D) -> Result<String, D::Error>
where
    D: Deserializer<'de>,
{
    Ok(Option::<String>::deserialize(d)?.unwrap_or_default())
}

/// One tool call replayed in history on an `assistant` message (OpenAI shape).
#[derive(Deserialize)]
pub struct ToolCallMsg {
    #[serde(default)]
    pub id: Option<String>,
    #[serde(rename = "type", default)]
    pub kind: Option<String>,
    pub function: FunctionCallMsg,
}

/// The `function` payload of a replayed [`ToolCallMsg`]: `arguments` is a JSON string on the wire.
#[derive(Deserialize)]
pub struct FunctionCallMsg {
    pub name: String,
    #[serde(default, deserialize_with = "de_null_string")]
    pub arguments: String,
}

/// One chat turn on the wire. Beyond `role`/`content`, an `assistant` turn may carry `tool_calls`
/// it previously made and a `tool` turn carries a function result (in `content`, keyed by
/// `tool_call_id`) — both replayed into the prompt so multi-turn tool conversations round-trip.
#[derive(Deserialize)]
pub struct ChatMessage {
    pub role: String,
    #[serde(default, deserialize_with = "de_null_string")]
    pub content: String,
    #[serde(default)]
    pub tool_calls: Vec<ToolCallMsg>,
    #[serde(default)]
    pub tool_call_id: Option<String>,
    /// The function name for a `tool` result (accepted for OpenAI compatibility; the ChatML
    /// `<tool_response>` wrapping does not need it).
    #[serde(default)]
    pub name: Option<String>,
}

/// The normalized, validated parameter bundle shared by both endpoints. The binary maps this onto
/// the engine's `RequestParams`; the numbers here are already range-checked and defaulted.
#[derive(Debug, Clone, PartialEq)]
pub struct CommonParams {
    pub max_tokens: usize,
    pub n: usize,
    pub temperature: f32,
    pub top_p: f32,
    pub top_k: Option<usize>,
    pub min_p: Option<f32>,
    pub seed: u64,
    pub presence_penalty: f32,
    pub frequency_penalty: f32,
    pub repetition_penalty: f32,
    pub logit_bias: Vec<(u32, f32)>,
    pub stop: Vec<String>,
    pub stop_token_ids: Vec<u32>,
    /// Number of top logprobs to return per token (`Some(0)` = only the chosen token's logprob);
    /// `None` = logprobs disabled.
    pub logprobs: Option<usize>,
    pub stream: bool,
    pub include_usage: bool,
}

/// Shared, endpoint-agnostic parameters as received on the wire. Both request structs flatten this
/// so the validation lives in one place.
#[derive(Deserialize, Default)]
pub struct RawParams {
    #[serde(default = "default_max_tokens")]
    pub max_tokens: usize,
    #[serde(default)]
    pub n: Option<usize>,
    #[serde(default)]
    pub temperature: Option<f32>,
    #[serde(default)]
    pub top_p: Option<f32>,
    #[serde(default)]
    pub top_k: Option<usize>,
    #[serde(default)]
    pub min_p: Option<f32>,
    #[serde(default)]
    pub seed: Option<u64>,
    #[serde(default)]
    pub presence_penalty: Option<f32>,
    #[serde(default)]
    pub frequency_penalty: Option<f32>,
    #[serde(default)]
    pub repetition_penalty: Option<f32>,
    #[serde(default)]
    pub logit_bias: Option<BTreeMap<String, f32>>,
    #[serde(default)]
    pub stop: Option<StopField>,
    #[serde(default)]
    pub stop_token_ids: Option<Vec<u32>>,
    #[serde(default)]
    pub stream: bool,
    #[serde(default)]
    pub stream_options: Option<StreamOptions>,
    // ---- Explicitly-captured unimplemented features: non-default values are rejected loudly. ----
    #[serde(default)]
    pub best_of: Option<usize>,
    #[serde(default)]
    pub suffix: Option<String>,
    #[serde(default)]
    pub echo: Option<bool>,
    #[serde(default)]
    pub tools: Option<Vec<serde_json::Value>>,
    #[serde(default)]
    pub tool_choice: Option<serde_json::Value>,
    #[serde(default)]
    pub functions: Option<Vec<serde_json::Value>>,
    #[serde(default)]
    pub function_call: Option<serde_json::Value>,
    #[serde(default)]
    pub response_format: Option<serde_json::Value>,
}

fn in_range(name: &str, v: f32, lo: f32, hi: f32) -> Result<(), ApiError> {
    if v.is_finite() && (lo..=hi).contains(&v) {
        Ok(())
    } else {
        Err(ApiError::invalid_request(format!("{name} must be in [{lo}, {hi}]")).with_param(name))
    }
}

impl RawParams {
    /// Validate and normalize into [`CommonParams`], rejecting every unimplemented non-default
    /// feature with a typed error. `logprobs` is passed in pre-resolved (the two endpoints spell it
    /// differently: an int count for completions, a bool + `top_logprobs` for chat).
    pub fn validate(&self, logprobs: Option<usize>) -> Result<CommonParams, ApiError> {
        // Unimplemented features → loud 400 (never silently ignored).
        if self.best_of.is_some_and(|b| b > 1) {
            return Err(
                ApiError::invalid_request("best_of > 1 is not implemented").with_param("best_of")
            );
        }
        if self.suffix.is_some() {
            return Err(ApiError::invalid_request("suffix is not implemented").with_param("suffix"));
        }
        if self.echo == Some(true) {
            return Err(ApiError::invalid_request("echo is not implemented").with_param("echo"));
        }
        // `tools` / `tool_choice` are endpoint-specific: chat renders them (see
        // `ChatReq::tools_to_render` / `RawParams::tool_choice_mode`), completions rejects them
        // (`CompletionReq::common`). The legacy `functions` API stays unimplemented everywhere.
        if self.functions.as_ref().is_some_and(|f| !f.is_empty()) {
            return Err(
                ApiError::invalid_request("functions are not implemented").with_param("functions")
            );
        }
        if self.function_call.is_some() {
            return Err(
                ApiError::invalid_request("function_call is not implemented")
                    .with_param("function_call"),
            );
        }
        if self.response_format.is_some() {
            return Err(ApiError::invalid_request(
                "response_format (structured output) is not implemented on this endpoint",
            )
            .with_param("response_format"));
        }

        let temperature = self.temperature.unwrap_or(0.0);
        in_range("temperature", temperature, 0.0, 10.0)?;
        let top_p = self.top_p.unwrap_or(1.0);
        if !(top_p.is_finite() && top_p > 0.0 && top_p <= 1.0) {
            return Err(ApiError::invalid_request("top_p must be in (0, 1]").with_param("top_p"));
        }
        if let Some(k) = self.top_k
            && k == 0
        {
            return Err(
                ApiError::invalid_request("top_k must be >= 1 (omit for unlimited)")
                    .with_param("top_k"),
            );
        }
        if let Some(mp) = self.min_p {
            in_range("min_p", mp, 0.0, 1.0)?;
        }
        let presence_penalty = self.presence_penalty.unwrap_or(0.0);
        in_range("presence_penalty", presence_penalty, -2.0, 2.0)?;
        let frequency_penalty = self.frequency_penalty.unwrap_or(0.0);
        in_range("frequency_penalty", frequency_penalty, -2.0, 2.0)?;
        let repetition_penalty = self.repetition_penalty.unwrap_or(1.0);
        if !(repetition_penalty.is_finite() && repetition_penalty > 0.0) {
            return Err(ApiError::invalid_request("repetition_penalty must be > 0")
                .with_param("repetition_penalty"));
        }

        let n = self.n.unwrap_or(1);
        if n == 0 || n > MAX_N {
            return Err(
                ApiError::invalid_request(format!("n must be in 1..={MAX_N}")).with_param("n"),
            );
        }
        if self.max_tokens == 0 {
            return Err(
                ApiError::invalid_request("max_tokens must be >= 1").with_param("max_tokens")
            );
        }

        let logit_bias = match &self.logit_bias {
            None => Vec::new(),
            Some(m) => {
                let mut out = Vec::with_capacity(m.len());
                for (k, &v) in m {
                    let id: u32 = k.parse().map_err(|_| {
                        ApiError::invalid_request(format!(
                            "logit_bias keys must be integer token ids, got `{k}`"
                        ))
                        .with_param("logit_bias")
                    })?;
                    out.push((id, v));
                }
                out
            }
        };

        let stop = match &self.stop {
            None => Vec::new(),
            Some(field) => {
                let v = field.to_vec();
                if v.len() > MAX_STOP {
                    return Err(ApiError::invalid_request(format!(
                        "at most {MAX_STOP} stop strings are allowed"
                    ))
                    .with_param("stop"));
                }
                v.into_iter().filter(|s| !s.is_empty()).collect()
            }
        };

        if let Some(l) = logprobs
            && l > MAX_TOP_LOGPROBS
        {
            return Err(ApiError::invalid_request(format!(
                "top_logprobs must be in 0..={MAX_TOP_LOGPROBS}"
            ))
            .with_param("top_logprobs"));
        }

        Ok(CommonParams {
            max_tokens: self.max_tokens,
            n,
            temperature,
            top_p,
            top_k: self.top_k,
            min_p: self.min_p,
            seed: self.seed.unwrap_or(0),
            presence_penalty,
            frequency_penalty,
            repetition_penalty,
            logit_bias,
            stop,
            stop_token_ids: self.stop_token_ids.clone().unwrap_or_default(),
            logprobs,
            stream: self.stream,
            include_usage: self
                .stream_options
                .as_ref()
                .map(|o| o.include_usage)
                .unwrap_or(false),
        })
    }

    /// Resolve `tool_choice` to a supported mode. Absent / `"auto"` → [`ToolMode::Auto`]; `"none"`
    /// → [`ToolMode::None`]. `"required"` and a named-function object need constrained decoding the
    /// engine does not do, so they are rejected loudly rather than silently downgraded to `auto`.
    pub fn tool_choice_mode(&self) -> Result<ToolMode, ApiError> {
        match &self.tool_choice {
            None => Ok(ToolMode::Auto),
            Some(v) => match v.as_str() {
                Some("auto") => Ok(ToolMode::Auto),
                Some("none") => Ok(ToolMode::None),
                Some("required") => Err(ApiError::invalid_request(
                    "tool_choice \"required\" needs constrained decoding, which is not implemented",
                )
                .with_param("tool_choice")),
                _ => Err(ApiError::invalid_request(
                    "tool_choice must be \"auto\" or \"none\" (forced/named tool choice is not implemented)",
                )
                .with_param("tool_choice")),
            },
        }
    }
}

/// Whether the model may call tools this request. `Auto` advertises the tools and lets the model
/// decide; `None` suppresses tool rendering entirely so the model cannot call one.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ToolMode {
    Auto,
    None,
}

/// `POST /v1/completions` request.
#[derive(Deserialize)]
pub struct CompletionReq {
    #[serde(default)]
    pub model: Option<String>,
    pub prompt: PromptField,
    /// Base64 image bytes — raw, or a `data:image/...;base64,...` URI — one per `<|image_pad|>` in
    /// the prompt, in order.
    ///
    /// This is an EXTENSION to the OpenAI completions shape, and deliberately so: it keeps the
    /// caller's job to "render the chat template and hand over the bytes", which needs a tokenizer
    /// and a jinja renderer and nothing else — no torch, no image processor. The engine expands each
    /// placeholder to one token per merged patch, because that count is a property of the image's
    /// grid and cannot be known by a caller that has not preprocessed it.
    #[serde(default)]
    pub images: Vec<String>,
    /// Completions spell logprobs as an integer count of top alternatives.
    #[serde(default)]
    pub logprobs: Option<usize>,
    #[serde(flatten)]
    pub params: RawParams,
}

impl CompletionReq {
    /// The single prompt string (rejecting multi-prompt arrays loudly).
    pub fn prompt_text(&self) -> Result<&str, ApiError> {
        match &self.prompt {
            PromptField::Text(s) => Ok(s.as_str()),
            PromptField::Texts(v) if v.len() == 1 => Ok(v[0].as_str()),
            PromptField::Texts(_) => Err(ApiError::invalid_request(
                "multiple prompts in one request are not implemented (send one prompt, or use n)",
            )
            .with_param("prompt")),
        }
    }

    pub fn common(&self) -> Result<CommonParams, ApiError> {
        // Tool calling only makes sense on chat (where a system turn and a tool-result role exist).
        if self.params.tools.as_ref().is_some_and(|t| !t.is_empty())
            || self.params.tool_choice.is_some()
        {
            return Err(ApiError::invalid_request(
                "tools / function calling is not supported on /v1/completions — use /v1/chat/completions",
            )
            .with_param("tools"));
        }
        self.params.validate(self.logprobs)
    }
}

/// `POST /v1/chat/completions` request.
#[derive(Deserialize)]
pub struct ChatReq {
    #[serde(default)]
    pub model: Option<String>,
    pub messages: Vec<ChatMessage>,
    /// Chat spells logprobs as a bool gate...
    #[serde(default)]
    pub logprobs: Option<bool>,
    /// ...plus a separate count of top alternatives.
    #[serde(default)]
    pub top_logprobs: Option<usize>,
    /// OpenAI's newer alias for `max_tokens` on chat.
    #[serde(default)]
    pub max_completion_tokens: Option<usize>,
    #[serde(flatten)]
    pub params: RawParams,
}

impl ChatReq {
    pub fn common(&self) -> Result<CommonParams, ApiError> {
        let logprobs = if self.logprobs == Some(true) {
            Some(self.top_logprobs.unwrap_or(0))
        } else {
            None
        };
        let mut c = self.params.validate(logprobs)?;
        // `max_completion_tokens` overrides `max_tokens` when present (OpenAI's chat spelling).
        if let Some(m) = self.max_completion_tokens {
            if m == 0 {
                return Err(
                    ApiError::invalid_request("max_completion_tokens must be >= 1")
                        .with_param("max_completion_tokens"),
                );
            }
            c.max_tokens = m;
        }
        Ok(c)
    }

    /// The tool signatures to advertise in the prompt this request: the supplied `tools` when they
    /// are non-empty **and** `tool_choice` resolves to [`ToolMode::Auto`]; empty otherwise (no
    /// tools, or `tool_choice: "none"` which suppresses them). Also the validation point for
    /// `tool_choice` — an unsupported value is a loud error. When this returns empty the response
    /// path must not parse tool calls, so the two decisions share one source of truth.
    pub fn tools_to_render(&self) -> Result<Vec<serde_json::Value>, ApiError> {
        let mode = self.params.tool_choice_mode()?;
        match &self.params.tools {
            Some(tools) if !tools.is_empty() && mode == ToolMode::Auto => Ok(tools.clone()),
            _ => Ok(Vec::new()),
        }
    }
}

/// One `logprobs` alternative for the response (`token` is the detokenized piece).
#[derive(Serialize, Clone)]
pub struct TopLogprob {
    pub token: String,
    pub logprob: f32,
}

/// Token usage accounting for a response.
#[derive(Serialize, Clone, Debug, PartialEq)]
pub struct Usage {
    pub prompt_tokens: usize,
    pub completion_tokens: usize,
    pub total_tokens: usize,
    pub prompt_tokens_details: PromptTokensDetails,
}

/// The `cached_tokens` breakdown OpenAI reports — here it is the radix-cache prefix-hit count, a
/// genuine number rather than a placeholder zero.
#[derive(Serialize, Clone, Debug, PartialEq)]
pub struct PromptTokensDetails {
    pub cached_tokens: usize,
}

impl Usage {
    pub fn new(prompt_tokens: usize, completion_tokens: usize, cached_tokens: usize) -> Self {
        Self {
            prompt_tokens,
            completion_tokens,
            total_tokens: prompt_tokens + completion_tokens,
            prompt_tokens_details: PromptTokensDetails { cached_tokens },
        }
    }
}

/// Seconds since the Unix epoch (the `created` field on every response object).
pub fn created_epoch() -> u64 {
    std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map(|d| d.as_secs())
        .unwrap_or(0)
}

/// Process-global monotonic counter so every response id is unique within a process run.
fn monotonic() -> u64 {
    use std::sync::atomic::{AtomicU64, Ordering};
    static COUNTER: AtomicU64 = AtomicU64::new(0);
    COUNTER.fetch_add(1, Ordering::Relaxed)
}

/// A unique response id of the form `{prefix}-{pid}-{monotonic}` (e.g. `cmpl-1234-0`). Two calls,
/// concurrent or not, never collide within a process.
pub fn response_id(prefix: &str) -> String {
    format!("{prefix}-{}-{}", std::process::id(), monotonic())
}

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

    fn raw(json: serde_json::Value) -> RawParams {
        serde_json::from_value(json).expect("raw params")
    }

    #[test]
    fn should_default_and_validate_the_happy_path() {
        let c = raw(serde_json::json!({})).validate(None).expect("valid");
        assert_eq!(c.max_tokens, 64);
        assert_eq!(c.n, 1);
        assert_eq!(c.temperature, 0.0);
        assert_eq!(c.top_p, 1.0);
        assert_eq!(c.repetition_penalty, 1.0);
        assert!(c.stop.is_empty());
        assert!(c.logit_bias.is_empty());
        assert_eq!(c.logprobs, None);
    }

    #[test]
    fn should_reject_out_of_range_top_p() {
        let e = raw(serde_json::json!({"top_p": 1.5}))
            .validate(None)
            .expect_err("reject");
        assert_eq!(e.param.as_deref(), Some("top_p"));
    }

    #[test]
    fn should_reject_n_outside_one_to_eight() {
        assert!(raw(serde_json::json!({"n": 0})).validate(None).is_err());
        assert!(raw(serde_json::json!({"n": 9})).validate(None).is_err());
        assert_eq!(
            raw(serde_json::json!({"n": 8}))
                .validate(None)
                .expect("ok")
                .n,
            8
        );
    }

    #[test]
    fn should_reject_unimplemented_features_loudly() {
        // `tools`/`tool_choice` are no longer rejected in `validate` — they are handled per
        // endpoint (chat renders, completions rejects). These remain unimplemented everywhere.
        for (field, body) in [
            ("best_of", serde_json::json!({"best_of": 2})),
            ("suffix", serde_json::json!({"suffix": "x"})),
            ("echo", serde_json::json!({"echo": true})),
            (
                "response_format",
                serde_json::json!({"response_format": {"type": "json_object"}}),
            ),
        ] {
            let e = raw(body).validate(None).expect_err("reject");
            assert_eq!(e.param.as_deref(), Some(field), "field {field}");
            assert_eq!(e.status, axum::http::StatusCode::BAD_REQUEST);
        }
    }

    #[test]
    fn should_allow_default_valued_unimplemented_features() {
        // best_of=1, echo=false, empty tools are the DEFAULTS and must not trip the rejection.
        let c = raw(serde_json::json!({"best_of": 1, "echo": false, "tools": []})).validate(None);
        assert!(c.is_ok(), "defaults must pass: {c:?}");
    }

    fn chat(json: serde_json::Value) -> ChatReq {
        serde_json::from_value(json).expect("chat req")
    }

    #[test]
    fn chat_advertises_tools_only_under_auto() {
        let tools = serde_json::json!([{"type": "function", "function": {"name": "f"}}]);
        // Absent tool_choice → auto → advertised.
        let auto = chat(serde_json::json!({"messages": [], "tools": tools}));
        assert_eq!(auto.tools_to_render().expect("ok").len(), 1);
        // Explicit auto → advertised.
        let explicit = chat(serde_json::json!({
            "messages": [], "tools": tools, "tool_choice": "auto"
        }));
        assert_eq!(explicit.tools_to_render().expect("ok").len(), 1);
        // "none" suppresses them even when present.
        let none = chat(serde_json::json!({
            "messages": [], "tools": tools, "tool_choice": "none"
        }));
        assert!(none.tools_to_render().expect("ok").is_empty());
        // No tools at all → empty.
        let bare = chat(serde_json::json!({"messages": []}));
        assert!(bare.tools_to_render().expect("ok").is_empty());
    }

    #[test]
    fn chat_rejects_forced_and_named_tool_choice() {
        for tc in [
            serde_json::json!("required"),
            serde_json::json!({"type": "function", "function": {"name": "f"}}),
        ] {
            let req = chat(serde_json::json!({"messages": [], "tool_choice": tc}));
            let e = req.tools_to_render().expect_err("reject");
            assert_eq!(e.param.as_deref(), Some("tool_choice"));
        }
    }

    #[test]
    fn completions_reject_tools() {
        let req: CompletionReq = serde_json::from_value(serde_json::json!({
            "prompt": "hi", "tools": [{"type": "function", "function": {"name": "f"}}]
        }))
        .expect("parse");
        let e = req.common().expect_err("reject");
        assert_eq!(e.param.as_deref(), Some("tools"));
    }

    #[test]
    fn chat_message_parses_tool_calls_and_null_content() {
        // Assistant turn with tool_calls and content: null (the OpenAI history shape).
        let req = chat(serde_json::json!({
            "messages": [{
                "role": "assistant",
                "content": null,
                "tool_calls": [{
                    "id": "call_1", "type": "function",
                    "function": {"name": "get_weather", "arguments": "{\"city\":\"Paris\"}"}
                }]
            }, {
                "role": "tool", "tool_call_id": "call_1", "content": "18C"
            }]
        }));
        let asst = &req.messages[0];
        assert_eq!(asst.content, "");
        assert_eq!(asst.tool_calls.len(), 1);
        assert_eq!(asst.tool_calls[0].function.name, "get_weather");
        assert_eq!(
            asst.tool_calls[0].function.arguments,
            "{\"city\":\"Paris\"}"
        );
        let tool = &req.messages[1];
        assert_eq!(tool.content, "18C");
        assert_eq!(tool.tool_call_id.as_deref(), Some("call_1"));
    }

    #[test]
    fn should_normalize_stop_string_and_array() {
        let one = raw(serde_json::json!({"stop": "END"}))
            .validate(None)
            .expect("ok");
        assert_eq!(one.stop, vec!["END".to_string()]);
        let many = raw(serde_json::json!({"stop": ["A", "B"]}))
            .validate(None)
            .expect("ok");
        assert_eq!(many.stop, vec!["A".to_string(), "B".to_string()]);
        // Over-limit stop arrays are rejected.
        assert!(
            raw(serde_json::json!({"stop": ["a", "b", "c", "d", "e"]}))
                .validate(None)
                .is_err()
        );
    }

    #[test]
    fn should_parse_logit_bias_keys_as_token_ids() {
        let c = raw(serde_json::json!({"logit_bias": {"5": 10.0, "42": -100.0}}))
            .validate(None)
            .expect("ok");
        let mut got = c.logit_bias.clone();
        got.sort_by_key(|(id, _)| *id);
        assert_eq!(got, vec![(5, 10.0), (42, -100.0)]);
        // Non-integer keys are a loud error.
        assert!(
            raw(serde_json::json!({"logit_bias": {"foo": 1.0}}))
                .validate(None)
                .is_err()
        );
    }

    #[test]
    fn should_cap_top_logprobs_at_twenty() {
        assert!(raw(serde_json::json!({})).validate(Some(21)).is_err());
        assert_eq!(
            raw(serde_json::json!({}))
                .validate(Some(20))
                .expect("ok")
                .logprobs,
            Some(20)
        );
    }

    #[test]
    fn should_thread_stream_options_include_usage() {
        let c = raw(serde_json::json!({"stream": true, "stream_options": {"include_usage": true}}))
            .validate(None)
            .expect("ok");
        assert!(c.stream);
        assert!(c.include_usage);
    }

    #[test]
    fn usage_totals_are_the_sum() {
        let u = Usage::new(10, 5, 3);
        assert_eq!(u.total_tokens, 15);
        assert_eq!(u.prompt_tokens_details.cached_tokens, 3);
    }

    #[test]
    fn response_ids_are_unique_and_prefixed() {
        let a = response_id("cmpl");
        let b = response_id("cmpl");
        assert_ne!(a, b, "ids must be distinct: {a} vs {b}");
        assert!(a.starts_with("cmpl-"));
    }

    #[test]
    fn chat_max_completion_tokens_overrides_max_tokens() {
        let req: ChatReq = serde_json::from_value(serde_json::json!({
            "messages": [], "max_tokens": 64, "max_completion_tokens": 7
        }))
        .expect("parse");
        assert_eq!(req.common().expect("ok").max_tokens, 7);
    }

    #[test]
    fn chat_logprobs_bool_plus_top_logprobs_becomes_count() {
        let req: ChatReq = serde_json::from_value(serde_json::json!({
            "messages": [], "logprobs": true, "top_logprobs": 3
        }))
        .expect("parse");
        assert_eq!(req.common().expect("ok").logprobs, Some(3));
        // logprobs:false ⇒ disabled regardless of top_logprobs.
        let off: ChatReq = serde_json::from_value(serde_json::json!({
            "messages": [], "logprobs": false, "top_logprobs": 3
        }))
        .expect("parse");
        assert_eq!(off.common().expect("ok").logprobs, None);
    }

    #[test]
    fn completion_rejects_multi_prompt_arrays() {
        let req: CompletionReq = serde_json::from_value(serde_json::json!({
            "prompt": ["a", "b"]
        }))
        .expect("parse");
        assert!(req.prompt_text().is_err());
        // A single-element array is accepted as that one prompt.
        let one: CompletionReq =
            serde_json::from_value(serde_json::json!({"prompt": ["solo"]})).expect("parse");
        assert_eq!(one.prompt_text().expect("ok"), "solo");
    }
}