xai-openapi 0.1.1

//! Tool and function call types for xAI API.

use serde::{Deserialize, Serialize};

use crate::prelude::*;

use crate::common::Annotation;

/// Definition of one tool that the model can call.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum Tool {
    /// A function tool that the model can call.
    Function {
        /// Definition of tool call available to the model.
        function: FunctionDefinition,
    },
    /// Live search tool.
    LiveSearch {
        /// Search sources.
        sources: Vec<crate::search::SearchSource>,
    },
}

impl Default for Tool {
    fn default() -> Self {
        Tool::Function {
            function: FunctionDefinition::default(),
        }
    }
}

/// Definition of the tool call made available to the model.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct FunctionDefinition {
    /// The name of the function.
    pub name: String,

    /// A JSON schema describing the function parameters.
    pub parameters: serde_json::Value,

    /// A description of the function to indicate to the model when to call it.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,

    /// Not supported. Only maintained for compatibility reasons.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub strict: Option<bool>,
}

/// A tool call made by the model.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct ToolCall {
    /// A unique ID of the tool call generated by xAI.
    pub id: String,

    /// Function to call for the tool call.
    pub function: Function,

    /// Index of the tool call.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub index: Option<i32>,

    /// Type of tool call.
    #[serde(rename = "type", skip_serializing_if = "Option::is_none")]
    pub tool_type: Option<String>,
}

/// Function call details.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct Function {
    /// Name of the function.
    pub name: String,

    /// Arguments available to the function.
    pub arguments: String,
}

/// Function name for tool choice.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct FunctionChoice {
    /// Name of the function.
    pub name: String,
}

/// Parameter to control how model chooses the tools.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(untagged)]
pub enum ToolChoice {
    /// Controls tool access by the model.
    /// `"none"` makes model ignore tools, `"auto"` lets the model automatically decide,
    /// `"required"` forces model to pick a tool to call.
    Mode(String),
    /// Specific function to use.
    Specific {
        /// Type is always `"function"`.
        #[serde(rename = "type")]
        tool_type: String,
        /// Name of the function to use.
        #[serde(skip_serializing_if = "Option::is_none")]
        function: Option<FunctionChoice>,
    },
}

impl Default for ToolChoice {
    fn default() -> Self {
        ToolChoice::Mode("auto".to_string())
    }
}

/// A tool call to run a function (for Responses API).
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct FunctionToolCall {
    /// The type of the function tool call.
    #[serde(rename = "type")]
    pub call_type: String,

    /// The unique ID of the function tool call generated by the model.
    pub call_id: String,

    /// The name of the function.
    pub name: String,

    /// The arguments to pass to the function, as a JSON string.
    pub arguments: String,

    /// The unique ID of the function tool call.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub id: Option<String>,

    /// Status of the item. One of `completed`, `in_progress` or `incomplete`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub status: Option<String>,
}

/// The output of a function tool call.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct FunctionToolCallOutput {
    /// The type of the function tool call, which is always `function_call_output`.
    #[serde(rename = "type")]
    pub output_type: String,

    /// The unique ID of the function tool call generated by the model.
    pub call_id: String,

    /// The output of the function tool call, as a JSON string.
    pub output: String,
}

/// The output of a web search tool call.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct WebSearchCall {
    /// The type of the web search tool call. Always `web_search_call`.
    #[serde(rename = "type")]
    pub call_type: String,

    /// An object describing the specific action taken in this web search call.
    pub action: WebSearchAction,

    /// The unique ID of the web search tool call.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub id: Option<String>,

    /// The status of the web search tool call.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub status: Option<String>,
}

/// Web search action.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum WebSearchAction {
    /// Action type "search" - Performs a web search query.
    Search {
        /// The search query.
        query: String,
        /// The sources used in the search.
        #[serde(skip_serializing_if = "Option::is_none")]
        sources: Option<Vec<WebSearchSource>>,
    },
    /// Action type `open_page` - Opens a specific URL from search results.
    OpenPage {
        /// The URL of the page to open.
        url: String,
    },
    /// Action type "find" - Searches for a pattern within a loaded page.
    Find {
        /// The source of the page to search in.
        source: WebSearchSource,
        /// The pattern or text to search for within the page.
        pattern: String,
    },
}

impl Default for WebSearchAction {
    fn default() -> Self {
        WebSearchAction::Search {
            query: String::new(),
            sources: None,
        }
    }
}

/// Web search source.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct WebSearchSource {
    /// The type of source.
    #[serde(rename = "type")]
    pub source_type: String,

    /// The URL of the source.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub url: Option<String>,
}

/// Web search options.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct WebSearchOptions {
    /// This field included for compatibility reason with `OpenAI`'s API.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub search_context_size: Option<String>,

    /// Only included for compatibility.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub filters: Option<serde_json::Value>,

    /// Only included for compatibility.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub user_location: Option<serde_json::Value>,
}

/// Web search filters.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct WebSearchFilters {
    /// List of website domains to restrict search results to.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub allowed_domains: Option<Vec<String>>,

    /// List of website domains to exclude from search results.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub excluded_domains: Option<Vec<String>>,
}

/// The output of a file search tool call.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct FileSearchCall {
    /// The type of the file search tool call. Always `file_search_call`.
    #[serde(rename = "type")]
    pub call_type: String,

    /// The queries used to search for files.
    pub queries: Vec<String>,

    /// The results of the file search tool call.
    pub results: Vec<FileSearchResult>,

    /// The unique ID of the file search tool call.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub id: Option<String>,

    /// The status of the file search tool call.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub status: Option<String>,
}

/// A file search result.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct FileSearchResult {
    /// The file ID of the file search result.
    pub file_id: String,

    /// The filename of the file search result.
    pub filename: String,

    /// The score of the file search result.
    pub score: f64,

    /// The text of the file search result.
    pub text: String,
}

/// The output of a code interpreter tool call.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct CodeInterpreterCall {
    /// The type of the code interpreter tool call. Always `code_interpreter_call`.
    #[serde(rename = "type")]
    pub call_type: String,

    /// The outputs of the code interpreter tool call.
    pub outputs: Vec<CodeInterpreterOutput>,

    /// The code of the code interpreter tool call.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub code: Option<String>,

    /// The unique ID of the code interpreter tool call.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub id: Option<String>,

    /// The status of the code interpreter tool call.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub status: Option<String>,
}

/// Output of a code interpreter tool call.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum CodeInterpreterOutput {
    /// Log output from code interpreter.
    Logs {
        /// The output of the code interpreter tool call.
        logs: String,
    },
    /// Image output from code interpreter.
    Image {
        /// The URL of the generated image.
        url: String,
    },
}

impl Default for CodeInterpreterOutput {
    fn default() -> Self {
        CodeInterpreterOutput::Logs {
            logs: String::new(),
        }
    }
}

/// The output of a MCP tool call.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct McpCall {
    /// The type of the MCP tool call. Always `mcp_call`.
    #[serde(rename = "type")]
    pub call_type: String,

    /// The name of the tool that was run.
    pub name: String,

    /// The label of the MCP server running the tool.
    pub server_label: String,

    /// A JSON string of the arguments passed to the tool.
    pub arguments: String,

    /// The output of the MCP tool call.
    pub output: String,

    /// The unique ID of the MCP tool call.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub id: Option<String>,

    /// The error message of the MCP tool call.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub error: Option<String>,

    /// The status of the MCP tool call.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub status: Option<String>,
}

/// The output of a custom tool call.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct CustomToolCall {
    /// The type of the custom tool call.
    #[serde(rename = "type")]
    pub call_type: String,

    /// The unique ID of the function tool call generated by the model.
    pub call_id: String,

    /// An identifier used to map this custom tool call to a tool call output.
    pub name: String,

    /// The status of the custom tool call.
    pub id: String,

    /// The unique ID of the custom tool call.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub input: Option<String>,

    /// Status of the item. One of `completed`, `in_progress` or `incomplete`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub status: Option<String>,
}

/// Definition of one tool that the model can call (for Responses API).
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum ModelTool {
    /// A function that the model can call.
    Function {
        /// The name of the function.
        name: String,
        /// A JSON schema describing the function parameters.
        parameters: serde_json::Value,
        /// A description of the function.
        #[serde(skip_serializing_if = "Option::is_none")]
        description: Option<String>,
        /// Not supported. Only maintained for compatibility reasons.
        #[serde(skip_serializing_if = "Option::is_none")]
        strict: Option<bool>,
    },
    /// Search the web.
    WebSearch {
        /// List of website domains to allow in the search results.
        #[serde(skip_serializing_if = "Option::is_none")]
        allowed_domains: Option<Vec<String>>,
        /// List of website domains to exclude from the search results.
        #[serde(skip_serializing_if = "Option::is_none")]
        excluded_domains: Option<Vec<String>>,
        /// Enable image understanding during web search.
        #[serde(skip_serializing_if = "Option::is_none")]
        enable_image_understanding: Option<bool>,
        /// Control whether the web search tool fetches live content or uses only cached content.
        #[serde(skip_serializing_if = "Option::is_none")]
        external_web_access: Option<bool>,
        /// Filters to apply to the search results.
        #[serde(skip_serializing_if = "Option::is_none")]
        filters: Option<WebSearchFilters>,
        /// High level guidance for the amount of context window space to use.
        #[serde(skip_serializing_if = "Option::is_none")]
        search_context_size: Option<String>,
        /// The user location to use for the search.
        #[serde(skip_serializing_if = "Option::is_none")]
        user_location: Option<serde_json::Value>,
    },
    /// Search X.
    XSearch {
        /// List of X Handles of the users from whom to consider the posts.
        #[serde(skip_serializing_if = "Option::is_none")]
        allowed_x_handles: Option<Vec<String>>,
        /// List of X Handles of the users from whom to exclude the posts.
        #[serde(skip_serializing_if = "Option::is_none")]
        excluded_x_handles: Option<Vec<String>>,
        /// Enable image understanding during X search.
        #[serde(skip_serializing_if = "Option::is_none")]
        enable_image_understanding: Option<bool>,
        /// Enable video understanding during X search.
        #[serde(skip_serializing_if = "Option::is_none")]
        enable_video_understanding: Option<bool>,
        /// Date from which to consider the results.
        #[serde(skip_serializing_if = "Option::is_none")]
        from_date: Option<String>,
        /// Date up to which to consider the results.
        #[serde(skip_serializing_if = "Option::is_none")]
        to_date: Option<String>,
    },
    /// Search the knowledge bases.
    FileSearch {
        /// List of vector store IDs to search within.
        vector_store_ids: Vec<String>,
        /// Maximum number of results.
        #[serde(skip_serializing_if = "Option::is_none")]
        max_num_results: Option<i32>,
        /// A filter to apply.
        #[serde(skip_serializing_if = "Option::is_none")]
        filters: Option<serde_json::Value>,
        /// Ranking options for search.
        #[serde(skip_serializing_if = "Option::is_none")]
        ranking_options: Option<serde_json::Value>,
    },
    /// Execute code.
    CodeInterpreter {
        /// The code interpreter container.
        #[serde(skip_serializing_if = "Option::is_none")]
        container: Option<serde_json::Value>,
    },
    /// A remote MCP server to use.
    Mcp {
        /// The label of the MCP server.
        server_label: String,
        /// The URL of the MCP server.
        server_url: String,
        /// Allowed tools.
        #[serde(skip_serializing_if = "Option::is_none")]
        allowed_tools: Option<Vec<String>>,
        /// Authorization token.
        #[serde(skip_serializing_if = "Option::is_none")]
        authorization: Option<String>,
        /// Connector ID.
        #[serde(skip_serializing_if = "Option::is_none")]
        connector_id: Option<String>,
        /// Additional headers.
        #[serde(skip_serializing_if = "Option::is_none")]
        headers: Option<HashMap<String, String>>,
        /// Whether to require approval.
        #[serde(skip_serializing_if = "Option::is_none")]
        require_approval: Option<String>,
        /// Server description.
        #[serde(skip_serializing_if = "Option::is_none")]
        server_description: Option<String>,
    },
}

impl Default for ModelTool {
    fn default() -> Self {
        ModelTool::Function {
            name: String::new(),
            parameters: serde_json::Value::Null,
            description: None,
            strict: None,
        }
    }
}

/// Parameter to control how model chooses the tools (for Responses API).
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(untagged)]
pub enum ModelToolChoice {
    /// Controls tool access by the model.
    Mode(String),
    /// Specific function to use.
    Specific {
        /// Type is always `"function"`.
        #[serde(rename = "type")]
        tool_type: String,
        /// Name of the function to use.
        name: String,
    },
}

impl Default for ModelToolChoice {
    fn default() -> Self {
        ModelToolChoice::Mode("auto".to_string())
    }
}

/// Text output from the model.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct OutputText {
    /// The type of the output. Always `output_text`.
    #[serde(rename = "type")]
    pub output_type: String,

    /// The text output from the model.
    pub text: String,

    /// Citations.
    pub annotations: Vec<Annotation>,

    /// The log probabilities of each output token returned.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub logprobs: Option<Vec<crate::chat::TokenLogProb>>,
}

/// Refusal output from the model.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct OutputRefusal {
    /// The type of the output. Always `refusal`.
    #[serde(rename = "type")]
    pub output_type: String,

    /// The reason for the refusal.
    pub refusal: String,
}

/// Output message content.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum OutputMessageContent {
    /// Text output.
    OutputText {
        /// The text output from the model.
        text: String,
        /// Citations.
        annotations: Vec<Annotation>,
        /// The log probabilities of each output token.
        #[serde(skip_serializing_if = "Option::is_none")]
        logprobs: Option<Vec<crate::chat::TokenLogProb>>,
    },
    /// Refusal output.
    Refusal {
        /// The reason for the refusal.
        refusal: String,
    },
}

impl Default for OutputMessageContent {
    fn default() -> Self {
        OutputMessageContent::OutputText {
            text: String::new(),
            annotations: Vec::new(),
            logprobs: None,
        }
    }
}