api_openai 0.3.0

//! Run-related types and structures for the Assistants API.

/// Define a private namespace for run-related items.
mod private
{
  // Use full paths from crate root for components
  use crate::components::common::
  {
    Metadata,
    CompletionUsage,
  };
  use crate::components::tools::Tool;

  // Import message types from the message module
  use crate::components::assistants_shared::message::IncompleteDetails;

  // Add serde imports
  use serde::{ Serialize, Deserialize };
  use serde_json::Value;

  // Import types from assistant module
  use crate::components::assistants_shared::assistant::
  {
    AssistantsApiResponseFormatOption,
    AssistantsApiToolChoiceOption,
    TruncationObject,
  };

  /// The last error associated with a run or run step.
  ///
  /// # Used By
  /// - `RunObject`
  /// - `RunStepObject`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct RunLastError
  {
    /// One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`.
    pub code : String,
    /// A human-readable description of the error.
    pub message : String,
  }

  /// Details on the action required to continue the run (currently only tool outputs).
  ///
  /// # Used By
  /// - `RunObject`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct RequiredAction
  {
    /// For now, this is always `submit_tool_outputs`.
    pub r#type : String,
    /// Details on the tool outputs needed for this run to continue.
    pub submit_tool_outputs : SubmitToolOutputs,
  }

  /// Details on the tool outputs needed for a run to continue.
  ///
  /// # Used By
  /// - `RequiredAction`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct SubmitToolOutputs
  {
    /// A list of the relevant tool calls.
    pub tool_calls : Vec< RunToolCallObject >,
  }

  /// Represents a tool call generated by the model during a run that requires output submission.
  ///
  /// # Used By
  /// - `SubmitToolOutputs`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct RunToolCallObject
  {
    /// The ID of the tool call.
    pub id : String,
    /// The type of tool call (currently always `function`).
    pub r#type : String,
    /// The function definition.
    pub function : RunToolCallFunction,
  }

  /// The function definition within a `RunToolCallObject`.
  ///
  /// # Used By
  /// - `RunToolCallObject`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct RunToolCallFunction
  {
    /// The name of the function.
    pub name : String,
    /// The arguments that the model expects you to pass to the function.
    pub arguments : String,
  }

  /// Represents an execution run on a thread.
  ///
  /// # Used By
  /// - `/threads/runs` (POST response)
  /// - `/threads/{thread_id}/runs` (GET - in `ListRunsResponse`, POST response)
  /// - `/threads/{thread_id}/runs/{run_id}` (GET, POST response)
  /// - `/threads/{thread_id}/runs/{run_id}/cancel` (POST response)
  /// - `/threads/{thread_id}/runs/{run_id}/submit_tool_outputs` (POST response)
  /// - `AssistantStreamEvent::ThreadRunCreated` and other run status events
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct RunObject
  {
    /// The identifier, which can be referenced in API endpoints.
    pub id : String,
    /// The object type, which is always `thread.run`.
    pub object : String,
    /// The Unix timestamp (in seconds) for when the run was created.
    pub created_at : i64,
    /// The ID of the thread that was executed on.
    pub thread_id : String,
    /// The ID of the assistant used for execution.
    pub assistant_id : String,
    /// The status of the run.
    pub status : String, // Enum : queued, in_progress, requires_action, cancelling, cancelled, failed, completed, incomplete, expired
    /// Details on the action required to continue the run. Null if no action is required.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub required_action : Option< RequiredAction >,
    /// The last error associated with this run. Null if no errors.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub last_error : Option< RunLastError >,
    /// The Unix timestamp (in seconds) for when the run will expire.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub expires_at : Option< i64 >,
    /// The Unix timestamp (in seconds) for when the run was started.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub started_at : Option< i64 >,
    /// The Unix timestamp (in seconds) for when the run was cancelled.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub cancelled_at : Option< i64 >,
    /// The Unix timestamp (in seconds) for when the run failed.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub failed_at : Option< i64 >,
    /// The Unix timestamp (in seconds) for when the run was completed.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub completed_at : Option< i64 >,
    /// Details on why the run is incomplete. Null if the run is not incomplete.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub incomplete_details : Option< IncompleteDetails >,
    /// The model that the assistant used for this run.
    pub model : String,
    /// The instructions that the assistant used for this run.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub instructions : Option< String >,
    /// The list of tools that the assistant used for this run.
    pub tools : Vec< Tool >,
    /// Set of 16 key-value pairs attached to the object.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub metadata : Option< Metadata >,
    /// Usage statistics related to the run. Null if the run is not in a terminal state.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub usage : Option< CompletionUsage >,
    /// The sampling temperature used for this run.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub temperature : Option< f32 >,
    /// The nucleus sampling value used for this run.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub top_p : Option< f32 >,
    /// The maximum number of prompt tokens specified for the run.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub max_prompt_tokens : Option< i32 >,
    /// The maximum number of completion tokens specified for the run.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub max_completion_tokens : Option< i32 >,
    /// The truncation strategy used for the run.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub truncation_strategy : Option< TruncationObject >,
    /// The tool choice strategy used for the run.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub tool_choice : Option< AssistantsApiToolChoiceOption >,
    /// Whether parallel tool calls were enabled for this run.
    pub parallel_tool_calls : bool,
    /// The response format specified for this run.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub response_format : Option< AssistantsApiResponseFormatOption >,
  }

  /// Response containing a list of runs.
  ///
  /// # Used By
  /// - `/threads/{thread_id}/runs` (GET)
  #[ derive( Debug, Deserialize, Clone, PartialEq ) ]
  pub struct ListRunsResponse
  {
    /// The object type, always "list".
    pub object : String,
    /// A list of run objects.
    pub data : Vec< RunObject >,
    /// The ID of the first run in the list.
    pub first_id : String,
    /// The ID of the last run in the list.
    pub last_id : String,
    /// Indicates whether there are more runs available.
    pub has_more : bool,
  }

  /// Details of the message creation step within a run.
  ///
  /// # Used By
  /// - `RunStepDetails::MessageCreation`
  /// - `RunStepDeltaStepDetailsMessageCreationObject`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct RunStepDetailsMessageCreationObject
  {
    /// Always `message_creation`.
    pub r#type : String,
    /// Details about the message creation.
    pub message_creation : MessageCreationDetails,
  }

  /// Contains the ID of the message created during a run step.
  ///
  /// # Used By
  /// - `RunStepDetailsMessageCreationObject`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct MessageCreationDetails
  {
    /// The ID of the message that was created by this run step.
    pub message_id : String,
  }

  /// Text output from the Code Interpreter tool call as part of a run step.
  ///
  /// # Used By
  /// - `CodeInterpreterOutput::Logs`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct RunStepDetailsToolCallsCodeOutputLogsObject
  {
    /// Always `logs`.
    pub r#type : String,
    /// The text output from the Code Interpreter tool call.
    pub logs : String,
  }

  /// Image output from the Code Interpreter tool call as part of a run step.
  ///
  /// # Used By
  /// - `CodeInterpreterOutput::Image`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct RunStepDetailsToolCallsCodeOutputImageObject
  {
    /// Always `image`.
    pub r#type : String,
    /// Contains the file ID of the generated image.
    pub image : ImageFileId,
  }

  /// Contains the file ID of an image generated by Code Interpreter.
  ///
  /// # Used By
  /// - `RunStepDetailsToolCallsCodeOutputImageObject`
  /// - `RunStepDeltaStepDetailsToolCallsCodeOutputImageObject`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct ImageFileId
  {
    /// The File ID of the image.
    pub file_id : String,
  }

  /// Represents the output from the Code Interpreter tool, which can be logs or an image.
  ///
  /// # Used By
  /// - `CodeInterpreterDetails`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  #[ serde( untagged ) ]
  pub enum CodeInterpreterOutput
  {
    /// Text log output.
    Logs( RunStepDetailsToolCallsCodeOutputLogsObject ),
    /// Image file output.
    Image( RunStepDetailsToolCallsCodeOutputImageObject ),
  }

  /// Contains the input and output details for a Code Interpreter tool call.
  ///
  /// # Used By
  /// - `RunStepDetailsToolCallsCodeObject`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct CodeInterpreterDetails
  {
    /// The input code provided to the tool.
    pub input : String,
    /// The outputs generated by the tool (logs or images).
    pub outputs : Vec< CodeInterpreterOutput >,
  }

  /// Details of the Code Interpreter tool call the run step was involved in.
  ///
  /// # Used By
  /// - `RunStepToolCall::Code`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct RunStepDetailsToolCallsCodeObject
  {
    /// The ID of the tool call.
    pub id : String,
    /// Always `code_interpreter`.
    pub r#type : String,
    /// The Code Interpreter tool call definition and outputs.
    pub code_interpreter : CodeInterpreterDetails,
  }

  /// Details of the File Search tool call the run step was involved in.
  ///
  /// # Used By
  /// - `RunStepToolCall::FileSearch`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct RunStepDetailsToolCallsFileSearchObject
  {
    /// The ID of the tool call object.
    pub id : String,
    /// Always `file_search`.
    pub r#type : String,
    /// For now, this is always going to be an empty object.
    pub file_search : Value,
  }

  /// Details of the Function tool call the run step was involved in.
  ///
  /// # Used By
  /// - `RunStepToolCall::Function`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct RunStepDetailsToolCallsFunctionObject
  {
    /// The ID of the tool call object.
    pub id : String,
    /// Always `function`.
    pub r#type : String,
    /// The definition of the function that was called.
    pub function : FunctionCallDetails,
  }

  /// Contains the details of a function call within a run step.
  ///
  /// # Used By
  /// - `RunStepDetailsToolCallsFunctionObject`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct FunctionCallDetails
  {
    /// The name of the function.
    pub name : String,
    /// The arguments passed to the function.
    pub arguments : String,
    /// The output of the function. Null if outputs have not been submitted yet.
    pub output : Option< String >,
  }

  /// Represents the specific type of tool call within a run step's details.
  ///
  /// # Used By
  /// - `RunStepDetailsToolCallsObject`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  #[ serde( untagged ) ]
  pub enum RunStepToolCall
  {
    /// Code Interpreter tool call details.
    Code( RunStepDetailsToolCallsCodeObject ),
    /// File Search tool call details.
    FileSearch( RunStepDetailsToolCallsFileSearchObject ),
    /// Function tool call details.
    Function( RunStepDetailsToolCallsFunctionObject ),
  }

  /// Details of the tool calls made during a run step.
  ///
  /// # Used By
  /// - `RunStepDetails::ToolCalls`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct RunStepDetailsToolCallsObject
  {
    /// Always `tool_calls`.
    pub r#type : String,
    /// An array of tool calls the run step was involved in.
    pub tool_calls : Vec< RunStepToolCall >,
  }

  /// Represents the details of a run step, which can be either message creation or tool calls.
  ///
  /// # Used By
  /// - `RunStepObject`
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  #[ serde( untagged ) ]
  pub enum RunStepDetails
  {
    /// Details for a message creation step.
    MessageCreation( RunStepDetailsMessageCreationObject ),
    /// Details for a tool call step.
    ToolCalls( RunStepDetailsToolCallsObject ),
  }

  /// Represents a step in execution of a run.
  ///
  /// # Used By
  /// - `/threads/{thread_id}/runs/{run_id}/steps` (GET - in `ListRunStepsResponse`)
  /// - `/threads/{thread_id}/runs/{run_id}/steps/{step_id}` (GET)
  /// - `AssistantStreamEvent::ThreadRunStepCreated` and other step status events
  #[ derive( Debug, Serialize, Deserialize, Clone, PartialEq ) ]
  pub struct RunStepObject
  {
    /// The identifier of the run step.
    pub id : String,
    /// The object type, always `thread.run.step`.
    pub object : String,
    /// The Unix timestamp (in seconds) for when the run step was created.
    pub created_at : i64,
    /// The ID of the assistant associated with the run step.
    pub assistant_id : String,
    /// The ID of the thread that was run.
    pub thread_id : String,
    /// The ID of the run that this run step is a part of.
    pub run_id : String,
    /// The type of run step (`message_creation` or `tool_calls`).
    pub r#type : String,
    /// The status of the run step.
    pub status : String, // Enum : in_progress, cancelled, failed, completed, expired
    /// The details of the run step.
    pub step_details : RunStepDetails,
    /// The last error associated with this run step. Null if no errors.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub last_error : Option< RunLastError >,
    /// The Unix timestamp (in seconds) for when the run step expired.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub expired_at : Option< i64 >,
    /// The Unix timestamp (in seconds) for when the run step was cancelled.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub cancelled_at : Option< i64 >,
    /// The Unix timestamp (in seconds) for when the run step failed.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub failed_at : Option< i64 >,
    /// The Unix timestamp (in seconds) for when the run step completed.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub completed_at : Option< i64 >,
    /// Set of 16 key-value pairs attached to the object.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub metadata : Option< Metadata >,
    /// Usage statistics related to the run step. Null if status is `in_progress`.
    #[ serde( skip_serializing_if = "Option::is_none" ) ]
    pub usage : Option< CompletionUsage >,
  }

  /// Response containing a list of run steps.
  ///
  /// # Used By
  /// - `/threads/{thread_id}/runs/{run_id}/steps` (GET)
  #[ derive( Debug, Deserialize, Clone, PartialEq ) ]
  pub struct ListRunStepsResponse
  {
    /// The object type, always "list".
    pub object : String,
    /// A list of run step objects.
    pub data : Vec< RunStepObject >,
    /// The ID of the first run step in the list.
    pub first_id : String,
    /// The ID of the last run step in the list.
    pub last_id : String,
    /// Indicates whether there are more run steps available.
    pub has_more : bool,
  }
}

crate ::mod_interface!
{
  exposed use private::RunLastError;
  exposed use private::RequiredAction;
  exposed use private::SubmitToolOutputs;
  exposed use private::RunToolCallObject;
  exposed use private::RunToolCallFunction;
  exposed use private::RunObject;
  exposed use private::ListRunsResponse;
  exposed use private::RunStepDetailsMessageCreationObject;
  exposed use private::MessageCreationDetails;
  exposed use private::RunStepDetailsToolCallsCodeOutputLogsObject;
  exposed use private::RunStepDetailsToolCallsCodeOutputImageObject;
  exposed use private::ImageFileId;
  exposed use private::CodeInterpreterOutput;
  exposed use private::CodeInterpreterDetails;
  exposed use private::RunStepDetailsToolCallsCodeObject;
  exposed use private::RunStepDetailsToolCallsFileSearchObject;
  exposed use private::RunStepDetailsToolCallsFunctionObject;
  exposed use private::FunctionCallDetails;
  exposed use private::RunStepToolCall;
  exposed use private::RunStepDetailsToolCallsObject;
  exposed use private::RunStepDetails;
  exposed use private::RunStepObject;
  exposed use private::ListRunStepsResponse;
}