rstructor 0.6.0

use async_trait::async_trait;
use serde::de::DeserializeOwned;
use std::time::Duration;
use tracing::{Instrument, debug, error, info, instrument, trace, warn};

use crate::backend::model_macro::define_model_enum;
use crate::backend::routing::{
    GROQ_BASE_URL, KeyPolicy, LM_STUDIO_BASE_URL, MOONSHOT_BASE_URL, OLLAMA_BASE_URL,
    OPENROUTER_BASE_URL,
};
use crate::backend::{
    ChatMessage, DEFAULT_REQUEST_TIMEOUT, GenerateResult, LLMClient, MaterializeAttemptError,
    MaterializeFailure, MaterializeInternalOutput, MaterializeReport, MaterializeResult, ModelInfo,
    OpenAICompatibleChatCompletionRequest, OpenAICompatibleChatCompletionResponse, ResponseFormat,
    StrictSchemaProvider, ThinkingLevel, build_http_client, check_response_status_with_capture,
    compile_strict_schema, convert_openai_compatible_chat_messages,
    generate_with_retry_attempts_with_history, generate_with_retry_attempts_with_initial_messages,
    generate_with_retry_with_history, generate_with_retry_with_initial_messages, handle_http_error,
    materialize_request_error, materialize_with_media_and_attempts_with_retry,
    materialize_with_media_with_retry, parse_json_response, parse_validate_and_create_output,
    request_messages,
};
#[cfg(feature = "streaming")]
use crate::backend::{OpenAICompatibleChatMessage, OpenAICompatibleMessageContent};
use crate::error::{ApiErrorKind, RStructorError, Result};
use crate::model::Instructor;

define_model_enum! {
    /// OpenAI models available for completion
    ///
    /// For the latest available models and their identifiers, check the
    /// [OpenAI Models Documentation](https://developers.openai.com/api/docs/models).
    ///
    /// # Using Custom Models
    ///
    /// You can specify any model name as a string using `Custom` variant or `FromStr`:
    ///
    /// ```rust
    /// use rstructor::OpenAIModel;
    /// use std::str::FromStr;
    ///
    /// // Using Custom variant
    /// let model = OpenAIModel::Custom("gpt-4-custom".to_string());
    ///
    /// // Using FromStr (useful for config files)
    /// let model = OpenAIModel::from_str("gpt-4-custom").unwrap();
    ///
    /// // Or use the convenience method
    /// let model = OpenAIModel::from_string("gpt-4-custom");
    /// ```
    pub enum Model {
        /// GPT-5.6 (alias for GPT-5.6 Sol, the latest flagship model)
        Gpt56 => "gpt-5.6",
        /// GPT-5.6 Sol (flagship model for frontier capability)
        Gpt56Sol => "gpt-5.6-sol",
        /// GPT-5.6 Terra (balanced intelligence, latency, and cost)
        Gpt56Terra => "gpt-5.6-terra",
        /// GPT-5.6 Luna (efficient model for high-volume workloads)
        Gpt56Luna => "gpt-5.6-luna",
        /// GPT-5.5 Pro (most capable GPT-5.5 model)
        Gpt55Pro => "gpt-5.5-pro",
        /// GPT-5.5 (previous frontier model for complex professional work)
        Gpt55 => "gpt-5.5",
        /// GPT-5.4 Pro (most capable GPT-5.4-class model)
        Gpt54Pro => "gpt-5.4-pro",
        /// GPT-5.4 (more affordable frontier model for complex professional work)
        Gpt54 => "gpt-5.4",
        /// GPT-5.4 Mini (lower-latency, lower-cost GPT-5.4-class model)
        Gpt54Mini => "gpt-5.4-mini",
        /// GPT-5.4 Nano (cheapest GPT-5.4-class model for high-volume tasks)
        Gpt54Nano => "gpt-5.4-nano",
        /// GPT-5.3 Chat Latest (ChatGPT GPT-5.3 model)
        Gpt53ChatLatest => "gpt-5.3-chat-latest",
        /// GPT-5.3 Codex (coding-focused GPT-5.3 model)
        Gpt53Codex => "gpt-5.3-codex",
        /// GPT-5.2 Pro (previous GPT-5.2 pro model)
        Gpt52Pro => "gpt-5.2-pro",
        /// GPT-5.2 (previous GPT-5.2 model)
        Gpt52 => "gpt-5.2",
        /// GPT-5.2 Chat Latest (ChatGPT GPT-5.2 model)
        Gpt52ChatLatest => "gpt-5.2-chat-latest",
        /// GPT-5.2 Codex (coding-focused GPT-5.2 model)
        Gpt52Codex => "gpt-5.2-codex",
        /// GPT-5.1 (GPT-5.1 model)
        Gpt51 => "gpt-5.1",
        /// GPT-5 Chat Latest (ChatGPT GPT-5 model)
        Gpt5ChatLatest => "gpt-5-chat-latest",
        /// GPT-5 Pro (most capable GPT-5 model)
        Gpt5Pro => "gpt-5-pro",
        /// GPT-5 (standard GPT-5 model)
        Gpt5 => "gpt-5",
        /// GPT-5 Nano (smallest GPT-5 model)
        Gpt5Nano => "gpt-5-nano",
        /// GPT-5 Mini (smaller, faster GPT-5 model)
        Gpt5Mini => "gpt-5-mini",
        /// GPT-4.1 (GPT-4.1 model)
        Gpt41 => "gpt-4.1",
        /// GPT-4.1 Mini (smaller GPT-4.1)
        Gpt41Mini => "gpt-4.1-mini",
        /// GPT-4.1 Nano (smallest GPT-4.1)
        Gpt41Nano => "gpt-4.1-nano",
        /// GPT-4o (previous GPT-4o model, optimized for chat)
        Gpt4O => "gpt-4o",
        /// GPT-4o Mini (smaller, faster, more cost-effective version)
        Gpt4OMini => "gpt-4o-mini",
        /// GPT-4 Turbo (high-intelligence model)
        Gpt4Turbo => "gpt-4-turbo",
        /// GPT-4 (standard GPT-4 model)
        Gpt4 => "gpt-4",
        /// GPT-3.5 Turbo (efficient model for simple tasks)
        Gpt35Turbo => "gpt-3.5-turbo",
    }
}

/// Configuration for the OpenAI client
#[derive(Debug, Clone)]
pub struct OpenAIConfig {
    pub api_key: String,
    pub model: Model,
    pub temperature: f32,
    pub max_tokens: Option<u32>,
    /// Total timeout for each HTTP request.
    /// Defaults to [`DEFAULT_REQUEST_TIMEOUT`](crate::DEFAULT_REQUEST_TIMEOUT) (5 minutes).
    pub timeout: Option<Duration>,
    pub max_retries: Option<usize>,
    /// Custom base URL for OpenAI-compatible APIs (e.g., local LLMs, proxy endpoints)
    /// Defaults to "https://api.openai.com/v1" if not set
    pub base_url: Option<String>,
    /// Thinking level for GPT-5.x models (reasoning effort)
    /// Controls the depth of reasoning applied to prompts
    pub thinking_level: Option<ThinkingLevel>,
    /// Opt-in caller-sanitized provider response capture.
    pub response_body_capture: Option<crate::ResponseBodyCapture>,
}

/// OpenAI client for generating completions
#[derive(Clone)]
pub struct OpenAIClient {
    config: OpenAIConfig,
    client: reqwest::Client,
}

// ResponseFormat and JsonSchemaFormat are imported from utils and shared
// OpenAI-compatible chat completion request/response types are in openai_compatible.rs.

impl OpenAIClient {
    fn with_api_key(api_key: String) -> Self {
        let config = OpenAIConfig {
            api_key,
            model: Model::Gpt56Sol, // Default to GPT-5.6 Sol (latest recommended flagship)
            temperature: 0.0,
            max_tokens: None,
            timeout: Some(DEFAULT_REQUEST_TIMEOUT), // Default: 5-minute request timeout
            max_retries: Some(3),                   // Default: 3 retries with error feedback
            base_url: None,                         // Default: use official OpenAI API
            thinking_level: Some(ThinkingLevel::Medium), // GPT-5.6 defaults to medium reasoning
            response_body_capture: None,
        };

        Self {
            config,
            client: build_http_client(DEFAULT_REQUEST_TIMEOUT),
        }
    }

    fn api_key_from_env(provider: &'static str, variable: &'static str) -> Result<String> {
        std::env::var(variable)
            .ok()
            .filter(|api_key| !api_key.is_empty())
            .ok_or_else(|| RStructorError::api_error(provider, ApiErrorKind::AuthenticationFailed))
    }

    /// Create an OpenAI-compatible client with an endpoint-specific key policy.
    pub(crate) fn openai_compatible(base_url: &'static str, key_policy: KeyPolicy) -> Result<Self> {
        let api_key = match key_policy {
            KeyPolicy::ProviderDefault => Self::api_key_from_env("OpenAI", "OPENAI_API_KEY")?,
            KeyPolicy::Keyless => String::new(),
            KeyPolicy::Environment { provider, variable } => {
                Self::api_key_from_env(provider, variable)?
            }
        };

        Ok(Self::with_api_key(api_key).base_url(base_url))
    }

    /// Create a new OpenAI client with the provided API key.
    ///
    /// # Arguments
    ///
    /// * `api_key` - Your OpenAI API key
    ///
    /// # Examples
    ///
    /// ```no_run
    /// # use rstructor::OpenAIClient;
    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// let client = OpenAIClient::new("your-openai-api-key")?;
    /// # Ok(())
    /// # }
    /// ```
    #[instrument(name = "openai_client_new", skip(api_key), fields(model = ?Model::Gpt56Sol))]
    pub fn new(api_key: impl Into<String>) -> Result<Self> {
        let api_key = api_key.into();
        if api_key.is_empty() {
            return Err(RStructorError::api_error(
                "OpenAI",
                ApiErrorKind::AuthenticationFailed,
            ));
        }
        info!("Creating new OpenAI client");
        trace!("API key length: {}", api_key.len());

        debug!("OpenAI client created with default configuration");
        Ok(Self::with_api_key(api_key))
    }

    /// Create a new OpenAI client by reading the API key from the `OPENAI_API_KEY` environment variable.
    ///
    /// # Errors
    ///
    /// Returns an error if `OPENAI_API_KEY` is not set.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// # use rstructor::OpenAIClient;
    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// let client = OpenAIClient::from_env()?;
    /// # Ok(())
    /// # }
    /// ```
    #[instrument(name = "openai_client_from_env", fields(model = ?Model::Gpt56Sol))]
    pub fn from_env() -> Result<Self> {
        let api_key = std::env::var("OPENAI_API_KEY")
            .map_err(|_| RStructorError::api_error("OpenAI", ApiErrorKind::AuthenticationFailed))?;

        info!("Creating new OpenAI client from environment variable");
        trace!("API key length: {}", api_key.len());

        debug!("OpenAI client created with default configuration");
        Ok(Self::with_api_key(api_key))
    }

    /// Connect to a local [Ollama](https://docs.ollama.com/api/openai-compatibility)
    /// server at `http://localhost:11434/v1`.
    ///
    /// Local Ollama requests are keyless and send no `Authorization` header.
    /// Select a pulled model with [`model`](Self::model).
    ///
    /// # Examples
    ///
    /// ```
    /// use rstructor::OpenAIClient;
    ///
    /// let client = OpenAIClient::ollama()?.model("llama3.3");
    /// # let _ = client;
    /// # Ok::<(), rstructor::RStructorError>(())
    /// ```
    pub fn ollama() -> Result<Self> {
        Self::openai_compatible(OLLAMA_BASE_URL, KeyPolicy::Keyless)
    }

    /// Connect to a local [LM Studio](https://lmstudio.ai/docs/developer/openai-compat)
    /// server at `http://localhost:1234/v1`.
    ///
    /// LM Studio does not require authentication by default, so this constructor
    /// sends no `Authorization` header. Select a loaded model with
    /// [`model`](Self::model).
    ///
    /// # Examples
    ///
    /// ```
    /// use rstructor::OpenAIClient;
    ///
    /// let client = OpenAIClient::lm_studio()?.model("your-loaded-model");
    /// # let _ = client;
    /// # Ok::<(), rstructor::RStructorError>(())
    /// ```
    pub fn lm_studio() -> Result<Self> {
        Self::openai_compatible(LM_STUDIO_BASE_URL, KeyPolicy::Keyless)
    }

    /// Connect to [OpenRouter](https://openrouter.ai/docs/quickstart).
    ///
    /// Reads `OPENROUTER_API_KEY` and uses `https://openrouter.ai/api/v1`.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use rstructor::OpenAIClient;
    ///
    /// # fn example() -> rstructor::Result<()> {
    /// let client = OpenAIClient::openrouter()?.model("moonshotai/kimi-k3");
    /// # let _ = client;
    /// # Ok(())
    /// # }
    /// ```
    pub fn openrouter() -> Result<Self> {
        Self::openai_compatible(
            OPENROUTER_BASE_URL,
            KeyPolicy::Environment {
                provider: "OpenRouter",
                variable: "OPENROUTER_API_KEY",
            },
        )
    }

    /// Connect to [Groq](https://console.groq.com/docs/openai).
    ///
    /// Reads `GROQ_API_KEY` and uses `https://api.groq.com/openai/v1`.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use rstructor::OpenAIClient;
    ///
    /// # fn example() -> rstructor::Result<()> {
    /// let client = OpenAIClient::groq()?.model("openai/gpt-oss-120b");
    /// # let _ = client;
    /// # Ok(())
    /// # }
    /// ```
    pub fn groq() -> Result<Self> {
        Self::openai_compatible(
            GROQ_BASE_URL,
            KeyPolicy::Environment {
                provider: "Groq",
                variable: "GROQ_API_KEY",
            },
        )
    }

    /// Connect to the international
    /// [Moonshot/Kimi API](https://platform.kimi.ai/docs/api/overview).
    ///
    /// Reads `MOONSHOT_API_KEY` and uses `https://api.moonshot.ai/v1`.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use rstructor::OpenAIClient;
    ///
    /// # fn example() -> rstructor::Result<()> {
    /// let client = OpenAIClient::moonshot()?.model("kimi-k3");
    /// # let _ = client;
    /// # Ok(())
    /// # }
    /// ```
    pub fn moonshot() -> Result<Self> {
        Self::openai_compatible(
            MOONSHOT_BASE_URL,
            KeyPolicy::Environment {
                provider: "Moonshot",
                variable: "MOONSHOT_API_KEY",
            },
        )
    }

    // Builder methods are generated by the macro below
}

// Generate builder methods using macro
crate::impl_client_builder_methods! {
    client_type: OpenAIClient,
    config_type: OpenAIConfig,
    model_type: Model,
    provider_name: "OpenAI"
}

impl OpenAIClient {
    /// Set a custom base URL for OpenAI-compatible APIs (e.g., local LLMs, proxy endpoints).
    ///
    /// # Arguments
    ///
    /// * `base_url` - Base URL without trailing slash (e.g., "http://localhost:1234/v1" or "https://api.example.com/v1")
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use rstructor::OpenAIClient;
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let client = OpenAIClient::new("api-key")?
    ///     .base_url("http://localhost:1234/v1")
    ///     .model("llama-3.1-70b");
    /// # Ok(())
    /// # }
    /// ```
    #[tracing::instrument(skip(self, base_url))]
    pub fn base_url(mut self, base_url: impl Into<String>) -> Self {
        let base_url_str = base_url.into();
        tracing::debug!(
            previous_base_url = ?self.config.base_url,
            new_base_url = %base_url_str,
            "Setting custom base URL"
        );
        self.config.base_url = Some(base_url_str);
        self
    }

    /// Set the thinking level for GPT-5.x models (reasoning effort).
    ///
    /// Controls the depth of reasoning the model applies to prompts.
    /// Higher thinking levels provide deeper reasoning but increase latency and cost.
    ///
    /// Note: When reasoning is enabled (any level except `Off`), temperature is
    /// automatically set to 1.0 as required by the API.
    ///
    /// # Reasoning Effort Levels
    ///
    /// - `Off`: No extended reasoning (maps to "none")
    /// - `Minimal`: Light reasoning (maps to "low")
    /// - `Low`: Standard reasoning (maps to "low", default)
    /// - `Medium`: Balanced reasoning (maps to "medium")
    /// - `High`: Deep reasoning (maps to "high")
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use rstructor::{OpenAIClient, ThinkingLevel};
    ///
    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// let client = OpenAIClient::from_env()?
    ///     .thinking_level(ThinkingLevel::High);
    /// # Ok(())
    /// # }
    /// ```
    #[tracing::instrument(skip(self))]
    pub fn thinking_level(mut self, level: ThinkingLevel) -> Self {
        tracing::debug!(
            previous_level = ?self.config.thinking_level,
            new_level = ?level,
            "Setting thinking level"
        );
        self.config.thinking_level = Some(level);
        self
    }

    /// Internal implementation of materialize (without retry logic)
    /// Accepts conversation history for multi-turn interactions.
    /// Returns the data, raw response, and optional usage info.
    ///
    /// Uses OpenAI's native Structured Outputs with `response_format: json_schema`
    /// for guaranteed schema compliance.
    ///
    /// The raw response is included to enable conversation history tracking for retries,
    /// which improves prompt caching efficiency.
    async fn materialize_internal<T>(
        &self,
        messages: &[ChatMessage],
    ) -> std::result::Result<MaterializeInternalOutput<T>, MaterializeAttemptError>
    where
        T: Instructor + DeserializeOwned + Send + 'static,
    {
        info!("Generating structured response with OpenAI (native structured outputs)");

        // Get the schema for type T
        let schema = T::try_schema().map_err(MaterializeAttemptError::preflight)?;
        let schema_name = T::schema_name().unwrap_or_else(|| "output".to_string());
        // Avoid calling to_string() in trace to prevent potential stack overflow with complex schemas
        trace!(schema_name = schema_name, "Retrieved JSON schema for type");

        // Reject dynamic maps before OpenAI's strict object transform can
        // silently narrow them to empty objects.
        let schema_json =
            compile_strict_schema(&schema, StrictSchemaProvider::OpenAI, "structured output")
                .map_err(MaterializeAttemptError::preflight)?;

        // Create response format with JSON schema (strict mode)
        let response_format = ResponseFormat::json_schema(
            schema_name.clone(),
            schema_json,
            Some("Output in the specified format. Include ALL required fields and follow the schema exactly.".to_string()),
        );

        // Build reasoning_effort for GPT-5.x models
        let is_gpt5 = self.config.model.as_str().starts_with("gpt-5");
        let reasoning_effort = if is_gpt5 {
            self.config
                .thinking_level
                .and_then(|level| level.openai_reasoning_effort().map(|s| s.to_string()))
        } else {
            None
        };

        // GPT-5.x with reasoning requires temperature=1.0
        let effective_temp = if reasoning_effort.is_some() {
            1.0
        } else {
            self.config.temperature
        };

        // Convert ChatMessage to OpenAI's format
        let api_messages = convert_openai_compatible_chat_messages(messages, "OpenAI")
            .map_err(MaterializeAttemptError::preflight)?;

        // Build the request with native structured outputs
        debug!(
            "Building OpenAI API request with structured outputs (history_len={})",
            api_messages.len()
        );
        let request = OpenAICompatibleChatCompletionRequest {
            model: self.config.model.as_str().to_string(),
            messages: api_messages,
            response_format: Some(response_format),
            temperature: effective_temp,
            max_tokens: self.config.max_tokens,
            reasoning_effort,
        };

        // Send the request to OpenAI
        let base_url = self
            .config
            .base_url
            .as_deref()
            .unwrap_or("https://api.openai.com/v1");
        let url = format!("{}/chat/completions", base_url);
        let gen_ai_span = crate::telemetry::inference_span(
            "openai",
            "chat",
            self.config.model.as_str(),
            &url,
            Some(f64::from(effective_temp)),
            self.config.max_tokens.map(u64::from),
        );
        debug!(url = %url, "Sending request to OpenAI API");
        let response = optional_bearer_auth(self.client.post(&url), &self.config.api_key)
            .header("Content-Type", "application/json")
            .json(&request)
            .send()
            .instrument(gen_ai_span.clone())
            .await
            .map_err(|error| {
                crate::telemetry::record_http_client_error(&gen_ai_span, &error);
                materialize_request_error(error, "OpenAI")
            })?;

        // Parse the response
        let response = check_response_status_with_capture(
            response,
            "OpenAI",
            self.config.response_body_capture.as_ref(),
        )
        .await
        .map_err(|error| {
            crate::telemetry::record_error(&gen_ai_span, &error);
            MaterializeAttemptError::transport(error)
        })?;

        debug!("Successfully received response from OpenAI");
        let (completion, response_metadata): (OpenAICompatibleChatCompletionResponse, _) =
            parse_json_response(
                response,
                "OpenAI",
                self.config.response_body_capture.as_ref(),
            )
            .await
            .map_err(|error| {
                crate::telemetry::record_error(&gen_ai_span, &error);
                MaterializeAttemptError::transport(error)
            })?;

        // Extract usage before validating the envelope so protocol failures can
        // still report provider-billed tokens.
        let model_name = completion
            .model
            .clone()
            .unwrap_or_else(|| self.config.model.as_str().to_string());
        let usage = completion
            .usage
            .as_ref()
            .map(|u| u.token_usage(model_name.clone()));

        if completion.choices.is_empty() {
            error!("OpenAI returned empty choices array");
            let error = RStructorError::api_error_with_response(
                "OpenAI",
                ApiErrorKind::UnexpectedResponse {
                    details: "No completion choices returned".to_string(),
                },
                response_metadata.clone(),
            );
            crate::telemetry::record_error(&gen_ai_span, &error);
            return Err(MaterializeAttemptError::transport_with_usage(error, usage)
                .with_response(response_metadata));
        }

        let message = &completion.choices[0].message;
        trace!(finish_reason = %completion.choices[0].finish_reason, "Completion finish reason");

        // With structured outputs, the response is in message.content as guaranteed-valid JSON
        if let Some(content) = &message.content {
            crate::telemetry::record_success(
                &gen_ai_span,
                completion.id.as_deref(),
                Some(&model_name),
                usage.as_ref(),
            );
            let raw_response = content.clone();
            debug!(
                content_len = raw_response.len(),
                "Structured output received from OpenAI"
            );

            // Parse and validate the response using shared utility
            parse_validate_and_create_output(raw_response, usage)
                .map(|output| output.with_response(response_metadata.clone()))
                .map_err(|error| error.with_response(response_metadata))
        } else {
            error!("No content in OpenAI response");
            let error = RStructorError::api_error_with_response(
                "OpenAI",
                ApiErrorKind::UnexpectedResponse {
                    details: "No content in response".to_string(),
                },
                response_metadata.clone(),
            );
            crate::telemetry::record_error(&gen_ai_span, &error);
            Err(MaterializeAttemptError::transport_with_usage(error, usage)
                .with_response(response_metadata))
        }
    }

    /// Internal implementation of raw text generation (no structured output).
    ///
    /// Accepts chat messages so that callers can attach media (images/PDFs) to
    /// the user message; the same content-building path as `materialize_internal`
    /// is used, so media is encoded per OpenAI's documented multimodal format.
    async fn generate_internal(&self, messages: &[ChatMessage]) -> Result<GenerateResult> {
        info!("Generating raw text response with OpenAI");

        // Build reasoning_effort for GPT-5.x models
        let is_gpt5 = self.config.model.as_str().starts_with("gpt-5");
        let reasoning_effort = if is_gpt5 {
            self.config
                .thinking_level
                .and_then(|level| level.openai_reasoning_effort().map(|s| s.to_string()))
        } else {
            None
        };

        // GPT-5.x with reasoning requires temperature=1.0
        let effective_temp = if reasoning_effort.is_some() {
            1.0
        } else {
            self.config.temperature
        };

        // Build the request for text generation (no structured output)
        debug!("Building OpenAI API request for text generation");
        let request = OpenAICompatibleChatCompletionRequest {
            model: self.config.model.as_str().to_string(),
            messages: convert_openai_compatible_chat_messages(messages, "OpenAI")?,
            response_format: None,
            temperature: effective_temp,
            max_tokens: self.config.max_tokens,
            reasoning_effort,
        };

        // Send the request to OpenAI
        let base_url = self
            .config
            .base_url
            .as_deref()
            .unwrap_or("https://api.openai.com/v1");
        let url = format!("{}/chat/completions", base_url);
        let gen_ai_span = crate::telemetry::inference_span(
            "openai",
            "chat",
            self.config.model.as_str(),
            &url,
            Some(f64::from(effective_temp)),
            self.config.max_tokens.map(u64::from),
        );
        debug!(url = %url, "Sending request to OpenAI API");
        let response = optional_bearer_auth(self.client.post(&url), &self.config.api_key)
            .header("Content-Type", "application/json")
            .json(&request)
            .send()
            .instrument(gen_ai_span.clone())
            .await
            .map_err(|error| {
                crate::telemetry::record_http_client_error(&gen_ai_span, &error);
                handle_http_error(error, "OpenAI")
            })?;

        // Parse the response
        let response = check_response_status_with_capture(
            response,
            "OpenAI",
            self.config.response_body_capture.as_ref(),
        )
        .await
        .inspect_err(|error| crate::telemetry::record_error(&gen_ai_span, error))?;

        debug!("Successfully received response from OpenAI");
        let (completion, response_metadata): (OpenAICompatibleChatCompletionResponse, _) =
            parse_json_response(
                response,
                "OpenAI",
                self.config.response_body_capture.as_ref(),
            )
            .await
            .inspect_err(|error| crate::telemetry::record_error(&gen_ai_span, error))?;

        if completion.choices.is_empty() {
            error!("OpenAI returned empty choices array");
            let error = RStructorError::api_error_with_response(
                "OpenAI",
                ApiErrorKind::UnexpectedResponse {
                    details: "No completion choices returned".to_string(),
                },
                response_metadata,
            );
            crate::telemetry::record_error(&gen_ai_span, &error);
            return Err(error);
        }

        // Extract usage info
        let model_name = completion
            .model
            .clone()
            .unwrap_or_else(|| self.config.model.as_str().to_string());
        let usage = completion
            .usage
            .as_ref()
            .map(|u| u.token_usage(model_name.clone()));

        let message = &completion.choices[0].message;
        trace!(finish_reason = %completion.choices[0].finish_reason, "Completion finish reason");

        if let Some(content) = &message.content {
            crate::telemetry::record_success(
                &gen_ai_span,
                completion.id.as_deref(),
                Some(&model_name),
                usage.as_ref(),
            );
            debug!(
                content_len = content.len(),
                "Successfully extracted content from response"
            );
            Ok(GenerateResult::new(content.clone(), usage))
        } else {
            error!("No content in OpenAI response");
            let error = RStructorError::api_error_with_response(
                "OpenAI",
                ApiErrorKind::UnexpectedResponse {
                    details: "No content in response".to_string(),
                },
                response_metadata,
            );
            crate::telemetry::record_error(&gen_ai_span, &error);
            Err(error)
        }
    }
}

#[cfg(feature = "streaming")]
impl OpenAIClient {
    /// Build the JSON request body for a streaming call (`stream: true`),
    /// optionally with a structured-output `response_format`.
    fn stream_body(
        &self,
        system: Option<&str>,
        prompt: &str,
        response_format: Option<ResponseFormat>,
    ) -> serde_json::Value {
        let is_gpt5 = self.config.model.as_str().starts_with("gpt-5");
        let reasoning_effort = if is_gpt5 {
            self.config
                .thinking_level
                .and_then(|level| level.openai_reasoning_effort().map(|s| s.to_string()))
        } else {
            None
        };
        let effective_temp = if reasoning_effort.is_some() {
            1.0
        } else {
            self.config.temperature
        };
        let mut messages = Vec::with_capacity(usize::from(system.is_some()) + 1);
        if let Some(system) = system {
            messages.push(OpenAICompatibleChatMessage {
                role: "system".to_string(),
                content: OpenAICompatibleMessageContent::Text(system.to_string()),
            });
        }
        messages.push(OpenAICompatibleChatMessage {
            role: "user".to_string(),
            content: OpenAICompatibleMessageContent::Text(prompt.to_string()),
        });
        let request = OpenAICompatibleChatCompletionRequest {
            model: self.config.model.as_str().to_string(),
            messages,
            response_format,
            temperature: effective_temp,
            max_tokens: self.config.max_tokens,
            reasoning_effort,
        };
        let mut body = serde_json::to_value(&request).unwrap_or_else(|_| serde_json::json!({}));
        body["stream"] = serde_json::Value::Bool(true);
        body
    }

    /// Send a streaming request and return the raw SSE response.
    fn send_stream(
        &self,
        body: serde_json::Value,
    ) -> impl std::future::Future<Output = Result<reqwest::Response>> + Send + 'static {
        let client = self.client.clone();
        let api_key = self.config.api_key.clone();
        let response_body_capture = self.config.response_body_capture.clone();
        let base_url = self
            .config
            .base_url
            .clone()
            .unwrap_or_else(|| "https://api.openai.com/v1".to_string());
        async move {
            let url = format!("{}/chat/completions", base_url);
            let resp = optional_bearer_auth(client.post(&url), &api_key)
                .header("Content-Type", "application/json")
                .json(&body)
                .send()
                .await
                .map_err(|e| handle_http_error(e, "OpenAI"))?;
            check_response_status_with_capture(resp, "OpenAI", response_body_capture.as_ref()).await
        }
    }
}

#[cfg(feature = "tools")]
fn tool_reasoning_effort(model: &str) -> Option<String> {
    model.starts_with("gpt-5.6").then(|| "none".to_string())
}

#[cfg(feature = "tools")]
#[async_trait]
impl crate::backend::tools::ToolRunner for OpenAIClient {
    async fn run_tool_loop(
        &self,
        system: Option<&str>,
        prompt: &str,
        media: &[super::MediaFile],
        toolbox: &crate::backend::tools::Toolbox,
        max_iterations: usize,
    ) -> Result<String> {
        let base_url = self
            .config
            .base_url
            .as_deref()
            .unwrap_or("https://api.openai.com/v1");
        let url = format!("{}/chat/completions", base_url);

        // GPT-5.x models require temperature=1.0. GPT-5.6 defaults to medium
        // reasoning, but Chat Completions function tools require effective
        // reasoning `none`, so make that override explicit for the 5.6 family.
        let is_gpt5 = self.config.model.as_str().starts_with("gpt-5");
        let effective_temp = if is_gpt5 {
            1.0
        } else {
            self.config.temperature
        };
        let reasoning_effort = tool_reasoning_effort(self.config.model.as_str());

        crate::backend::tools::run_openai_compatible_tools(
            &self.client,
            &url,
            &self.config.api_key,
            "OpenAI",
            self.config.model.as_str(),
            effective_temp,
            self.config.max_tokens,
            reasoning_effort,
            system,
            prompt,
            media,
            toolbox,
            max_iterations,
        )
        .await
    }
}

#[async_trait]
impl LLMClient for OpenAIClient {
    fn from_env() -> Result<Self> {
        Self::from_env()
    }

    #[instrument(
        name = "openai_materialize",
        skip(self, prompt),
        fields(
            type_name = std::any::type_name::<T>(),
            model = %self.config.model.as_str(),
            prompt_len = prompt.len()
        )
    )]
    async fn materialize<T>(&self, prompt: &str) -> Result<T>
    where
        T: Instructor + DeserializeOwned + Send + 'static,
    {
        let output = generate_with_retry_with_history(
            |messages: Vec<ChatMessage>| {
                let this = self;
                async move { this.materialize_internal::<T>(&messages).await }
            },
            prompt,
            self.config.max_retries,
        )
        .await?;
        Ok(output.data)
    }

    #[instrument(
        name = "openai_materialize_with_media",
        skip(self, prompt, media),
        fields(
            type_name = std::any::type_name::<T>(),
            model = %self.config.model.as_str(),
            prompt_len = prompt.len(),
            media_len = media.len()
        )
    )]
    async fn materialize_with_media<T>(&self, prompt: &str, media: &[super::MediaFile]) -> Result<T>
    where
        T: Instructor + DeserializeOwned + Send + 'static,
    {
        materialize_with_media_with_retry(
            |messages: Vec<ChatMessage>| {
                let this = self;
                async move { this.materialize_internal::<T>(&messages).await }
            },
            prompt,
            media,
            self.config.max_retries,
        )
        .await
    }

    #[instrument(
        name = "openai_materialize_with_metadata",
        skip(self, prompt),
        fields(
            type_name = std::any::type_name::<T>(),
            model = %self.config.model.as_str(),
            prompt_len = prompt.len()
        )
    )]
    async fn materialize_with_metadata<T>(&self, prompt: &str) -> Result<MaterializeResult<T>>
    where
        T: Instructor + DeserializeOwned + Send + 'static,
    {
        let output = generate_with_retry_with_history(
            |messages: Vec<ChatMessage>| {
                let this = self;
                async move { this.materialize_internal::<T>(&messages).await }
            },
            prompt,
            self.config.max_retries,
        )
        .await?;
        Ok(MaterializeResult::new(output.data, output.usage))
    }

    #[instrument(
        name = "openai_materialize_with_attempts",
        skip(self, prompt),
        fields(
            type_name = std::any::type_name::<T>(),
            model = %self.config.model.as_str(),
            prompt_len = prompt.len()
        )
    )]
    async fn materialize_with_attempts<T>(
        &self,
        prompt: &str,
    ) -> std::result::Result<MaterializeReport<T>, MaterializeFailure>
    where
        T: Instructor + DeserializeOwned + Send + 'static,
    {
        generate_with_retry_attempts_with_history(
            |messages: Vec<ChatMessage>| {
                let this = self;
                async move { this.materialize_internal::<T>(&messages).await }
            },
            prompt,
            self.config.max_retries,
        )
        .await
    }

    #[instrument(
        name = "openai_materialize_with_media_and_attempts",
        skip(self, prompt, media),
        fields(
            type_name = std::any::type_name::<T>(),
            model = %self.config.model.as_str(),
            prompt_len = prompt.len(),
            media_len = media.len()
        )
    )]
    async fn materialize_with_media_and_attempts<T>(
        &self,
        prompt: &str,
        media: &[super::MediaFile],
    ) -> std::result::Result<MaterializeReport<T>, MaterializeFailure>
    where
        T: Instructor + DeserializeOwned + Send + 'static,
    {
        materialize_with_media_and_attempts_with_retry(
            |messages: Vec<ChatMessage>| {
                let this = self;
                async move { this.materialize_internal::<T>(&messages).await }
            },
            prompt,
            media,
            self.config.max_retries,
        )
        .await
    }

    async fn materialize_request<T>(
        &self,
        system: Option<&str>,
        prompt: &str,
        media: &[super::MediaFile],
    ) -> Result<T>
    where
        T: Instructor + DeserializeOwned + Send + 'static,
    {
        let output = generate_with_retry_with_initial_messages(
            |messages: Vec<ChatMessage>| {
                let this = self;
                async move { this.materialize_internal::<T>(&messages).await }
            },
            request_messages(system, prompt, media),
            self.config.max_retries,
        )
        .await?;
        Ok(output.data)
    }

    async fn materialize_request_with_attempts<T>(
        &self,
        system: Option<&str>,
        prompt: &str,
        media: &[super::MediaFile],
    ) -> std::result::Result<MaterializeReport<T>, MaterializeFailure>
    where
        T: Instructor + DeserializeOwned + Send + 'static,
    {
        generate_with_retry_attempts_with_initial_messages(
            |messages: Vec<ChatMessage>| {
                let this = self;
                async move { this.materialize_internal::<T>(&messages).await }
            },
            request_messages(system, prompt, media),
            self.config.max_retries,
        )
        .await
    }

    #[instrument(
        name = "openai_generate",
        skip(self, prompt),
        fields(
            model = %self.config.model.as_str(),
            prompt_len = prompt.len()
        )
    )]
    async fn generate(&self, prompt: &str) -> Result<String> {
        let result = self.generate_with_metadata(prompt).await?;
        Ok(result.text)
    }

    #[instrument(
        name = "openai_generate_with_media",
        skip(self, prompt, media),
        fields(
            model = %self.config.model.as_str(),
            prompt_len = prompt.len(),
            media_len = media.len()
        )
    )]
    async fn generate_with_media(
        &self,
        prompt: &str,
        media: &[super::MediaFile],
    ) -> Result<String> {
        let result = self
            .generate_internal(&[ChatMessage::user_with_media(prompt, media.to_vec())])
            .await?;
        Ok(result.text)
    }

    #[instrument(
        name = "openai_generate_with_metadata",
        skip(self, prompt),
        fields(
            model = %self.config.model.as_str(),
            prompt_len = prompt.len()
        )
    )]
    async fn generate_with_metadata(&self, prompt: &str) -> Result<GenerateResult> {
        self.generate_internal(&[ChatMessage::user(prompt)]).await
    }

    async fn generate_request(
        &self,
        system: Option<&str>,
        prompt: &str,
        media: &[super::MediaFile],
    ) -> Result<String> {
        let result = self
            .generate_internal(&request_messages(system, prompt, media))
            .await?;
        Ok(result.text)
    }

    #[cfg(feature = "streaming")]
    fn generate_stream<'a>(&'a self, prompt: &'a str) -> crate::backend::streaming::TextStream<'a>
    where
        Self: Sync,
    {
        self.generate_stream_request(None, prompt.to_string())
    }

    #[cfg(feature = "streaming")]
    fn generate_stream_request<'a>(
        &'a self,
        system: Option<String>,
        prompt: String,
    ) -> crate::backend::streaming::TextStream<'a>
    where
        Self: Sync,
    {
        let body = self.stream_body(system.as_deref(), &prompt, None);
        crate::backend::streaming::sse_text_stream(
            self.send_stream(body),
            crate::backend::streaming::openai_stream_event,
            crate::backend::streaming::TerminalMarker::DoneSentinel,
        )
    }

    #[cfg(feature = "streaming")]
    fn materialize_stream<'a, T>(
        &'a self,
        prompt: &'a str,
    ) -> crate::backend::streaming::ObjectStream<'a, T>
    where
        T: Instructor + DeserializeOwned + Send + 'static,
        Self: Sync,
    {
        self.materialize_stream_request(None, prompt.to_string())
    }

    #[cfg(feature = "streaming")]
    fn materialize_stream_request<'a, T>(
        &'a self,
        system: Option<String>,
        prompt: String,
    ) -> crate::backend::streaming::ObjectStream<'a, T>
    where
        T: Instructor + DeserializeOwned + Send + 'static,
        Self: Sync,
    {
        let schema = match T::try_schema() {
            Ok(schema) => schema,
            Err(error) => return crate::backend::streaming::error_stream(error),
        };
        let schema_name = T::schema_name().unwrap_or_else(|| "output".to_string());
        let schema_json = match compile_strict_schema(
            &schema,
            StrictSchemaProvider::OpenAI,
            "streamed structured output",
        ) {
            Ok(schema) => schema,
            Err(error) => return crate::backend::streaming::error_stream(error),
        };
        let response_format = ResponseFormat::json_schema(
            schema_name,
            schema_json,
            Some("Output in the specified format. Include ALL required fields and follow the schema exactly.".to_string()),
        );
        let body = self.stream_body(system.as_deref(), &prompt, Some(response_format));
        crate::backend::streaming::object_stream(
            self.send_stream(body),
            crate::backend::streaming::openai_stream_event,
            crate::backend::streaming::TerminalMarker::DoneSentinel,
        )
    }

    #[cfg(feature = "streaming")]
    fn materialize_iter<'a, T>(
        &'a self,
        prompt: &'a str,
    ) -> crate::backend::streaming::ItemStream<'a, T>
    where
        T: Instructor + DeserializeOwned + Send + 'static,
        Self: Sync,
    {
        self.materialize_iter_request(None, prompt.to_string())
    }

    #[cfg(feature = "streaming")]
    fn materialize_iter_request<'a, T>(
        &'a self,
        system: Option<String>,
        prompt: String,
    ) -> crate::backend::streaming::ItemStream<'a, T>
    where
        T: Instructor + DeserializeOwned + Send + 'static,
        Self: Sync,
    {
        let schema = match T::try_schema() {
            Ok(schema) => schema,
            Err(error) => return crate::backend::streaming::error_stream(error),
        };
        let item_schema =
            match compile_strict_schema(&schema, StrictSchemaProvider::OpenAI, "streamed item") {
                Ok(schema) => schema,
                Err(error) => return crate::backend::streaming::error_stream(error),
            };
        let wrapper = crate::backend::streaming::array_wrapper_schema(item_schema, true);
        let response_format = ResponseFormat::json_schema(
            "items".to_string(),
            wrapper,
            Some("Return a JSON object with an `items` array; each element must follow the item schema exactly.".to_string()),
        );
        let body = self.stream_body(system.as_deref(), &prompt, Some(response_format));
        crate::backend::streaming::iter_stream(
            self.send_stream(body),
            crate::backend::streaming::openai_stream_event,
            crate::backend::streaming::TerminalMarker::DoneSentinel,
            crate::backend::streaming::finalize_item::<T>,
        )
    }

    /// Fetch available models from OpenAI's API.
    ///
    /// Returns a list of GPT models available for chat completions.
    /// Filters out embedding, whisper, and other non-chat models.
    async fn list_models(&self) -> Result<Vec<ModelInfo>> {
        let base_url = self
            .config
            .base_url
            .as_deref()
            .unwrap_or("https://api.openai.com/v1");
        let url = format!("{}/models", base_url);

        debug!(url = %url, "Fetching available models from OpenAI");

        let response = optional_bearer_auth(self.client.get(&url), &self.config.api_key)
            .header("Content-Type", "application/json")
            .send()
            .await
            .map_err(|e| handle_http_error(e, "OpenAI"))?;

        let response = check_response_status_with_capture(
            response,
            "OpenAI",
            self.config.response_body_capture.as_ref(),
        )
        .await?;

        let json: serde_json::Value = response.json().await.map_err(|e| {
            error!(error = %e, "Failed to parse models response from OpenAI");
            e
        })?;

        let models = json
            .get("data")
            .and_then(|data| data.as_array())
            .map(|models_array| {
                models_array
                    .iter()
                    .filter_map(|model| {
                        let id = model.get("id").and_then(|id| id.as_str())?;
                        // Filter to only GPT models (chat completion models).
                        // The legacy o-series reasoning models are deliberately
                        // excluded: they reject the request parameters this
                        // client sends (`temperature`, `max_tokens`).
                        if id.starts_with("gpt-") {
                            Some(ModelInfo {
                                id: id.to_string(),
                                name: None,
                                description: None,
                            })
                        } else {
                            None
                        }
                    })
                    .collect::<Vec<_>>()
            })
            .unwrap_or_default();

        debug!(count = models.len(), "Fetched OpenAI models");
        Ok(models)
    }
}

fn optional_bearer_auth(
    request: reqwest::RequestBuilder,
    api_key: &str,
) -> reqwest::RequestBuilder {
    if api_key.is_empty() {
        request
    } else {
        request.bearer_auth(api_key)
    }
}

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

    #[test]
    fn default_config_has_default_timeout() {
        let client = OpenAIClient::new("test-key").unwrap();
        assert_eq!(client.config.timeout, Some(DEFAULT_REQUEST_TIMEOUT));
    }

    #[test]
    fn default_config_uses_latest_model() {
        let client = OpenAIClient::new("test-key").unwrap();
        assert_eq!(client.config.model, Model::Gpt56Sol);
    }

    #[test]
    fn explicit_timeout_overrides_default() {
        let client = OpenAIClient::new("test-key")
            .unwrap()
            .timeout(Duration::from_secs(10));
        assert_eq!(client.config.timeout, Some(Duration::from_secs(10)));
    }

    #[test]
    fn local_constructors_are_keyless_and_use_official_base_urls() {
        let ollama = OpenAIClient::ollama().unwrap();
        assert_eq!(ollama.config.base_url.as_deref(), Some(OLLAMA_BASE_URL));
        assert!(ollama.config.api_key.is_empty());

        let lm_studio = OpenAIClient::lm_studio().unwrap();
        assert_eq!(
            lm_studio.config.base_url.as_deref(),
            Some(LM_STUDIO_BASE_URL)
        );
        assert!(lm_studio.config.api_key.is_empty());
    }

    #[cfg(feature = "tools")]
    #[test]
    fn gpt56_tool_calls_explicitly_disable_reasoning() {
        for model in ["gpt-5.6", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna"] {
            assert_eq!(tool_reasoning_effort(model), Some("none".to_string()));
        }
        assert_eq!(tool_reasoning_effort("gpt-5.5"), None);
        assert_eq!(tool_reasoning_effort("gpt-4.1-mini"), None);
    }
}