openai 0.92.0 → 0.93.0

data/sig/openai/models/chat/chat_completion.rbs

@@ -18,30 +18,127 @@ module OpenAI
         }
 
       class ChatCompletion < OpenAI::Internal::Type::BaseModel
+        # A unique identifier for the chat completion.
         attr_accessor id: String
 
+        # A list of chat completion choices. Can be more than one if `n` is greater
+        # than 1.
         attr_accessor choices: ::Array[OpenAI::Chat::ChatCompletion::Choice]
 
+        # The Unix timestamp (in seconds) of when the chat completion was created.
         attr_accessor created: Integer
 
+        # The model used for the chat completion.
         attr_accessor model: String
 
+        # The object type, which is always `chat.completion`.
         attr_accessor object: :"chat.completion"
 
+        # Set of 16 key-value pairs that can be attached to an object. This can be useful
+        # for storing additional information about the object in a structured format, and
+        # querying for objects via API or the dashboard.
+        #
+        # Keys are strings with a maximum length of 64 characters. Values are strings with
+        # a maximum length of 512 characters.
         attr_accessor metadata: OpenAI::Models::metadata?
 
+        # Moderation results for the request input and generated output, if moderated
+        # completions were requested.
         attr_accessor moderation: OpenAI::Chat::ChatCompletion::Moderation?
 
+        # Specifies the processing type used for serving the request.
+        #
+        # - If set to 'auto', then the request will be processed with the service tier
+        #   configured in the Project settings. Unless otherwise configured, the Project
+        #   will use 'default'.
+        # - If set to 'default', then the request will be processed with the standard
+        #   pricing and performance for the selected model.
+        # - If set to
+        #   '[flex](https://developers.openai.com/api/docs/guides/flex-processing)', then
+        #   the request will be processed with the Flex Processing service tier.
+        # - To opt-in to
+        #   [Fast mode](https://developers.openai.com/api/docs/guides/fast-mode) at the
+        #   request level, include the `service_tier=fast` or `service_tier=priority`
+        #   parameter for Responses or Chat Completions. The response will show
+        #   `service_tier=priority` regardless of if you specify `service_tier=fast` or
+        #   `priority` in your request.
+        # - When not set, the default behavior is 'auto'.
+        #
+        # When the `service_tier` parameter is set, the response body will include the
+        # `service_tier` value based on the processing mode actually used to serve the
+        # request. This response value may be different from the value set in the
+        # parameter.
         attr_accessor service_tier: OpenAI::Models::Chat::ChatCompletion::service_tier?
 
+        # This fingerprint represents the backend configuration that the model runs with.
+        #
+        # Can be used in conjunction with the `seed` request parameter to understand when
+        # backend changes have been made that might impact determinism.
         attr_reader system_fingerprint: String?
 
+        # This fingerprint represents the backend configuration that the model runs with.
+        #
+        # Can be used in conjunction with the `seed` request parameter to understand when
+        # backend changes have been made that might impact determinism.
         def system_fingerprint=: (String) -> String
 
+        # Usage statistics for the completion request.
         attr_reader usage: OpenAI::CompletionUsage?
 
+        # Usage statistics for the completion request.
         def usage=: (OpenAI::CompletionUsage) -> OpenAI::CompletionUsage
 
+        # @param id
+        #   A unique identifier for the chat completion.
+        # @param choices
+        #   A list of chat completion choices. Can be more than one if `n` is greater
+        #   than 1.
+        # @param created
+        #   The Unix timestamp (in seconds) of when the chat completion was created.
+        # @param model
+        #   The model used for the chat completion.
+        # @param metadata
+        #   Set of 16 key-value pairs that can be attached to an object. This can be useful
+        #   for storing additional information about the object in a structured format, and
+        #   querying for objects via API or the dashboard.
+        #
+        #   Keys are strings with a maximum length of 64 characters. Values are strings with
+        #   a maximum length of 512 characters.
+        # @param moderation
+        #   Moderation results for the request input and generated output, if moderated
+        #   completions were requested.
+        # @param service_tier
+        #   Specifies the processing type used for serving the request.
+        #
+        #   - If set to 'auto', then the request will be processed with the service tier
+        #     configured in the Project settings. Unless otherwise configured, the Project
+        #     will use 'default'.
+        #   - If set to 'default', then the request will be processed with the standard
+        #     pricing and performance for the selected model.
+        #   - If set to
+        #     '[flex](https://developers.openai.com/api/docs/guides/flex-processing)', then
+        #     the request will be processed with the Flex Processing service tier.
+        #   - To opt-in to
+        #     [Fast mode](https://developers.openai.com/api/docs/guides/fast-mode) at the
+        #     request level, include the `service_tier=fast` or `service_tier=priority`
+        #     parameter for Responses or Chat Completions. The response will show
+        #     `service_tier=priority` regardless of if you specify `service_tier=fast` or
+        #     `priority` in your request.
+        #   - When not set, the default behavior is 'auto'.
+        #
+        #   When the `service_tier` parameter is set, the response body will include the
+        #   `service_tier` value based on the processing mode actually used to serve the
+        #   request. This response value may be different from the value set in the
+        #   parameter.
+        # @param system_fingerprint
+        #   This fingerprint represents the backend configuration that the model runs with.
+        #
+        #   Can be used in conjunction with the `seed` request parameter to understand when
+        #   backend changes have been made that might impact determinism.
+        # @param usage
+        #   Usage statistics for the completion request.
+        # @param object
+        #   The object type, which is always `chat.completion`.
         def initialize: (
           id: String,
           choices: ::Array[OpenAI::Chat::ChatCompletion::Choice],
@@ -77,14 +174,38 @@ module OpenAI
           }
 
         class Choice < OpenAI::Internal::Type::BaseModel
+          # The reason the model stopped generating tokens. This will be `stop` if the model
+          # hit a natural stop point or a provided stop sequence, `length` if the maximum
+          # number of tokens specified in the request was reached, `content_filter` if
+          # content was omitted due to a flag from our content filters, `tool_calls` if the
+          # model called a tool, or `function_call` (deprecated) if the model called a
+          # function. Read the [Model Spec](https://model-spec.openai.com/2025-12-18.html)
+          # for more.
           attr_accessor finish_reason: OpenAI::Models::Chat::ChatCompletion::Choice::finish_reason
 
+          # The index of the choice in the list of choices.
           attr_accessor index: Integer
 
+          # Log probability information for the choice.
           attr_accessor logprobs: OpenAI::Chat::ChatCompletion::Choice::Logprobs?
 
+          # A chat completion message generated by the model.
           attr_accessor message: OpenAI::Chat::ChatCompletionMessage
 
+          # @param finish_reason
+          #   The reason the model stopped generating tokens. This will be `stop` if the model
+          #   hit a natural stop point or a provided stop sequence, `length` if the maximum
+          #   number of tokens specified in the request was reached, `content_filter` if
+          #   content was omitted due to a flag from our content filters, `tool_calls` if the
+          #   model called a tool, or `function_call` (deprecated) if the model called a
+          #   function. Read the [Model Spec](https://model-spec.openai.com/2025-12-18.html)
+          #   for more.
+          # @param index
+          #   The index of the choice in the list of choices.
+          # @param logprobs
+          #   Log probability information for the choice.
+          # @param message
+          #   A chat completion message generated by the model.
           def initialize: (
             finish_reason: OpenAI::Models::Chat::ChatCompletion::Choice::finish_reason,
             index: Integer,
@@ -121,10 +242,16 @@ module OpenAI
             }
 
           class Logprobs < OpenAI::Internal::Type::BaseModel
+            # A list of message content tokens with log probability information.
             attr_accessor content: ::Array[OpenAI::Chat::ChatCompletionTokenLogprob]?
 
+            # A list of message refusal tokens with log probability information.
             attr_accessor refusal: ::Array[OpenAI::Chat::ChatCompletionTokenLogprob]?
 
+            # @param content
+            #   A list of message content tokens with log probability information.
+            # @param refusal
+            #   A list of message refusal tokens with log probability information.
             def initialize: (
               content: ::Array[OpenAI::Chat::ChatCompletionTokenLogprob]?,
               refusal: ::Array[OpenAI::Chat::ChatCompletionTokenLogprob]?
@@ -144,10 +271,16 @@ module OpenAI
           }
 
         class Moderation < OpenAI::Internal::Type::BaseModel
+          # Moderation for the request input.
           attr_accessor input: OpenAI::Models::Chat::ChatCompletion::Moderation::input
 
+          # Moderation for the generated output.
           attr_accessor output: OpenAI::Models::Chat::ChatCompletion::Moderation::output
 
+          # @param input
+          #   Moderation for the request input.
+          # @param output
+          #   Moderation for the generated output.
           def initialize: (
             input: OpenAI::Models::Chat::ChatCompletion::Moderation::input,
             output: OpenAI::Models::Chat::ChatCompletion::Moderation::output
@@ -173,12 +306,21 @@ module OpenAI
               }
 
             class ModerationResults < OpenAI::Internal::Type::BaseModel
+              # The moderation model used to generate the results.
               attr_accessor model: String
 
+              # A list of moderation results.
               attr_accessor results: ::Array[OpenAI::Chat::ChatCompletion::Moderation::Input::ModerationResults::Result]
 
+              # The object type, which is always `moderation_results`.
               attr_accessor type: :moderation_results
 
+              # @param model
+              #   The moderation model used to generate the results.
+              # @param results
+              #   A list of moderation results.
+              # @param type
+              #   The object type, which is always `moderation_results`.
               def initialize: (
                 model: String,
                 results: ::Array[OpenAI::Chat::ChatCompletion::Moderation::Input::ModerationResults::Result],
@@ -202,18 +344,40 @@ module OpenAI
                 }
 
               class Result < OpenAI::Internal::Type::BaseModel
+                # A dictionary of moderation categories to booleans, True if the input is flagged
+                # under this category.
                 attr_accessor categories: ::Hash[Symbol, bool]
 
+                # Which modalities of input are reflected by the score for each category.
                 attr_accessor category_applied_input_types: ::Hash[Symbol, ::Array[OpenAI::Models::Chat::ChatCompletion::Moderation::Input::ModerationResults::Result::category_applied_input_type]]
 
+                # A dictionary of moderation categories to scores.
                 attr_accessor category_scores: ::Hash[Symbol, Float]
 
+                # A boolean indicating whether the content was flagged by any category.
                 attr_accessor flagged: bool
 
+                # The moderation model that produced this result.
                 attr_accessor model: String
 
+                # The object type, which was always `moderation_result` for successful moderation
+                # results.
                 attr_accessor type: :moderation_result
 
+                # @param categories
+                #   A dictionary of moderation categories to booleans, True if the input is flagged
+                #   under this category.
+                # @param category_applied_input_types
+                #   Which modalities of input are reflected by the score for each category.
+                # @param category_scores
+                #   A dictionary of moderation categories to scores.
+                # @param flagged
+                #   A boolean indicating whether the content was flagged by any category.
+                # @param model
+                #   The moderation model that produced this result.
+                # @param type
+                #   The object type, which was always `moderation_result` for successful moderation
+                #   results.
                 def initialize: (
                   categories: ::Hash[Symbol, bool],
                   category_applied_input_types: ::Hash[Symbol, ::Array[OpenAI::Models::Chat::ChatCompletion::Moderation::Input::ModerationResults::Result::category_applied_input_type]],
@@ -248,12 +412,21 @@ module OpenAI
             type error = { code: String, message: String, ?type: :error }
 
             class Error < OpenAI::Internal::Type::BaseModel
+              # The error code.
               attr_accessor code: String
 
+              # The error message.
               attr_accessor message: String
 
+              # The object type, which is always `error`.
               attr_accessor type: :error
 
+              # @param code
+              #   The error code.
+              # @param message
+              #   The error message.
+              # @param type
+              #   The object type, which is always `error`.
               def initialize: (
                 code: String,
                 message: String,
@@ -281,12 +454,21 @@ module OpenAI
               }
 
             class ModerationResults < OpenAI::Internal::Type::BaseModel
+              # The moderation model used to generate the results.
               attr_accessor model: String
 
+              # A list of moderation results.
               attr_accessor results: ::Array[OpenAI::Chat::ChatCompletion::Moderation::Output::ModerationResults::Result]
 
+              # The object type, which is always `moderation_results`.
               attr_accessor type: :moderation_results
 
+              # @param model
+              #   The moderation model used to generate the results.
+              # @param results
+              #   A list of moderation results.
+              # @param type
+              #   The object type, which is always `moderation_results`.
               def initialize: (
                 model: String,
                 results: ::Array[OpenAI::Chat::ChatCompletion::Moderation::Output::ModerationResults::Result],
@@ -310,18 +492,40 @@ module OpenAI
                 }
 
               class Result < OpenAI::Internal::Type::BaseModel
+                # A dictionary of moderation categories to booleans, True if the input is flagged
+                # under this category.
                 attr_accessor categories: ::Hash[Symbol, bool]
 
+                # Which modalities of input are reflected by the score for each category.
                 attr_accessor category_applied_input_types: ::Hash[Symbol, ::Array[OpenAI::Models::Chat::ChatCompletion::Moderation::Output::ModerationResults::Result::category_applied_input_type]]
 
+                # A dictionary of moderation categories to scores.
                 attr_accessor category_scores: ::Hash[Symbol, Float]
 
+                # A boolean indicating whether the content was flagged by any category.
                 attr_accessor flagged: bool
 
+                # The moderation model that produced this result.
                 attr_accessor model: String
 
+                # The object type, which was always `moderation_result` for successful moderation
+                # results.
                 attr_accessor type: :moderation_result
 
+                # @param categories
+                #   A dictionary of moderation categories to booleans, True if the input is flagged
+                #   under this category.
+                # @param category_applied_input_types
+                #   Which modalities of input are reflected by the score for each category.
+                # @param category_scores
+                #   A dictionary of moderation categories to scores.
+                # @param flagged
+                #   A boolean indicating whether the content was flagged by any category.
+                # @param model
+                #   The moderation model that produced this result.
+                # @param type
+                #   The object type, which was always `moderation_result` for successful moderation
+                #   results.
                 def initialize: (
                   categories: ::Hash[Symbol, bool],
                   category_applied_input_types: ::Hash[Symbol, ::Array[OpenAI::Models::Chat::ChatCompletion::Moderation::Output::ModerationResults::Result::category_applied_input_type]],
@@ -356,12 +560,21 @@ module OpenAI
             type error = { code: String, message: String, ?type: :error }
 
             class Error < OpenAI::Internal::Type::BaseModel
+              # The error code.
               attr_accessor code: String
 
+              # The error message.
               attr_accessor message: String
 
+              # The object type, which is always `error`.
               attr_accessor type: :error
 
+              # @param code
+              #   The error code.
+              # @param message
+              #   The error message.
+              # @param type
+              #   The object type, which is always `error`.
               def initialize: (
                 code: String,
                 message: String,

data/sig/openai/models/chat/chat_completion_allowed_tool_choice.rbs

@@ -10,10 +10,16 @@ module OpenAI
         }
 
       class ChatCompletionAllowedToolChoice < OpenAI::Internal::Type::BaseModel
+        # Constrains the tools available to the model to a pre-defined set.
         attr_accessor allowed_tools: OpenAI::Chat::ChatCompletionAllowedTools
 
+        # Allowed tool configuration type. Always `allowed_tools`.
         attr_accessor type: :allowed_tools
 
+        # @param allowed_tools
+        #   Constrains the tools available to the model to a pre-defined set.
+        # @param type
+        #   Allowed tool configuration type. Always `allowed_tools`.
         def initialize: (
           allowed_tools: OpenAI::Chat::ChatCompletionAllowedTools,
           ?type: :allowed_tools

data/sig/openai/models/chat/chat_completion_allowed_tools.rbs

@@ -8,10 +8,44 @@ module OpenAI
         }
 
       class ChatCompletionAllowedTools < OpenAI::Internal::Type::BaseModel
+        # Constrains the tools available to the model to a pre-defined set.
+        #
+        # `auto` allows the model to pick from among the allowed tools and generate a
+        # message.
+        #
+        # `required` requires the model to call one or more of the allowed tools.
         attr_accessor mode: OpenAI::Models::Chat::ChatCompletionAllowedTools::mode
 
+        # A list of tool definitions that the model should be allowed to call.
+        #
+        # For the Chat Completions API, the list of tool definitions might look like:
+        #
+        # ```json
+        # [
+        #   { "type": "function", "function": { "name": "get_weather" } },
+        #   { "type": "function", "function": { "name": "get_time" } }
+        # ]
+        # ```
         attr_accessor tools: ::Array[::Hash[Symbol, top]]
 
+        # @param mode
+        #   Constrains the tools available to the model to a pre-defined set.
+        #
+        #   `auto` allows the model to pick from among the allowed tools and generate a
+        #   message.
+        #
+        #   `required` requires the model to call one or more of the allowed tools.
+        # @param tools
+        #   A list of tool definitions that the model should be allowed to call.
+        #
+        #   For the Chat Completions API, the list of tool definitions might look like:
+        #
+        #   ```json
+        #   [
+        #     { "type": "function", "function": { "name": "get_weather" } },
+        #     { "type": "function", "function": { "name": "get_time" } }
+        #   ]
+        #   ```
         def initialize: (
           mode: OpenAI::Models::Chat::ChatCompletionAllowedTools::mode,
           tools: ::Array[::Hash[Symbol, top]]

data/sig/openai/models/chat/chat_completion_assistant_message_param.rbs

@@ -15,26 +15,58 @@ module OpenAI
         }
 
       class ChatCompletionAssistantMessageParam < OpenAI::Internal::Type::BaseModel
+        # The role of the messages author, in this case `assistant`.
         attr_accessor role: :assistant
 
+        # Data about a previous audio response from the model.
+        # [Learn more](https://developers.openai.com/api/docs/guides/audio).
         attr_accessor audio: OpenAI::Chat::ChatCompletionAssistantMessageParam::Audio?
 
+        # The contents of the assistant message. Required unless `tool_calls` or
+        # `function_call` is specified.
         attr_accessor content: OpenAI::Models::Chat::ChatCompletionAssistantMessageParam::content?
 
+        # Deprecated and replaced by `tool_calls`. The name and arguments of a function
+        # that should be called, as generated by the model.
         attr_accessor function_call: OpenAI::Chat::ChatCompletionAssistantMessageParam::FunctionCall?
 
+        # An optional name for the participant. Provides the model information to
+        # differentiate between participants of the same role.
         attr_reader name: String?
 
+        # An optional name for the participant. Provides the model information to
+        # differentiate between participants of the same role.
         def name=: (String) -> String
 
+        # The refusal message by the assistant.
         attr_accessor refusal: String?
 
+        # The tool calls generated by the model, such as function calls.
         attr_reader tool_calls: ::Array[OpenAI::Models::Chat::chat_completion_message_tool_call]?
 
+        # The tool calls generated by the model, such as function calls.
         def tool_calls=: (
           ::Array[OpenAI::Models::Chat::chat_completion_message_tool_call]
         ) -> ::Array[OpenAI::Models::Chat::chat_completion_message_tool_call]
 
+        # @param audio
+        #   Data about a previous audio response from the model.
+        #   [Learn more](https://developers.openai.com/api/docs/guides/audio).
+        # @param content
+        #   The contents of the assistant message. Required unless `tool_calls` or
+        #   `function_call` is specified.
+        # @param function_call
+        #   Deprecated and replaced by `tool_calls`. The name and arguments of a function
+        #   that should be called, as generated by the model.
+        # @param name
+        #   An optional name for the participant. Provides the model information to
+        #   differentiate between participants of the same role.
+        # @param refusal
+        #   The refusal message by the assistant.
+        # @param tool_calls
+        #   The tool calls generated by the model, such as function calls.
+        # @param role
+        #   The role of the messages author, in this case `assistant`.
         def initialize: (
           ?audio: OpenAI::Chat::ChatCompletionAssistantMessageParam::Audio?,
           ?content: OpenAI::Models::Chat::ChatCompletionAssistantMessageParam::content?,
@@ -58,8 +90,11 @@ module OpenAI
         type audio = { id: String }
 
         class Audio < OpenAI::Internal::Type::BaseModel
+          # Unique identifier for a previous audio response from the model.
           attr_accessor id: String
 
+          # @param id
+          #   Unique identifier for a previous audio response from the model.
           def initialize: (id: String) -> void
 
           def to_hash: -> { id: String }
@@ -90,10 +125,22 @@ module OpenAI
         type function_call = { arguments: String, name: String }
 
         class FunctionCall < OpenAI::Internal::Type::BaseModel
+          # The arguments to call the function with, as generated by the model in JSON
+          # format. Note that the model does not always generate valid JSON, and may
+          # hallucinate parameters not defined by your function schema. Validate the
+          # arguments in your code before calling your function.
           attr_accessor arguments: String
 
+          # The name of the function to call.
           attr_accessor name: String
 
+          # @param arguments
+          #   The arguments to call the function with, as generated by the model in JSON
+          #   format. Note that the model does not always generate valid JSON, and may
+          #   hallucinate parameters not defined by your function schema. Validate the
+          #   arguments in your code before calling your function.
+          # @param name
+          #   The name of the function to call.
           def initialize: (arguments: String, name: String) -> void
 
           def to_hash: -> { arguments: String, name: String }

data/sig/openai/models/chat/chat_completion_audio.rbs

@@ -7,14 +7,30 @@ module OpenAI
         { id: String, data: String, expires_at: Integer, transcript: String }
 
       class ChatCompletionAudio < OpenAI::Internal::Type::BaseModel
+        # Unique identifier for this audio response.
         attr_accessor id: String
 
+        # Base64 encoded audio bytes generated by the model, in the format specified in
+        # the request.
         attr_accessor data: String
 
+        # The Unix timestamp (in seconds) for when this audio response will no longer be
+        # accessible on the server for use in multi-turn conversations.
         attr_accessor expires_at: Integer
 
+        # Transcript of the audio generated by the model.
         attr_accessor transcript: String
 
+        # @param id
+        #   Unique identifier for this audio response.
+        # @param data
+        #   Base64 encoded audio bytes generated by the model, in the format specified in
+        #   the request.
+        # @param expires_at
+        #   The Unix timestamp (in seconds) for when this audio response will no longer be
+        #   accessible on the server for use in multi-turn conversations.
+        # @param transcript
+        #   Transcript of the audio generated by the model.
         def initialize: (
           id: String,
           data: String,

data/sig/openai/models/chat/chat_completion_audio_param.rbs

@@ -10,10 +10,24 @@ module OpenAI
         }
 
       class ChatCompletionAudioParam < OpenAI::Internal::Type::BaseModel
+        # Specifies the output audio format. Must be one of `wav`, `mp3`, `flac`, `opus`,
+        # or `pcm16`.
         attr_accessor format_: OpenAI::Models::Chat::ChatCompletionAudioParam::format_
 
+        # The voice the model uses to respond. Supported built-in voices are `alloy`,
+        # `ash`, `ballad`, `coral`, `echo`, `fable`, `nova`, `onyx`, `sage`, `shimmer`,
+        # `marin`, and `cedar`. You may also provide a custom voice object with an `id`,
+        # for example `{ "id": "voice_1234" }`.
         attr_accessor voice: OpenAI::Models::Chat::ChatCompletionAudioParam::voice
 
+        # @param format_
+        #   Specifies the output audio format. Must be one of `wav`, `mp3`, `flac`, `opus`,
+        #   or `pcm16`.
+        # @param voice
+        #   The voice the model uses to respond. Supported built-in voices are `alloy`,
+        #   `ash`, `ballad`, `coral`, `echo`, `fable`, `nova`, `onyx`, `sage`, `shimmer`,
+        #   `marin`, and `cedar`. You may also provide a custom voice object with an `id`,
+        #   for example `{ "id": "voice_1234" }`.
         def initialize: (
           format_: OpenAI::Models::Chat::ChatCompletionAudioParam::format_,
           voice: OpenAI::Models::Chat::ChatCompletionAudioParam::voice
@@ -59,8 +73,11 @@ module OpenAI
           type id = { id: String }
 
           class ID < OpenAI::Internal::Type::BaseModel
+            # The custom voice ID, e.g. `voice_1234`.
             attr_accessor id: String
 
+            # @param id
+            #   The custom voice ID, e.g. `voice_1234`.
             def initialize: (id: String) -> void
 
             def to_hash: -> { id: String }