llm-kernel 0.31.1

//! Core types for the LLM client module.
#![deny(missing_docs)]

use std::fmt;
use std::pin::Pin;

use serde::{Deserialize, Serialize};

/// Role of a message sender in a chat conversation.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum MessageRole {
    /// System-level instruction message.
    System,
    /// User input message.
    User,
    /// Assistant response message.
    Assistant,
    /// Tool/function result message.
    Tool,
}

impl fmt::Display for MessageRole {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::System => write!(f, "system"),
            Self::User => write!(f, "user"),
            Self::Assistant => write!(f, "assistant"),
            Self::Tool => write!(f, "tool"),
        }
    }
}

/// A single content part in a multimodal chat message.
///
/// Supports text, image URLs, and base64-encoded images.
/// Single-text messages serialize as a plain string for backward compatibility
/// with OpenAI and Anthropic APIs.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum ContentPart {
    /// Plain text content.
    Text {
        /// The text string.
        text: String,
    },
    /// Image specified by URL.
    ImageUrl {
        /// URL pointing to the image.
        url: String,
    },
    /// Image specified as base64-encoded data.
    ImageBase64 {
        /// MIME type (e.g. `"image/png"`).
        media_type: String,
        /// Base64-encoded image data.
        data: String,
    },
}

impl ContentPart {
    /// Create a text content part.
    pub fn text(s: impl Into<String>) -> Self {
        Self::Text { text: s.into() }
    }

    /// Create an image URL content part.
    pub fn image_url(url: impl Into<String>) -> Self {
        Self::ImageUrl { url: url.into() }
    }

    /// Extract text content, if this is a text part.
    pub fn as_text(&self) -> Option<&str> {
        match self {
            Self::Text { text } => Some(text),
            _ => None,
        }
    }
}

/// Serde helper: serialize `Vec<ContentPart>` as a plain string when there's
/// a single text entry, or as an array otherwise.
mod content_vec_serde {
    use super::ContentPart;
    use serde::{Deserialize, Deserializer, Serialize, Serializer};

    pub fn serialize<S: Serializer>(parts: &[ContentPart], s: S) -> Result<S::Ok, S::Error> {
        if parts.len() == 1
            && let ContentPart::Text { text } = &parts[0]
        {
            return s.serialize_str(text);
        }
        parts.serialize(s)
    }

    pub fn deserialize<'de, D: Deserializer<'de>>(d: D) -> Result<Vec<ContentPart>, D::Error> {
        #[derive(Deserialize)]
        #[serde(untagged)]
        enum StringOrParts {
            S(String),
            P(Vec<ContentPart>),
        }
        match StringOrParts::deserialize(d)? {
            StringOrParts::S(s) => Ok(vec![ContentPart::text(s)]),
            StringOrParts::P(v) => Ok(v),
        }
    }
}

/// A single message in a chat conversation.
///
/// Implements [`Default`] for forward-compatible struct-update syntax.
/// Prefer the `ChatMessage::system` / `::user` / `::assistant` / `::tool`
/// constructors for clarity.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ChatMessage {
    /// Role of the message sender.
    pub role: MessageRole,
    /// Content parts (text, images). Serializes as a plain string when
    /// containing a single text part for backward compatibility.
    #[serde(with = "content_vec_serde")]
    pub content: Vec<ContentPart>,
}

impl Default for ChatMessage {
    fn default() -> Self {
        Self {
            role: MessageRole::User,
            content: Vec::new(),
        }
    }
}

impl ChatMessage {
    /// Create a system message with text content.
    pub fn system(content: impl Into<String>) -> Self {
        Self {
            role: MessageRole::System,
            content: vec![ContentPart::text(content)],
        }
    }

    /// Create a user message with text content.
    pub fn user(content: impl Into<String>) -> Self {
        Self {
            role: MessageRole::User,
            content: vec![ContentPart::text(content)],
        }
    }

    /// Create an assistant message with text content.
    pub fn assistant(content: impl Into<String>) -> Self {
        Self {
            role: MessageRole::Assistant,
            content: vec![ContentPart::text(content)],
        }
    }

    /// Create a tool result message.
    pub fn tool(content: impl Into<String>) -> Self {
        Self {
            role: MessageRole::Tool,
            content: vec![ContentPart::text(content)],
        }
    }

    /// Create a user message with multimodal content parts.
    pub fn user_multimodal(parts: Vec<ContentPart>) -> Self {
        Self {
            role: MessageRole::User,
            content: parts,
        }
    }

    /// Extract all text from this message's content parts.
    pub fn text_content(&self) -> String {
        self.content
            .iter()
            .filter_map(|p| p.as_text())
            .collect::<Vec<_>>()
            .join("")
    }
}

/// Configuration for a specific LLM model and provider.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ModelConfig {
    /// Provider name (e.g. `"openai"`, `"anthropic"`).
    pub provider: String,
    /// Model identifier (e.g. `"gpt-4o"`, `"claude-sonnet-4-6"`).
    pub model: String,
    /// Environment variable name holding the API key.
    pub api_key_env: String,
    /// Optional base URL override for the provider API.
    pub base_url: Option<String>,
    /// Sampling temperature (0.0–2.0).
    pub temperature: f32,
    /// Maximum tokens to generate in the response.
    pub max_tokens: Option<u32>,
}

impl Default for ModelConfig {
    fn default() -> Self {
        Self {
            provider: "openai".into(),
            model: "gpt-4o".into(),
            api_key_env: "OPENAI_API_KEY".into(),
            base_url: None,
            temperature: 0.7,
            max_tokens: Some(4096),
        }
    }
}

/// Desired output format for the LLM response.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum ResponseFormat {
    /// Plain text response (default).
    Text,
    /// JSON object response.
    Json,
    /// JSON response conforming to the given schema.
    JsonSchema {
        /// JSON Schema the response must satisfy.
        schema: serde_json::Value,
    },
}

/// Reasoning effort for reasoning models (OpenAI `reasoning_effort`).
///
/// Wire values follow the official OpenAI Chat Completions parameter:
/// `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. Not every
/// model supports every value (e.g. `none` is gpt-5.1+); see the OpenAI
/// reasoning guide for model-specific support.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum ReasoningEffort {
    /// Disable reasoning entirely (gpt-5.1+ only).
    None,
    /// Minimal reasoning (gpt-5+ only).
    Minimal,
    /// Low effort — latency-sensitive tasks.
    Low,
    /// Medium effort — balanced default for most workloads.
    Medium,
    /// High effort — hard reasoning, complex debugging.
    High,
    /// Extra-high effort — deep research, long agentic runs.
    XHigh,
    /// Maximum reasoning for the most complex tasks.
    Max,
}

/// Verbosity of the model's response (OpenAI `verbosity`).
///
/// Wire values follow the official OpenAI Chat Completions parameter:
/// `low`, `medium`, `high` (spec default `medium`).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum Verbosity {
    /// More concise responses.
    Low,
    /// Balanced (spec default).
    Medium,
    /// More verbose responses.
    High,
}

/// Summary style for reasoning models (Responses-API `reasoning.summary`,
/// also accepted inside OpenRouter's `reasoning` object).
///
/// Wire values follow the official OpenAI spec: `auto`, `concise`,
/// `detailed`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum ReasoningSummary {
    /// Model/provider picks the summary style.
    Auto,
    /// Compact reasoning summary (gpt-5+ reasoning models).
    Concise,
    /// Detailed reasoning summary.
    Detailed,
}

/// Reasoning-model controls for a chat completion request.
///
/// Three independent knobs, each serialized only when set:
///
/// - `effort` maps to the official OpenAI Chat Completions `reasoning_effort`
///   parameter (accepted by OpenAI and most OpenAI-compatible gateways,
///   including OpenRouter).
/// - `enabled` maps to the OpenRouter extension object
///   `reasoning: {"enabled": bool}`. `enabled: false` stops reasoning models
///   from emitting chain-of-thought into `content` (which would otherwise
///   also burn `max_tokens` on reasoning). This key is only sent when you
///   explicitly set it — pure-OpenAI endpoints never see it otherwise.
/// - `summary` rides inside the same `reasoning` object; the key and its
///   values (`auto`/`concise`/`detailed`) follow the official OpenAI
///   Responses-API `reasoning.summary` parameter, which OpenRouter's chat
///   completions endpoint also accepts.
///
/// Forwarded by [`OpenAIClient`](crate::llm::OpenAIClient) in both `complete`
/// and `stream_complete`. [`AnthropicClient`](crate::llm::AnthropicClient)
/// has no mapping for these controls (extended thinking is configured
/// per-model there) and ignores them.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct ReasoningConfig {
    /// On/off toggle for providers with an explicit switch (OpenRouter
    /// `reasoning.enabled`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub enabled: Option<bool>,
    /// How much the model reasons (OpenAI `reasoning_effort`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub effort: Option<ReasoningEffort>,
    /// Reasoning summary style (OpenAI Responses `reasoning.summary`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub summary: Option<ReasoningSummary>,
}

impl ReasoningConfig {
    /// Turn reasoning off where the provider supports an explicit switch
    /// (serializes `reasoning: {"enabled": false}` — the OpenRouter form).
    pub fn disabled() -> Self {
        Self {
            enabled: Some(false),
            effort: None,
            summary: None,
        }
    }

    /// Request a specific reasoning effort (serializes `reasoning_effort`).
    pub fn effort(effort: ReasoningEffort) -> Self {
        Self {
            enabled: None,
            effort: Some(effort),
            summary: None,
        }
    }
}

/// A chat completion request to an LLM provider.
///
/// This struct implements [`Default`] so callers can use struct-update syntax
/// to stay forward-compatible with future field additions:
///
/// ```rust,ignore
/// let req = LLMRequest {
///     system: Some("...".into()),
///     messages: vec![ChatMessage::user("hi")],
///     ..LLMRequest::default()
/// };
/// ```
///
/// New fields added to `LLMRequest` in future non-breaking releases are
/// absorbed by `..LLMRequest::default()` and will not break such call sites
/// (unlike full struct literals, which must enumerate every field). For the
/// fluent equivalent, see [`LLMRequest::builder`].
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LLMRequest {
    /// Optional system prompt prepended to the conversation.
    pub system: Option<String>,
    /// Ordered list of chat messages forming the conversation.
    pub messages: Vec<ChatMessage>,
    /// Sampling temperature (0.0–2.0).
    pub temperature: f32,
    /// Maximum tokens to generate. `None` uses the provider default.
    pub max_tokens: Option<u32>,
    /// Model override for this request. `None` uses the client default.
    pub model: Option<String>,
    /// Desired response format. `None` uses the provider default.
    ///
    /// Forwarded to the provider by [`OpenAIClient`](crate::llm::OpenAIClient)
    /// (OpenAI `response_format`) and, for [`ResponseFormat::JsonSchema`], by
    /// [`AnthropicClient`](crate::llm::AnthropicClient) (Anthropic
    /// `output_config.format`). [`ResponseFormat::Json`] without a schema has no
    /// native Anthropic equivalent and is a no-op there.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub response_format: Option<ResponseFormat>,
    /// Tool definitions available to the model for this request.
    ///
    /// Forwarded to both OpenAI (`tools` with `type: "function"`) and Anthropic
    /// (`tools` with `input_schema`). Any tool calls the model makes are returned
    /// in [`LLMResponse::tool_calls`].
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tools: Option<Vec<crate::llm::ToolDefinition>>,
    /// Reasoning-model controls (effort / on-off switch / summary). `None`
    /// adds nothing to the request body. See [`ReasoningConfig`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub reasoning: Option<ReasoningConfig>,
    /// Response verbosity (OpenAI `verbosity`: `low`/`medium`/`high`).
    /// `None` adds nothing to the request body. Forwarded by
    /// [`OpenAIClient`](crate::llm::OpenAIClient); ignored by
    /// [`AnthropicClient`](crate::llm::AnthropicClient).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub verbosity: Option<Verbosity>,
    /// Escape hatch for provider parameters the kernel does not model
    /// natively (named after the OpenAI SDK's `extra_body` convention).
    ///
    /// Keys are merged into the OpenAI-compatible request body verbatim,
    /// last-write-wins over natively forwarded fields — any official spec
    /// parameter (`seed`, `stop`, `logprobs`, `parallel_tool_calls`,
    /// `service_tier`, `web_search_options`, …) or provider extension can be
    /// sent on demand. `None` adds nothing. Only
    /// [`OpenAIClient`](crate::llm::OpenAIClient) forwards it;
    /// [`AnthropicClient`](crate::llm::AnthropicClient) ignores it.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub extra_body: Option<serde_json::Map<String, serde_json::Value>>,
    /// Caller-attached observability context. The kernel does not
    /// interpret or forward this to providers — it exists so middleware
    /// (e.g. an observability adapter) can nest the generation under a
    /// caller-opened trace, vary sessions per call, and name
    /// observations. See [`ObservabilityContext`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub observability: Option<ObservabilityContext>,
}

/// Vendor-neutral observability context carried on an [`LLMRequest`].
///
/// The kernel treats this as opaque data — it never parses or forwards
/// the values. Observability middleware consumes it:
///
/// - `traceparent` lets an adapter attach the generation under a trace
///   the caller already opened (W3C trace-context format, matching the
///   standard `traceparent` header, so callers inside an OpenTelemetry
///   context can extract and pass it directly).
/// - `session_id` groups related calls per execution unit rather than
///   per client.
/// - `name` overrides the observation name (verb-first, low-cardinality,
///   model-free — backends index and filter by name).
/// - `tags`/`metadata` ride along for backend-side filtering.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct ObservabilityContext {
    /// W3C trace context of the parent span (`traceparent` header format).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub traceparent: Option<String>,
    /// Session id grouping related calls in observability backends.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub session_id: Option<String>,
    /// Observation name override (verb-first, low-cardinality, model-free).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// Tags attached to the trace in observability backends.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub tags: Vec<String>,
    /// Free-form string metadata forwarded to observability backends.
    #[serde(default, skip_serializing_if = "std::collections::BTreeMap::is_empty")]
    pub metadata: std::collections::BTreeMap<String, String>,
}

impl Default for LLMRequest {
    fn default() -> Self {
        Self {
            system: None,
            messages: Vec::new(),
            // Matches `LLMRequestBuilder::build()`'s `unwrap_or(0.7)` so the two
            // construction paths agree. Keep these coupled.
            temperature: 0.7,
            max_tokens: None,
            model: None,
            response_format: None,
            tools: None,
            reasoning: None,
            verbosity: None,
            extra_body: None,
            observability: None,
        }
    }
}

impl LLMRequest {
    /// Create a new builder for constructing an `LLMRequest`.
    pub fn builder() -> LLMRequestBuilder {
        LLMRequestBuilder::default()
    }

    /// Convert into OpenAI-format messages, consuming the request.
    ///
    /// Prepends a system message if `self.system` is set.
    pub(crate) fn into_openai_messages(self) -> Vec<(String, String)> {
        let mut out = Vec::with_capacity(self.messages.len() + 1);
        if let Some(system) = self.system {
            out.push(("system".into(), system));
        }
        for msg in self.messages {
            out.push((msg.role.to_string(), msg.text_content()));
        }
        out
    }

    /// Convert into Anthropic-format messages, consuming the request.
    ///
    /// Returns only user/assistant messages (system is handled separately by Anthropic API).
    pub(crate) fn into_anthropic_messages(self) -> Vec<(String, String)> {
        self.messages
            .into_iter()
            .map(|m| (m.role.to_string(), m.text_content()))
            .collect()
    }
}

/// Builder for constructing `LLMRequest` instances with a fluent API.
///
/// # Example
///
/// ```no_run
/// use llm_kernel::llm::LLMRequest;
///
/// let request = LLMRequest::builder()
///     .system("You are concise.")
///     .user_message("Summarise Rust ownership in one line.")
///     .temperature(0.0)
///     .build();
/// ```
#[derive(Debug, Clone, Default)]
pub struct LLMRequestBuilder {
    system: Option<String>,
    messages: Vec<ChatMessage>,
    temperature: Option<f32>,
    max_tokens: Option<u32>,
    model: Option<String>,
    response_format: Option<ResponseFormat>,
    tools: Option<Vec<crate::llm::ToolDefinition>>,
    reasoning: Option<ReasoningConfig>,
    verbosity: Option<Verbosity>,
    extra_body: Option<serde_json::Map<String, serde_json::Value>>,
    observability: Option<ObservabilityContext>,
}

impl LLMRequestBuilder {
    /// Set the system prompt.
    pub fn system(mut self, prompt: impl Into<String>) -> Self {
        self.system = Some(prompt.into());
        self
    }

    /// Append a user message.
    pub fn user_message(mut self, content: impl Into<String>) -> Self {
        self.messages.push(ChatMessage::user(content));
        self
    }

    /// Append an assistant message.
    pub fn assistant_message(mut self, content: impl Into<String>) -> Self {
        self.messages.push(ChatMessage::assistant(content));
        self
    }

    /// Append a raw `ChatMessage`.
    pub fn message(mut self, msg: ChatMessage) -> Self {
        self.messages.push(msg);
        self
    }

    /// Replace the message list with the provided messages.
    ///
    /// Convenience for callers that already hold a `Vec<ChatMessage>` (e.g. a
    /// pre-built conversation), avoiding repeated `.message()` calls.
    pub fn messages(mut self, messages: Vec<ChatMessage>) -> Self {
        self.messages = messages;
        self
    }

    /// Set the sampling temperature.
    pub fn temperature(mut self, temp: f32) -> Self {
        self.temperature = Some(temp);
        self
    }

    /// Set the maximum tokens to generate.
    pub fn max_tokens(mut self, tokens: u32) -> Self {
        self.max_tokens = Some(tokens);
        self
    }

    /// Set the maximum tokens to generate, or `None` to use the provider default.
    ///
    /// Convenience for callers that already hold an `Option<u32>` (e.g. a
    /// config field), avoiding a conditional chain.
    pub fn maybe_max_tokens(mut self, tokens: Option<u32>) -> Self {
        self.max_tokens = tokens;
        self
    }

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

    /// Set the desired response format.
    pub fn response_format(mut self, format: ResponseFormat) -> Self {
        self.response_format = Some(format);
        self
    }

    /// Set the tool definitions available to the model.
    pub fn tools(mut self, tools: Vec<crate::llm::ToolDefinition>) -> Self {
        self.tools = Some(tools);
        self
    }

    /// Set reasoning-model controls (effort / on-off switch / summary).
    pub fn reasoning(mut self, cfg: ReasoningConfig) -> Self {
        self.reasoning = Some(cfg);
        self
    }

    /// Set the response verbosity (OpenAI `verbosity`).
    pub fn verbosity(mut self, verbosity: Verbosity) -> Self {
        self.verbosity = Some(verbosity);
        self
    }

    /// Merge extra provider parameters into the request body verbatim
    /// (last-write-wins). Any official spec parameter or provider extension.
    pub fn extra_body(mut self, extra: serde_json::Map<String, serde_json::Value>) -> Self {
        self.extra_body = Some(extra);
        self
    }

    /// Attach an observability context for middleware (kernel-opaque).
    pub fn observability(mut self, context: ObservabilityContext) -> Self {
        self.observability = Some(context);
        self
    }

    /// Convenience: set just the session id, creating the context if
    /// absent and preserving other fields otherwise.
    pub fn with_session(mut self, session_id: impl Into<String>) -> Self {
        let context = self.observability.get_or_insert_with(Default::default);
        context.session_id = Some(session_id.into());
        self
    }

    /// Build the `LLMRequest`.
    pub fn build(self) -> LLMRequest {
        LLMRequest {
            system: self.system,
            messages: self.messages,
            temperature: self.temperature.unwrap_or(0.7),
            max_tokens: self.max_tokens,
            model: self.model,
            response_format: self.response_format,
            tools: self.tools,
            reasoning: self.reasoning,
            verbosity: self.verbosity,
            extra_body: self.extra_body,
            observability: self.observability,
        }
    }
}

/// A chat completion response from an LLM provider.
///
/// Implements [`Default`] for forward-compatible struct-update syntax
/// (`LLMResponse { ..LLMResponse::default() }`).
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct LLMResponse {
    /// Generated text content.
    pub content: String,
    /// Reasoning model's chain-of-thought (GLM-4.5+/z.ai, OpenAI o1, DeepSeek-R1).
    ///
    /// When the provider leaves `content` empty and returns the final answer in
    /// `reasoning_content`, the client promotes the reasoning into `content` and
    /// still preserves the original here. `None` for non-reasoning models and for
    /// cache entries written before this field existed (serde default).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub reasoning: Option<String>,
    /// Model that produced this response.
    pub model: String,
    /// Token usage statistics.
    pub usage: TokenUsage,
    /// Tool calls the model requested this turn.
    ///
    /// Empty unless the request supplied [`LLMRequest::tools`] and the model
    /// chose to call one. Each entry carries the provider-assigned call `id`,
    /// tool `name`, and JSON-encoded `arguments`.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub tool_calls: Vec<crate::llm::ToolCall>,
    /// Reason the generation stopped (e.g. `"stop"`, `"length"`, `"tool_calls"`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub finish_reason: Option<String>,
    /// Provider-assigned response ID (useful for logging and deduplication).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub id: Option<String>,
    /// Unix timestamp (seconds) when the response was created.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub created: Option<u64>,
}

/// Token usage statistics from an LLM response.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct TokenUsage {
    /// Number of tokens in the prompt.
    pub prompt_tokens: u32,
    /// Number of tokens in the completion.
    pub completion_tokens: u32,
    /// Total tokens (prompt + completion).
    pub total_tokens: u32,
    /// Reasoning-only tokens (o1 / GLM-4.7 `completion_tokens_details.reasoning_tokens`).
    /// `None` when the provider does not report it.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub reasoning_tokens: Option<u32>,
}

/// A single event in an LLM streaming response.
///
/// `#[non_exhaustive]`: new variants (e.g. reasoning/tool-call streaming) may be
/// added in a minor release without breaking downstream `match` arms — external
/// consumers must include a `_ =>` arm. Within this crate, exhaustive matching is
/// still permitted.
#[derive(Debug, Clone)]
#[non_exhaustive]
pub enum StreamEvent {
    /// Partial text content arrived.
    Delta {
        /// The partial text chunk.
        content: String,
    },
    /// Partial reasoning content arrived (GLM `delta.reasoning_content`,
    /// Anthropic `thinking_delta`).
    ///
    /// **Streaming/reasoning asymmetry (important):** the non-streaming
    /// `LLMClient::complete` path promotes reasoning into `content` when the
    /// provider leaves `content` empty (notably GLM-4.7), so non-streaming callers
    /// transparently receive the final answer. The streaming path does **not**
    /// perform this promotion — it emits `ReasoningDelta` and `Delta` as separate
    /// events and leaves accumulation to the consumer. For reasoning-only models
    /// that put the answer in `reasoning_content` (GLM-4.7), streaming consumers
    /// **must** accumulate both `ReasoningDelta` and `Delta` chunks to reconstruct
    /// the full answer; accumulating `Delta` alone yields an empty result.
    ReasoningDelta {
        /// The partial reasoning chunk.
        content: String,
    },
    /// Final token usage statistics.
    Usage(TokenUsage),
    /// Stream has ended.
    Done,
}

/// Type alias for a boxed streaming response.
#[cfg(feature = "client-async")]
pub type LLMStream =
    Pin<Box<dyn futures_core::Stream<Item = crate::error::Result<StreamEvent>> + Send>>;

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

    #[test]
    fn message_role_display() {
        assert_eq!(MessageRole::System.to_string(), "system");
        assert_eq!(MessageRole::User.to_string(), "user");
        assert_eq!(MessageRole::Assistant.to_string(), "assistant");
        assert_eq!(MessageRole::Tool.to_string(), "tool");
    }

    #[test]
    fn message_role_serde_roundtrip() {
        let json = serde_json::to_string(&MessageRole::User).unwrap();
        assert_eq!(json, "\"user\"");
        let back: MessageRole = serde_json::from_str(&json).unwrap();
        assert_eq!(back, MessageRole::User);
    }

    #[test]
    fn chat_message_constructors() {
        let sys = ChatMessage::system("instructions");
        assert_eq!(sys.role, MessageRole::System);

        let user = ChatMessage::user("hello");
        assert_eq!(user.role, MessageRole::User);

        let asst = ChatMessage::assistant("hi there");
        assert_eq!(asst.role, MessageRole::Assistant);

        let tool = ChatMessage::tool("result");
        assert_eq!(tool.role, MessageRole::Tool);
    }

    #[test]
    fn single_text_serializes_as_string() {
        let msg = ChatMessage::user("hello");
        let json = serde_json::to_string(&msg).unwrap();
        assert!(json.contains("\"content\":\"hello\""), "got: {json}");
    }

    #[test]
    fn multipart_serializes_as_array() {
        let msg = ChatMessage::user_multimodal(vec![
            ContentPart::text("describe this"),
            ContentPart::image_url("https://example.com/img.png"),
        ]);
        let json = serde_json::to_string(&msg).unwrap();
        assert!(
            json.contains("\"content\":["),
            "expected array serialization, got: {json}"
        );
    }

    #[test]
    fn single_text_deserialize_from_string() {
        let json = r#"{"role":"user","content":"hello"}"#;
        let msg: ChatMessage = serde_json::from_str(json).unwrap();
        assert_eq!(msg.role, MessageRole::User);
        assert_eq!(msg.content.len(), 1);
        assert_eq!(msg.text_content(), "hello");
    }

    #[test]
    fn multipart_deserialize_from_array() {
        let json = r#"{"role":"user","content":[{"type":"text","text":"hi"},{"type":"image_url","url":"https://x.com/img.png"}]}"#;
        let msg: ChatMessage = serde_json::from_str(json).unwrap();
        assert_eq!(msg.content.len(), 2);
    }

    #[test]
    fn content_part_text_helper() {
        let p = ContentPart::text("hello");
        assert_eq!(p.as_text(), Some("hello"));
    }

    #[test]
    fn response_format_json_serialization() {
        let fmt = ResponseFormat::Json;
        let json = serde_json::to_string(&fmt).unwrap();
        assert!(json.contains("\"type\":\"json\""), "got: {json}");
    }

    #[test]
    fn response_format_text_serialization() {
        let fmt = ResponseFormat::Text;
        let json = serde_json::to_string(&fmt).unwrap();
        assert!(json.contains("\"type\":\"text\""), "got: {json}");
    }

    #[test]
    fn response_format_json_schema() {
        let fmt = ResponseFormat::JsonSchema {
            schema: serde_json::json!({"type": "object"}),
        };
        let json = serde_json::to_string(&fmt).unwrap();
        assert!(json.contains("json_schema"), "got: {json}");
    }

    #[test]
    fn builder_basic() {
        let req = LLMRequest::builder()
            .system("you are helpful")
            .user_message("hello")
            .temperature(0.5)
            .build();
        assert_eq!(req.system.as_deref(), Some("you are helpful"));
        assert_eq!(req.messages.len(), 1);
        assert_eq!(req.temperature, 0.5);
    }

    #[test]
    fn builder_with_model_and_format() {
        let req = LLMRequest::builder()
            .user_message("test")
            .model("gpt-4o-mini")
            .response_format(ResponseFormat::Json)
            .max_tokens(100)
            .build();
        assert_eq!(req.model.as_deref(), Some("gpt-4o-mini"));
        assert!(matches!(req.response_format, Some(ResponseFormat::Json)));
        assert_eq!(req.max_tokens, Some(100));
    }

    #[test]
    fn builder_with_tools() {
        use crate::llm::ToolDefinition;
        let req = LLMRequest::builder()
            .user_message("what's the weather?")
            .tools(vec![ToolDefinition {
                name: "get_weather".into(),
                description: "Get weather".into(),
                input_schema: serde_json::json!({"type": "object"}),
            }])
            .build();
        assert!(req.tools.is_some());
        assert_eq!(req.tools.unwrap().len(), 1);
    }

    /// `LLMRequest::default()` and `LLMRequest::builder().build()` must agree on
    /// every field. The temperature default (0.7) in particular is duplicated
    /// between the manual `Default` impl and the builder's `unwrap_or(0.7)`;
    /// this test couples them so a future edit to one without the other is caught.
    #[test]
    fn default_matches_builder_default() {
        let from_default = LLMRequest::default();
        let from_builder = LLMRequest::builder().build();
        assert_eq!(from_default.temperature, from_builder.temperature);
        assert_eq!(from_default.temperature, 0.7);
        assert!(from_default.system.is_none());
        assert!(from_default.messages.is_empty());
        assert!(from_default.max_tokens.is_none());
        assert!(from_default.model.is_none());
        assert!(from_default.response_format.is_none());
        assert!(from_default.tools.is_none());
        assert!(from_default.reasoning.is_none());
        assert!(from_default.verbosity.is_none());
        assert!(from_default.extra_body.is_none());
    }

    #[test]
    fn reasoning_config_disabled_serializes_enabled_only() {
        let json = serde_json::to_value(ReasoningConfig::disabled()).unwrap();
        assert_eq!(json, serde_json::json!({"enabled": false}));
    }

    #[test]
    fn reasoning_config_effort_serializes_effort_only() {
        let json = serde_json::to_value(ReasoningConfig::effort(ReasoningEffort::Medium)).unwrap();
        assert_eq!(json, serde_json::json!({"effort": "medium"}));
        // Empty config serializes to an empty object (no phantom keys).
        assert_eq!(
            serde_json::to_value(ReasoningConfig::default()).unwrap(),
            serde_json::json!({})
        );
    }

    #[test]
    fn observability_context_roundtrip() {
        let mut metadata = std::collections::BTreeMap::new();
        metadata.insert("source".to_string(), "router".to_string());
        let req = LLMRequest::builder()
            .user_message("hi")
            .observability(ObservabilityContext {
                traceparent: Some(
                    "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01".to_string(),
                ),
                session_id: Some("s-1".to_string()),
                name: Some("generate-reply".to_string()),
                tags: vec!["prod".to_string()],
                metadata,
            })
            .build();
        let ctx = req.observability.as_ref().unwrap();
        assert_eq!(ctx.name.as_deref(), Some("generate-reply"));
        assert_eq!(
            ctx.metadata.get("source").map(String::as_str),
            Some("router")
        );

        // Serializes nested; absent when None; absent key deserializes to None.
        let json = serde_json::to_value(&req).unwrap();
        assert_eq!(json["observability"]["session_id"], "s-1");
        let back: LLMRequest = serde_json::from_value(json).unwrap();
        assert_eq!(back.observability, req.observability);
        let legacy = serde_json::json!({"messages": [], "temperature": 0.5});
        let plain: LLMRequest = serde_json::from_value(legacy).unwrap();
        assert!(plain.observability.is_none());
    }

    #[test]
    fn with_session_preserves_other_context_fields() {
        let req = LLMRequest::builder()
            .observability(ObservabilityContext {
                name: Some("generate-reply".to_string()),
                ..Default::default()
            })
            .with_session("s-2")
            .build();
        let ctx = req.observability.as_ref().unwrap();
        assert_eq!(ctx.session_id.as_deref(), Some("s-2"));
        assert_eq!(ctx.name.as_deref(), Some("generate-reply"));
        // Absent context is created on demand.
        let fresh = LLMRequest::builder().with_session("s-3").build();
        assert_eq!(
            fresh.observability.unwrap().session_id.as_deref(),
            Some("s-3")
        );
    }

    #[test]
    fn builder_reasoning_roundtrip() {
        let req = LLMRequest::builder()
            .user_message("hi")
            .reasoning(ReasoningConfig::disabled())
            .build();
        assert_eq!(req.reasoning.as_ref().unwrap().enabled, Some(false));

        // Serialized request nests under `reasoning`; absent when None.
        let with = serde_json::to_value(&req).unwrap();
        assert_eq!(with["reasoning"]["enabled"], false);
        let without = serde_json::to_value(LLMRequest::default()).unwrap();
        assert!(without.get("reasoning").is_none());
    }

    #[test]
    fn builder_verbosity_roundtrip() {
        let req = LLMRequest::builder()
            .user_message("hi")
            .verbosity(Verbosity::Low)
            .build();
        assert_eq!(req.verbosity, Some(Verbosity::Low));
        let json = serde_json::to_value(&req).unwrap();
        assert_eq!(json["verbosity"], "low");
        // Absent when None.
        assert!(
            serde_json::to_value(LLMRequest::default())
                .unwrap()
                .get("verbosity")
                .is_none()
        );
    }

    #[test]
    fn builder_extra_body_roundtrip() {
        let mut extra = serde_json::Map::new();
        extra.insert("seed".into(), 42.into());
        extra.insert("stop".into(), ["\n\nUser:"].into());
        let req = LLMRequest::builder()
            .user_message("hi")
            .extra_body(extra)
            .build();
        let json = serde_json::to_value(&req).unwrap();
        assert_eq!(json["extra_body"]["seed"], 42);
        assert!(
            serde_json::to_value(LLMRequest::default())
                .unwrap()
                .get("extra_body")
                .is_none()
        );
    }

    #[test]
    fn llm_request_deserializes_without_reasoning_field() {
        // Payloads written before `reasoning` existed must still deserialize.
        let json =
            r#"{"system":null,"messages":[],"temperature":0.7,"max_tokens":null,"model":null}"#;
        let req: LLMRequest = serde_json::from_str(json).unwrap();
        assert!(req.reasoning.is_none());
        assert!(req.verbosity.is_none());
    }

    #[test]
    fn builder_messages_setter_replaces_list() {
        let conv = vec![ChatMessage::user("first"), ChatMessage::assistant("second")];
        let req = LLMRequest::builder().messages(conv).build();
        assert_eq!(req.messages.len(), 2);
        assert_eq!(req.messages[0].role, MessageRole::User);
        assert_eq!(req.messages[1].role, MessageRole::Assistant);
    }

    #[test]
    fn builder_maybe_max_tokens_accepts_option() {
        // Some — sets the value
        let req = LLMRequest::builder().maybe_max_tokens(Some(512)).build();
        assert_eq!(req.max_tokens, Some(512));
        // None — explicitly defers to provider default
        let req = LLMRequest::builder().maybe_max_tokens(None).build();
        assert_eq!(req.max_tokens, None);
    }

    #[test]
    fn into_openai_messages_with_system() {
        let req = LLMRequest::builder()
            .system("be helpful")
            .user_message("hi")
            .assistant_message("hello")
            .build();
        let msgs = req.into_openai_messages();
        assert_eq!(msgs.len(), 3);
        assert_eq!(msgs[0].0, "system");
        assert_eq!(msgs[1].0, "user");
        assert_eq!(msgs[2].0, "assistant");
    }

    #[test]
    fn into_anthropic_messages_excludes_system() {
        let req = LLMRequest::builder()
            .system("be helpful")
            .user_message("hi")
            .build();
        let msgs = req.into_anthropic_messages();
        assert_eq!(msgs.len(), 1);
        assert_eq!(msgs[0].0, "user");
    }

    #[test]
    fn text_content_extracts_text() {
        let msg = ChatMessage::user_multimodal(vec![
            ContentPart::text("hello "),
            ContentPart::image_url("http://x.com/i.png"),
            ContentPart::text("world"),
        ]);
        assert_eq!(msg.text_content(), "hello world");
    }

    #[test]
    fn llm_response_back_compat_without_reasoning_field() {
        // Cache entries written before `reasoning` existed must still deserialize.
        let json = r#"{"content":"hi","model":"m","usage":{"prompt_tokens":0,"completion_tokens":0,"total_tokens":0}}"#;
        let r: LLMResponse = serde_json::from_str(json).unwrap();
        assert_eq!(r.content, "hi");
        assert!(r.reasoning.is_none());
    }

    #[test]
    fn token_usage_back_compat_without_reasoning_tokens() {
        let json = r#"{"prompt_tokens":1,"completion_tokens":2,"total_tokens":3}"#;
        let u: TokenUsage = serde_json::from_str(json).unwrap();
        assert_eq!(u.total_tokens, 3);
        assert!(u.reasoning_tokens.is_none());
    }
}