api_openai 0.3.0

// src/components/chat_shared.rs
//! This module defines shared data structures and components used across various `OpenAI` chat-related API endpoints.
//! It includes definitions for chat completion requests, messages, content parts, and tool-related structures.
//!
//! For more details, refer to the [`OpenAI` Chat API documentation](https://platform.openai.com/docs/api-reference/chat).

/// Define a private namespace for all its items.
mod private
{
  // Serde imports
  use serde::{ Serialize, Deserialize };
  use serde_json::Value;
  use former::Former;
  use crate::components::tools::FunctionTool;

  /// Represents a message in a chat completion request.
  ///
  /// # Used By
  /// - `ChatCompletionRequest`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq, Former ) ]
  pub struct ChatCompletionRequestMessage
  {
    /// The role of the message's author.
    pub role : String,
    /// The content of the message.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub content : Option< ChatCompletionRequestMessageContent >,
    /// The name of the author of this message.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub name : Option< String >,
    /// The tool calls generated by the model, if applicable.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub tool_calls : Option< Vec< ChatCompletionMessageToolCall > >,
    /// Tool call ID that this message is responding to.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub tool_call_id : Option< String >,
  }

  /// Represents the content of a message in a chat completion request.
  /// Can be a simple string or a list of content parts (for multimodal input).
  ///
  /// # Used By
  /// - `ChatCompletionRequestMessage`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  #[ serde( untagged ) ]
  pub enum ChatCompletionRequestMessageContent
  {
    /// A single string content.
    Text( String ),
    /// A list of content parts for multimodal input.
    Parts( Vec< ChatCompletionRequestMessageContentPart > ),
  }

  /// Represents a part of the content in a chat completion request message.
  /// Can be text or an image URL.
  ///
  /// # Used By
  /// - `ChatCompletionRequestMessageContent`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  #[ serde( tag = "type" ) ]
  pub enum ChatCompletionRequestMessageContentPart
  {
    /// Text content.
    #[ serde( rename = "text" ) ]
    Text
    {
      /// The text content.
      text : String
    },
    /// Image URL content.
    #[ serde( rename = "image_url" ) ]
    ImageUrl
    {
      /// The image URL content.
      image_url : ChatCompletionRequestMessageContentImageUrl
    },
  }

  /// Represents an image URL in a chat completion request message content part.
  ///
  /// # Used By
  /// - `ChatCompletionRequestMessageContentPart::ImageUrl`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq, Former ) ]
  pub struct ChatCompletionRequestMessageContentImageUrl
  {
    /// The URL of the image.
    pub url : String,
    /// The detail level of the image. Can be `low`, `high`, or `auto`.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub detail : Option< String >,
  }

  /// Represents a tool call generated by the model.
  ///
  /// # Used By
  /// - `ChatCompletionRequestMessage`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq, Former ) ]
  pub struct ChatCompletionMessageToolCall
  {
    /// The ID of the tool call.
    pub id : String,
    /// The type of the tool. Currently, only `function` is supported.
    pub r#type : String,
    /// The function that the model called.
    pub function : ChatCompletionMessageToolCallFunction,
  }

  /// Represents a function call within a tool call.
  ///
  /// # Used By
  /// - `ChatCompletionMessageToolCall`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq, Former ) ]
  pub struct ChatCompletionMessageToolCallFunction
  {
    /// The name of the function to call.
    pub name : String,
    /// The arguments to call the function with, as a JSON string.
    pub arguments : String,
  }

  /// Represents a tool that can be used by the model.
  ///
  /// # Used By
  /// - `ChatCompletionRequest`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq, Former ) ]
  pub struct ChatCompletionTool
  {
    /// The type of the tool. Currently, only `function` is supported.
    pub r#type : String,
    /// The function definition.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub function : Option< FunctionTool >,
  }

  /// Represents the choice of tool to use.
  ///
  /// # Used By
  /// - `ChatCompletionRequest`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  #[ serde( untagged ) ]
  pub enum ToolChoiceOption
  {
    /// A string representing the tool choice (e.g., "none", "auto").
    String( String ),
    /// A specific tool to force the model to use.
    Object( ToolChoiceObject ),
  }

  /// Represents a specific tool to force the model to use.
  ///
  /// # Used By
  /// - `ToolChoiceOption::Object`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq, Former ) ]
  pub struct ToolChoiceObject
  {
    /// The type of the tool. Currently, only `function` is supported.
    pub r#type : String,
    /// The function to force the model to use.
    pub function : ToolChoiceFunction,
  }

  /// Represents a function to force the model to use.
  ///
  /// # Used By
  /// - `ToolChoiceObject`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq, Former ) ]
  pub struct ToolChoiceFunction
  {
    /// The name of the function to force the model to use.
    pub name : String,
  }

  /// Represents a chat completion request.
  ///
  /// # Used By
  /// - `api::responses::Responses::create`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq, Former ) ]
  pub struct ChatCompletionRequest
  {
    /// ID of the model to use.
    pub model : String,
    /// A list of messages comprising the conversation so far.
    pub messages : Vec< ChatCompletionRequestMessage >,
    /// What sampling temperature to use, between 0 and 2.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub temperature : Option< f32 >,
    /// An alternative to sampling with temperature, called nucleus sampling.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub top_p : Option< f32 >,
    /// The maximum number of tokens to generate in the chat completion.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub max_tokens : Option< i32 >,
    /// Number of chat completion choices to generate for each input message.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub n : Option< i32 >,
    /// Up to 4 sequences where the API will stop generating further tokens.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub stop : Option< Vec< String > >,
    /// Whether to stream back partial progress.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub stream : Option< bool >,
    /// The system prompt that helps guide the behavior of the model.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub system_prompt : Option< String >,
    /// A unique identifier representing your end-user.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub user : Option< String >,
    /// A list of tools the model may call.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub tools : Option< Vec< ChatCompletionTool > >,
    /// Controls which (if any) tool the model calls.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub tool_choice : Option< ToolChoiceOption >,
    /// An object specifying the format that the model must output.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub response_format : Option< ChatCompletionResponseFormat >,
    /// This feature is in Beta.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub seed : Option< i64 >,
    /// Adjusts the likelihood of specified tokens appearing in the completion.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub logit_bias : Option< Value >,
    /// Log probability of the most likely tokens.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub logprobs : Option< bool >,
    /// The number of most likely tokens to return at each token position.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub top_logprobs : Option< i32 >,
  }

  /// Represents the format that the model must output.
  ///
  /// # Used By
  /// - `ChatCompletionRequest`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq, Former ) ]
  pub struct ChatCompletionResponseFormat
  {
    /// The type of response format. Currently, only `json_object` is supported.
    pub r#type : String,
  }

  /// Represents a chat completion response.
  ///
  /// # Used By
  /// - `api::responses::Responses::create`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct CreateChatCompletionResponse
  {
    /// A unique identifier for the chat completion.
    pub id : String,
    /// A list of chat completion choices.
    pub choices : Vec< ChatCompletionChoice >,
    /// The Unix timestamp (in seconds) of when the chat completion was created.
    #[ serde( rename = "created" ) ]
    pub created_at : i64,
    /// The model used for the chat completion.
    pub model : String,
    /// The object type, which is always `chat.completion`.
    pub object : String,
    /// This fingerprint represents the contents of the `input` field.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub system_fingerprint : Option< String >,
    /// Usage statistics for the completion request.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub usage : Option< ChatCompletionUsage >,
  }

  /// Represents a choice in a chat completion response.
  ///
  /// # Used By
  /// - `CreateChatCompletionResponse`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct ChatCompletionChoice
  {
    /// The reason the model finished generating tokens.
    pub finish_reason : String,
    /// The index of the choice in the list of choices.
    pub index : i32,
    /// A message describing the model's response.
    pub message : ChatCompletionResponseMessage,
    /// Log probability information for the choice.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub logprobs : Option< ChatCompletionLogprobs >,
  }

  /// Represents a message in a chat completion response.
  ///
  /// # Used By
  /// - `ChatCompletionChoice`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct ChatCompletionResponseMessage
  {
    /// The contents of the message.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub content : Option< String >,
    /// The role of the author of this message.
    pub role : String,
    /// The tool calls generated by the model, if applicable.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub tool_calls : Option< Vec< ChatCompletionMessageToolCall > >,
  }

  /// Represents usage statistics for a chat completion request.
  ///
  /// # Used By
  /// - `CreateChatCompletionResponse`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct ChatCompletionUsage
  {
    /// Number of tokens in the completion.
    pub completion_tokens : i32,
    /// Number of tokens in the prompt.
    pub prompt_tokens : i32,
    /// Total number of tokens used in the request (prompt + completion).
    pub total_tokens : i32,
  }

  /// Represents log probability information for a chat completion choice.
  ///
  /// # Used By
  /// - `ChatCompletionChoice`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct ChatCompletionLogprobs
  {
    /// A list of log probability information for the tokens in the completion.
    pub content : Vec< ChatCompletionLogprobsContent >,
  }

  /// Represents log probability information for a single token in the completion.
  ///
  /// # Used By
  /// - `ChatCompletionLogprobs`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct ChatCompletionLogprobsContent
  {
    /// The token.
    pub token : String,
    /// The log probability of the token.
    pub logprob : f32,
    /// A list of the most likely tokens and their log probabilities.
    pub top_logprobs : Vec< ChatCompletionLogprobsTopLogprob >,
  }

  /// Represents a top log probability token.
  ///
  /// # Used By
  /// - `ChatCompletionLogprobsContent`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct ChatCompletionLogprobsTopLogprob
  {
    /// The token.
    pub token : String,
    /// The log probability of the token.
    pub logprob : f32,
  }

  /// Represents a streaming chat completion response.
  ///
  /// # Used By
  /// - `api::responses::Responses::create_stream`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct ChatCompletionStreamResponse
  {
    /// A unique identifier for the chat completion.
    pub id : String,
    /// A list of chat completion choices.
    pub choices : Vec< ChatCompletionStreamChoice >,
    /// The Unix timestamp (in seconds) of when the chat completion was created.
    #[ serde( rename = "created" ) ]
    pub created_at : i64,
    /// The model used for the chat completion.
    pub model : String,
    /// The object type, which is always `chat.completion.chunk`.
    pub object : String,
    /// This fingerprint represents the contents of the `input` field.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub system_fingerprint : Option< String >,
  }

  /// Represents a choice in a streaming chat completion response.
  ///
  /// # Used By
  /// - `ChatCompletionStreamResponse`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct ChatCompletionStreamChoice
  {
    /// The reason the model finished generating tokens.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub finish_reason : Option< String >,
    /// The index of the choice in the list of choices.
    pub index : i32,
    /// A message describing the model's response.
    pub delta : ChatCompletionStreamResponseMessage,
    /// Log probability information for the choice.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub logprobs : Option< ChatCompletionLogprobs >,
  }

  /// Represents a message in a streaming chat completion response.
  ///
  /// # Used By
  /// - `ChatCompletionStreamChoice`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct ChatCompletionStreamResponseMessage
  {
    /// The contents of the message.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub content : Option< String >,
    /// The role of the author of this message.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub role : Option< String >,
    /// The tool calls generated by the model, if applicable.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub tool_calls : Option< Vec< ChatCompletionMessageToolCall > >,
  }
}

crate ::mod_interface!
{
  exposed use
  {
    ChatCompletionRequestMessage,
    ChatCompletionRequestMessageContent,
    ChatCompletionRequestMessageContentPart,
    ChatCompletionRequestMessageContentImageUrl,
    ChatCompletionMessageToolCall,
    ChatCompletionMessageToolCallFunction,
    ChatCompletionTool,
    ToolChoiceOption,
    ToolChoiceObject,
    ToolChoiceFunction,
    ChatCompletionRequest,
    ChatCompletionResponseFormat,
    CreateChatCompletionResponse,
    ChatCompletionChoice,
    ChatCompletionResponseMessage,
    ChatCompletionUsage,
    ChatCompletionLogprobs,
    ChatCompletionLogprobsContent,
    ChatCompletionLogprobsTopLogprob,
    ChatCompletionStreamResponse,
    ChatCompletionStreamChoice,
    ChatCompletionStreamResponseMessage,
  };
}