api_openai 0.3.0

//! Response handling and streaming structures for the Realtime API.

/// Define a private namespace for response-related items.
mod private
{
  // Use full paths from crate root for components
  use crate::components::common::{ Metadata, VoiceIdsShared, Error };
  use crate::components::tools::{ Tool };
  use crate::components::realtime_shared::conversation::
  {
    RealtimeConversationItem,
    RealtimeConversationItemWithReference,
  };

  // Serde imports
  use serde::{ Serialize, Deserialize };
  use serde_json::Value; // Keep if needed for Value type

  /// Represents details about the status of a Realtime response (e.g., why it failed or was incomplete).
  ///
  /// # Used By
  /// - `RealtimeResponse`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ] // Added Serialize
  pub struct RealtimeResponseStatusDetails
  {
    /// The type corresponding to the `status` field (`completed`, `cancelled`, `incomplete`, `failed`).
    pub r#type : String,
    /// The reason the Response did not complete (e.g., `turn_detected`, `max_output_tokens`).
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub reason : Option< String >,
    /// Details of the error if the status is `failed`.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub error : Option< Error >,
  }

  /// Detailed breakdown of input tokens used in a Realtime response.
  ///
  /// # Used By
  /// - `RealtimeResponseUsage`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ] // Added Serialize
  pub struct RealtimeResponseInputTokenDetails
  {
    /// The number of cached tokens used.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub cached_tokens : Option< i32 >,
    /// The number of text tokens used.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub text_tokens : Option< i32 >,
    /// The number of audio tokens used.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub audio_tokens : Option< i32 >,
  }

  /// Detailed breakdown of output tokens used in a Realtime response.
  ///
  /// # Used By
  /// - `RealtimeResponseUsage`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ] // Added Serialize
  pub struct RealtimeResponseOutputTokenDetails
  {
    /// The number of text tokens used.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub text_tokens : Option< i32 >,
    /// The number of audio tokens used.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub audio_tokens : Option< i32 >,
  }

  /// Usage statistics for a Realtime response, corresponding to billing.
  ///
  /// # Used By
  /// - `RealtimeResponse`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ] // Added Serialize
  pub struct RealtimeResponseUsage
  {
    /// The total number of tokens in the Response.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub total_tokens : Option< i32 >,
    /// The number of input tokens used.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub input_tokens : Option< i32 >,
    /// The number of output tokens sent.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub output_tokens : Option< i32 >,
    /// Details about the input tokens used.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub input_token_details : Option< RealtimeResponseInputTokenDetails >,
    /// Details about the output tokens used.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub output_token_details : Option< RealtimeResponseOutputTokenDetails >,
  }

  /// Represents the response resource from the Realtime API.
  ///
  /// # Used By
  /// - `RealtimeServerEventResponseCreated`
  /// - `RealtimeServerEventResponseDone`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ] // Added Serialize
  pub struct RealtimeResponse
  {
    /// The unique ID of the response.
    pub id : String,
    /// The object type, must be `realtime.response`.
    pub object : String,
    /// The final status of the response (`completed`, `cancelled`, `failed`, or `incomplete`).
    pub status : String,
    /// Additional details about the status.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub status_details : Option< RealtimeResponseStatusDetails >,
    /// The list of output items generated by the response.
    pub output : Vec< RealtimeConversationItem >,
    /// Metadata associated with the response.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub metadata : Option< Metadata >,
    /// Usage statistics for the Response.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub usage : Option< RealtimeResponseUsage >,
    /// Which conversation the response is added to (`auto`, `none`, or `conv_123`).
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub conversation_id : Option< String >,
    /// The voice the model used to respond.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub voice : Option< VoiceIdsShared >,
    /// The set of modalities the model used to respond.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub modalities : Option< Vec< String > >,
    /// The format of output audio.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub output_audio_format : Option< String >,
    /// Sampling temperature used for this response.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub temperature : Option< f64 >,
    /// Maximum number of output tokens used in this response.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub max_response_output_tokens : Option< Value >, // Can be integer or "inf"
  }

  /// Parameters for creating a new Realtime response via the client event.
  ///
  /// # Used By
  /// - `RealtimeClientEventResponseCreate`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq, former::Former ) ] // Added Serialize
  pub struct RealtimeResponseCreateParams
  {
    /// The set of modalities the model can respond with.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub modalities : Option< Vec< String > >,
    /// System instructions override for this response.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub instructions : Option< String >,
    /// Voice override for this response.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub voice : Option< VoiceIdsShared >,
    /// Output audio format override for this response.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub output_audio_format : Option< String >,
    /// Tools override for this response.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub tools : Option< Vec< Tool > >,
    /// Tool choice override for this response.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub tool_choice : Option< String >, // Should ideally be ToolChoice enum if possible
    /// Temperature override for this response.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub temperature : Option< f64 >,
    /// Max output tokens override for this response.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub max_response_output_tokens : Option< Value >, // Can be integer or "inf"
    /// Conversation context override ("auto" or "none").
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub conversation : Option< String >,
    /// Metadata override for this response.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub metadata : Option< Metadata >,
    /// Input items override for this response's context.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub input : Option< Vec< RealtimeConversationItemWithReference > >,
  }

} // end mod private

crate ::mod_interface!
{
  exposed use
  {
    RealtimeResponseStatusDetails,
    RealtimeResponseInputTokenDetails,
    RealtimeResponseOutputTokenDetails,
    RealtimeResponseUsage,
    RealtimeResponse,
    RealtimeResponseCreateParams,
  };
}