api_openai_compatible 0.2.0

//! Wire types for `OpenAI` chat completion requests and responses.
//!
//! These types serialise to and deserialise from the JSON shapes described in
//! the `OpenAI` chat completions API reference. Absent optional fields are
//! omitted from the wire representation (`skip_serializing_if = "Option::is_none"`).

mod private
{
  use serde::{ Serialize, Deserialize };
  use former::Former;

  // ------------------------------------------------------------------ //
  //  Role
  // ------------------------------------------------------------------ //

  /// Role of a participant in a chat conversation.
  ///
  /// Serialises to lowercase strings as required by the `OpenAI` wire protocol
  /// (e.g. `Role::User` → `"user"`).
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq, Eq ) ]
  #[ serde( rename_all = "lowercase" ) ]
  pub enum Role
  {
    /// System-level instructions provided before the conversation begins.
    System,

    /// Message from the human user.
    User,

    /// Response generated by the AI assistant.
    Assistant,

    /// Result message from a tool/function call execution.
    Tool,
  }

  // ------------------------------------------------------------------ //
  //  ToolCall / FunctionCall
  // ------------------------------------------------------------------ //

  /// A function invocation requested by the assistant.
  ///
  /// When the model decides to call a tool it includes one or more `ToolCall`
  /// objects in the assistant message's `tool_calls` field.
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct ToolCall
  {
    /// Unique identifier for this invocation (used to correlate tool results).
    pub id : String,

    /// Always `"function"` for function-calling tools.
    #[ serde( rename = "type" ) ]
    pub tool_type : String,

    /// Name and serialised arguments for the function to invoke.
    pub function : FunctionCall,
  }

  /// Name and arguments for a specific function invocation.
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct FunctionCall
  {
    /// Registered function name.
    pub name : String,

    /// JSON-encoded arguments string (not a `Value` — must be re-parsed by caller).
    pub arguments : String,
  }

  // ------------------------------------------------------------------ //
  //  Message
  // ------------------------------------------------------------------ //

  /// A single message in a chat conversation.
  ///
  /// All fields except `role` are optional; `None` fields are omitted from
  /// serialised JSON (`skip_serializing_if = "Option::is_none"`).
  ///
  /// # Examples
  ///
  /// ```
  /// # #[ cfg( feature = "enabled" ) ]
  /// # {
  /// use api_openai_compatible::Message;
  ///
  /// let sys  = Message::system( "You are a helpful assistant." );
  /// let user = Message::user( "What is 2 + 2?" );
  /// # }
  /// ```
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct Message
  {
    /// Who sent this message.
    pub role : Role,

    /// Text content of the message.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub content : Option< String >,

    /// Tool invocations requested by the assistant (assistant role only).
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub tool_calls : Option< Vec< ToolCall > >,

    /// ID of the `ToolCall` this message responds to (tool role only).
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub tool_call_id : Option< String >,
  }

  impl Message
  {
    /// Creates a system-role message.
    ///
    /// # Examples
    ///
    /// ```
    /// # #[ cfg( feature = "enabled" ) ]
    /// # {
    /// use api_openai_compatible::Message;
    ///
    /// let msg = Message::system( "You are a helpful coding assistant." );
    /// # }
    /// ```
    #[ inline ]
    pub fn system( content : impl Into< String > ) -> Self
    {
      Self
      {
        role         : Role::System,
        content      : Some( content.into() ),
        tool_calls   : None,
        tool_call_id : None,
      }
    }

    /// Creates a user-role message.
    ///
    /// # Examples
    ///
    /// ```
    /// # #[ cfg( feature = "enabled" ) ]
    /// # {
    /// use api_openai_compatible::Message;
    ///
    /// let msg = Message::user( "Explain monads." );
    /// # }
    /// ```
    #[ inline ]
    pub fn user( content : impl Into< String > ) -> Self
    {
      Self
      {
        role         : Role::User,
        content      : Some( content.into() ),
        tool_calls   : None,
        tool_call_id : None,
      }
    }

    /// Creates an assistant-role message.
    ///
    /// # Examples
    ///
    /// ```
    /// # #[ cfg( feature = "enabled" ) ]
    /// # {
    /// use api_openai_compatible::Message;
    ///
    /// let msg = Message::assistant( "A monad is a design pattern…" );
    /// # }
    /// ```
    #[ inline ]
    pub fn assistant( content : impl Into< String > ) -> Self
    {
      Self
      {
        role         : Role::Assistant,
        content      : Some( content.into() ),
        tool_calls   : None,
        tool_call_id : None,
      }
    }

    /// Creates a tool-result message.
    ///
    /// # Arguments
    ///
    /// * `tool_call_id` — Must match the `id` of the `ToolCall` being answered.
    /// * `content` — Serialised result from the tool execution.
    ///
    /// # Examples
    ///
    /// ```
    /// # #[ cfg( feature = "enabled" ) ]
    /// # {
    /// use api_openai_compatible::Message;
    ///
    /// let msg = Message::tool( "call_abc123", r#"{"temperature":22}"# );
    /// # }
    /// ```
    #[ inline ]
    pub fn tool
    (
      tool_call_id : impl Into< String >,
      content      : impl Into< String >,
    )
    -> Self
    {
      Self
      {
        role         : Role::Tool,
        content      : Some( content.into() ),
        tool_calls   : None,
        tool_call_id : Some( tool_call_id.into() ),
      }
    }
  }

  // ------------------------------------------------------------------ //
  //  Tool / Function definitions
  // ------------------------------------------------------------------ //

  /// A function tool definition passed in the `tools` array of a request.
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq, Former ) ]
  pub struct Tool
  {
    /// Always `"function"` for function-type tools.
    #[ serde( rename = "type" ) ]
    pub tool_type : String,

    /// Function specification.
    pub function : Function,
  }

  impl Tool
  {
    /// Convenience constructor for a function-type tool.
    ///
    /// # Examples
    ///
    /// ```
    /// # #[ cfg( feature = "enabled" ) ]
    /// # {
    /// use api_openai_compatible::Tool;
    ///
    /// let tool = Tool::function(
    ///   "get_weather",
    ///   "Get current weather for a location",
    ///   serde_json::json!({ "type": "object", "properties": {} }),
    /// );
    /// # }
    /// ```
    #[ inline ]
    pub fn function
    (
      name        : impl Into< String >,
      description : impl Into< String >,
      parameters  : serde_json::Value,
    )
    -> Self
    {
      Self
      {
        tool_type : "function".to_string(),
        function  : Function
        {
          name        : name.into(),
          description : description.into(),
          parameters,
        },
      }
    }
  }

  /// Function specification (name, description, JSON Schema parameters).
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq, Former ) ]
  pub struct Function
  {
    /// Registered function name.
    pub name : String,

    /// Human-readable description used by the model to decide when to call.
    pub description : String,

    /// JSON Schema describing the expected parameters.
    pub parameters : serde_json::Value,
  }

  // ------------------------------------------------------------------ //
  //  Usage
  // ------------------------------------------------------------------ //

  /// Token usage statistics returned in every completion response.
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq, Eq ) ]
  pub struct Usage
  {
    /// Number of tokens in the prompt (input).
    pub prompt_tokens : u32,

    /// Number of tokens in the completion (output).
    pub completion_tokens : u32,

    /// Total tokens consumed (`prompt_tokens + completion_tokens`).
    pub total_tokens : u32,
  }

  // ------------------------------------------------------------------ //
  //  ChatCompletionRequest
  // ------------------------------------------------------------------ //

  /// Request body for the `POST chat/completions` endpoint.
  ///
  /// Uses the `Former` builder pattern for ergonomic construction.
  ///
  /// # Examples
  ///
  /// ```
  /// # #[ cfg( feature = "enabled" ) ]
  /// # {
  /// use api_openai_compatible::{ ChatCompletionRequest, Message };
  ///
  /// let req = ChatCompletionRequest::former()
  ///   .model( "gpt-4o".to_string() )
  ///   .messages( vec![ Message::user( "Hello!" ) ] )
  ///   .max_tokens( 100_u32 )
  ///   .form();
  /// # }
  /// ```
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq, Former ) ]
  pub struct ChatCompletionRequest
  {
    /// Model identifier (e.g. `"gpt-4o"`, `"grok-2-1212"`).
    pub model : String,

    /// Ordered list of conversation messages.
    pub messages : Vec< Message >,

    /// Sampling temperature in `[0.0, 2.0]`. Higher = more random.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub temperature : Option< f32 >,

    /// Maximum tokens to generate in the completion.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub max_tokens : Option< u32 >,

    /// Nucleus sampling threshold in `[0.0, 1.0]`.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub top_p : Option< f32 >,

    /// Frequency penalty in `[0.0, 2.0]` (reduces token repetition).
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub frequency_penalty : Option< f32 >,

    /// Presence penalty in `[0.0, 2.0]` (encourages topic diversity).
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub presence_penalty : Option< f32 >,

    /// When `true`, the response is streamed as Server-Sent Events.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub stream : Option< bool >,

    /// Tool definitions available for function calling.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub tools : Option< Vec< Tool > >,
  }

  // ------------------------------------------------------------------ //
  //  ChatCompletionResponse / Choice
  // ------------------------------------------------------------------ //

  /// Response body from the `POST chat/completions` endpoint.
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct ChatCompletionResponse
  {
    /// Opaque completion identifier (e.g. `"chatcmpl-abc123"`).
    pub id : String,

    /// Object type — always `"chat.completion"`.
    pub object : String,

    /// Unix timestamp of when the completion was created.
    pub created : u64,

    /// Model that generated this completion.
    pub model : String,

    /// One or more completion choices (`n` defaults to 1).
    pub choices : Vec< Choice >,

    /// Token usage statistics for billing.
    pub usage : Usage,
  }

  /// One completion alternative within a `ChatCompletionResponse`.
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct Choice
  {
    /// Zero-based index of this choice.
    pub index : u32,

    /// The generated message.
    pub message : Message,

    /// Reason the generation stopped (`"stop"`, `"length"`, `"tool_calls"`).
    pub finish_reason : Option< String >,
  }
}

crate::mod_interface!
{
  exposed use
  {
    Role,
    ToolCall,
    FunctionCall,
    Message,
    Tool,
    Function,
    Usage,
    ChatCompletionRequest,
    ChatCompletionResponse,
    Choice,
  };
}