RubyGems - openai - Versions diffs - 0.91.0 → 0.93.0 - Mend

openai 0.91.0 → 0.93.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1351) hide show

data/sig/openai/models/realtime/realtime_session_create_response.rbs CHANGED Viewed

@@ -24,78 +24,259 @@ module OpenAI
         }
       class RealtimeSessionCreateResponse < OpenAI::Internal::Type::BaseModel
+        # Unique identifier for the session that looks like `sess_1234567890abcdef`.
         attr_accessor id: String
+        # The object type. Always `realtime.session`.
         attr_accessor object: :"realtime.session"
+        # The type of session to create. Always `realtime` for the Realtime API.
         attr_accessor type: :realtime
+        # Configuration for input and output audio.
         attr_reader audio: OpenAI::Realtime::RealtimeSessionCreateResponse::Audio?
+        # Configuration for input and output audio.
         def audio=: (
           OpenAI::Realtime::RealtimeSessionCreateResponse::Audio
         ) -> OpenAI::Realtime::RealtimeSessionCreateResponse::Audio
+        # Expiration timestamp for the session, in seconds since epoch.
         attr_reader expires_at: Integer?
+        # Expiration timestamp for the session, in seconds since epoch.
         def expires_at=: (Integer) -> Integer
+        # Additional fields to include in server outputs.
+        #
+        # `item.input_audio_transcription.logprobs`: Include logprobs for input audio
+        # transcription.
         attr_reader include: ::Array[OpenAI::Models::Realtime::RealtimeSessionCreateResponse::include_]?
+        # Additional fields to include in server outputs.
+        #
+        # `item.input_audio_transcription.logprobs`: Include logprobs for input audio
+        # transcription.
         def include=: (
           ::Array[OpenAI::Models::Realtime::RealtimeSessionCreateResponse::include_]
         ) -> ::Array[OpenAI::Models::Realtime::RealtimeSessionCreateResponse::include_]
+        # The default system instructions (i.e. system message) prepended to model calls.
+        # This field allows the client to guide the model on desired responses. The model
+        # can be instructed on response content and format, (e.g. "be extremely succinct",
+        # "act friendly", "here are examples of good responses") and on audio behavior
+        # (e.g. "talk quickly", "inject emotion into your voice", "laugh frequently"). The
+        # instructions are not guaranteed to be followed by the model, but they provide
+        # guidance to the model on the desired behavior.
+        #
+        # Note that the server sets default instructions which will be used if this field
+        # is not set and are visible in the `session.created` event at the start of the
+        # session.
         attr_reader instructions: String?
+        # The default system instructions (i.e. system message) prepended to model calls.
+        # This field allows the client to guide the model on desired responses. The model
+        # can be instructed on response content and format, (e.g. "be extremely succinct",
+        # "act friendly", "here are examples of good responses") and on audio behavior
+        # (e.g. "talk quickly", "inject emotion into your voice", "laugh frequently"). The
+        # instructions are not guaranteed to be followed by the model, but they provide
+        # guidance to the model on the desired behavior.
+        #
+        # Note that the server sets default instructions which will be used if this field
+        # is not set and are visible in the `session.created` event at the start of the
+        # session.
         def instructions=: (String) -> String
+        # Maximum number of output tokens for a single assistant response, inclusive of
+        # tool calls. Provide an integer between 1 and 4096 to limit output tokens, or
+        # `inf` for the maximum available tokens for a given model. Defaults to `inf`.
         attr_reader max_output_tokens: OpenAI::Models::Realtime::RealtimeSessionCreateResponse::max_output_tokens?
+        # Maximum number of output tokens for a single assistant response, inclusive of
+        # tool calls. Provide an integer between 1 and 4096 to limit output tokens, or
+        # `inf` for the maximum available tokens for a given model. Defaults to `inf`.
         def max_output_tokens=: (
           OpenAI::Models::Realtime::RealtimeSessionCreateResponse::max_output_tokens
         ) -> OpenAI::Models::Realtime::RealtimeSessionCreateResponse::max_output_tokens
+        # The Realtime model used for this session.
         attr_reader model: OpenAI::Models::Realtime::RealtimeSessionCreateResponse::model?
+        # The Realtime model used for this session.
         def model=: (
           OpenAI::Models::Realtime::RealtimeSessionCreateResponse::model
         ) -> OpenAI::Models::Realtime::RealtimeSessionCreateResponse::model
+        # The set of modalities the model can respond with. It defaults to `["audio"]`,
+        # indicating that the model will respond with audio plus a transcript. `["text"]`
+        # can be used to make the model respond with text only. It is not possible to
+        # request both `text` and `audio` at the same time.
         attr_reader output_modalities: ::Array[OpenAI::Models::Realtime::RealtimeSessionCreateResponse::output_modality]?
+        # The set of modalities the model can respond with. It defaults to `["audio"]`,
+        # indicating that the model will respond with audio plus a transcript. `["text"]`
+        # can be used to make the model respond with text only. It is not possible to
+        # request both `text` and `audio` at the same time.
         def output_modalities=: (
           ::Array[OpenAI::Models::Realtime::RealtimeSessionCreateResponse::output_modality]
         ) -> ::Array[OpenAI::Models::Realtime::RealtimeSessionCreateResponse::output_modality]
+        # Reference to a prompt template and its variables.
+        # [Learn more](https://developers.openai.com/api/docs/guides/text?api-mode=responses#version-prompts-in-code).
         attr_accessor prompt: OpenAI::Responses::ResponsePrompt?
+        # Configuration for reasoning-capable Realtime models such as `gpt-realtime-2`.
         attr_reader reasoning: OpenAI::Realtime::RealtimeReasoning?
+        # Configuration for reasoning-capable Realtime models such as `gpt-realtime-2`.
         def reasoning=: (
           OpenAI::Realtime::RealtimeReasoning
         ) -> OpenAI::Realtime::RealtimeReasoning
+        # How the model chooses tools. Provide one of the string modes or force a specific
+        # function/MCP tool.
         attr_reader tool_choice: OpenAI::Models::Realtime::RealtimeSessionCreateResponse::tool_choice?
+        # How the model chooses tools. Provide one of the string modes or force a specific
+        # function/MCP tool.
         def tool_choice=: (
           OpenAI::Models::Realtime::RealtimeSessionCreateResponse::tool_choice
         ) -> OpenAI::Models::Realtime::RealtimeSessionCreateResponse::tool_choice
+        # Tools available to the model.
         attr_reader tools: ::Array[OpenAI::Models::Realtime::RealtimeSessionCreateResponse::tool]?
+        # Tools available to the model.
         def tools=: (
           ::Array[OpenAI::Models::Realtime::RealtimeSessionCreateResponse::tool]
         ) -> ::Array[OpenAI::Models::Realtime::RealtimeSessionCreateResponse::tool]
+        # Realtime API can write session traces to the
+        # [Traces Dashboard](https://platform.openai.com/logs?api=traces). Set to null to
+        # disable tracing. Once tracing is enabled for a session, the configuration cannot
+        # be modified.
+        #
+        # `auto` will create a trace for the session with default values for the workflow
+        # name, group id, and metadata.
         attr_accessor tracing: OpenAI::Models::Realtime::RealtimeSessionCreateResponse::tracing?
+        # When the number of tokens in a conversation exceeds the model's input token
+        # limit, the conversation be truncated, meaning messages (starting from the
+        # oldest) will not be included in the model's context. A 32k context model with
+        # 4,096 max output tokens can only include 28,224 tokens in the context before
+        # truncation occurs.
+        #
+        # Clients can configure truncation behavior to truncate with a lower max token
+        # limit, which is an effective way to control token usage and cost.
+        #
+        # Truncation will reduce the number of cached tokens on the next turn (busting the
+        # cache), since messages are dropped from the beginning of the context. However,
+        # clients can also configure truncation to retain messages up to a fraction of the
+        # maximum context size, which will reduce the need for future truncations and thus
+        # improve the cache rate.
+        #
+        # Truncation can be disabled entirely, which means the server will never truncate
+        # but would instead return an error if the conversation exceeds the model's input
+        # token limit.
         attr_reader truncation: OpenAI::Models::Realtime::realtime_truncation?
+        # When the number of tokens in a conversation exceeds the model's input token
+        # limit, the conversation be truncated, meaning messages (starting from the
+        # oldest) will not be included in the model's context. A 32k context model with
+        # 4,096 max output tokens can only include 28,224 tokens in the context before
+        # truncation occurs.
+        #
+        # Clients can configure truncation behavior to truncate with a lower max token
+        # limit, which is an effective way to control token usage and cost.
+        #
+        # Truncation will reduce the number of cached tokens on the next turn (busting the
+        # cache), since messages are dropped from the beginning of the context. However,
+        # clients can also configure truncation to retain messages up to a fraction of the
+        # maximum context size, which will reduce the need for future truncations and thus
+        # improve the cache rate.
+        #
+        # Truncation can be disabled entirely, which means the server will never truncate
+        # but would instead return an error if the conversation exceeds the model's input
+        # token limit.
         def truncation=: (
           OpenAI::Models::Realtime::realtime_truncation
         ) -> OpenAI::Models::Realtime::realtime_truncation
+        # @param id
+        #   Unique identifier for the session that looks like `sess_1234567890abcdef`.
+        # @param audio
+        #   Configuration for input and output audio.
+        # @param expires_at
+        #   Expiration timestamp for the session, in seconds since epoch.
+        # @param include
+        #   Additional fields to include in server outputs.
+        #
+        #   `item.input_audio_transcription.logprobs`: Include logprobs for input audio
+        #   transcription.
+        # @param instructions
+        #   The default system instructions (i.e. system message) prepended to model calls.
+        #   This field allows the client to guide the model on desired responses. The model
+        #   can be instructed on response content and format, (e.g. "be extremely succinct",
+        #   "act friendly", "here are examples of good responses") and on audio behavior
+        #   (e.g. "talk quickly", "inject emotion into your voice", "laugh frequently"). The
+        #   instructions are not guaranteed to be followed by the model, but they provide
+        #   guidance to the model on the desired behavior.
+        #
+        #   Note that the server sets default instructions which will be used if this field
+        #   is not set and are visible in the `session.created` event at the start of the
+        #   session.
+        # @param max_output_tokens
+        #   Maximum number of output tokens for a single assistant response, inclusive of
+        #   tool calls. Provide an integer between 1 and 4096 to limit output tokens, or
+        #   `inf` for the maximum available tokens for a given model. Defaults to `inf`.
+        # @param model
+        #   The Realtime model used for this session.
+        # @param output_modalities
+        #   The set of modalities the model can respond with. It defaults to `["audio"]`,
+        #   indicating that the model will respond with audio plus a transcript. `["text"]`
+        #   can be used to make the model respond with text only. It is not possible to
+        #   request both `text` and `audio` at the same time.
+        # @param prompt
+        #   Reference to a prompt template and its variables.
+        #   [Learn more](https://developers.openai.com/api/docs/guides/text?api-mode=responses#version-prompts-in-code).
+        # @param reasoning
+        #   Configuration for reasoning-capable Realtime models such as `gpt-realtime-2`.
+        # @param tool_choice
+        #   How the model chooses tools. Provide one of the string modes or force a specific
+        #   function/MCP tool.
+        # @param tools
+        #   Tools available to the model.
+        # @param tracing
+        #   Realtime API can write session traces to the
+        #   [Traces Dashboard](https://platform.openai.com/logs?api=traces). Set to null to
+        #   disable tracing. Once tracing is enabled for a session, the configuration cannot
+        #   be modified.
+        #
+        #   `auto` will create a trace for the session with default values for the workflow
+        #   name, group id, and metadata.
+        # @param truncation
+        #   When the number of tokens in a conversation exceeds the model's input token
+        #   limit, the conversation be truncated, meaning messages (starting from the
+        #   oldest) will not be included in the model's context. A 32k context model with
+        #   4,096 max output tokens can only include 28,224 tokens in the context before
+        #   truncation occurs.
+        #
+        #   Clients can configure truncation behavior to truncate with a lower max token
+        #   limit, which is an effective way to control token usage and cost.
+        #
+        #   Truncation will reduce the number of cached tokens on the next turn (busting the
+        #   cache), since messages are dropped from the beginning of the context. However,
+        #   clients can also configure truncation to retain messages up to a fraction of the
+        #   maximum context size, which will reduce the need for future truncations and thus
+        #   improve the cache rate.
+        #
+        #   Truncation can be disabled entirely, which means the server will never truncate
+        #   but would instead return an error if the conversation exceeds the model's input
+        #   token limit.
+        # @param object
+        #   The object type. Always `realtime.session`.
+        # @param type
+        #   The type of session to create. Always `realtime` for the Realtime API.
         def initialize: (
           id: String,
           ?audio: OpenAI::Realtime::RealtimeSessionCreateResponse::Audio,
@@ -172,14 +353,26 @@ module OpenAI
             }
           class Input < OpenAI::Internal::Type::BaseModel
+            # The format of the input audio.
             attr_reader format_: OpenAI::Models::Realtime::realtime_audio_formats?
+            # The format of the input audio.
             def format_=: (
               OpenAI::Models::Realtime::realtime_audio_formats
             ) -> OpenAI::Models::Realtime::realtime_audio_formats
+            # Configuration for input audio noise reduction. This can be set to `null` to turn
+            # off. Noise reduction filters audio added to the input audio buffer before it is
+            # sent to VAD and the model. Filtering the audio can improve VAD and turn
+            # detection accuracy (reducing false positives) and model performance by improving
+            # perception of the input audio.
             attr_reader noise_reduction: OpenAI::Realtime::RealtimeSessionCreateResponse::Audio::Input::NoiseReduction?
+            # Configuration for input audio noise reduction. This can be set to `null` to turn
+            # off. Noise reduction filters audio added to the input audio buffer before it is
+            # sent to VAD and the model. Filtering the audio can improve VAD and turn
+            # detection accuracy (reducing false positives) and model performance by improving
+            # perception of the input audio.
             def noise_reduction=: (
               OpenAI::Realtime::RealtimeSessionCreateResponse::Audio::Input::NoiseReduction
             ) -> OpenAI::Realtime::RealtimeSessionCreateResponse::Audio::Input::NoiseReduction
@@ -190,8 +383,49 @@ module OpenAI
               OpenAI::Realtime::AudioTranscription
             ) -> OpenAI::Realtime::AudioTranscription
+            # Configuration for turn detection, ether Server VAD or Semantic VAD. This can be
+            # set to `null` to turn off, in which case the client must manually trigger model
+            # response.
+            #
+            # Server VAD means that the model will detect the start and end of speech based on
+            # audio volume and respond at the end of user speech.
+            #
+            # Semantic VAD is more advanced and uses a turn detection model (in conjunction
+            # with VAD) to semantically estimate whether the user has finished speaking, then
+            # dynamically sets a timeout based on this probability. For example, if user audio
+            # trails off with "uhhm", the model will score a low probability of turn end and
+            # wait longer for the user to continue speaking. This can be useful for more
+            # natural conversations, but may have a higher latency.
+            #
+            # For `gpt-realtime-whisper` transcription sessions, turn detection must be set to
+            # `null`; VAD is not supported.
             attr_accessor turn_detection: OpenAI::Models::Realtime::RealtimeSessionCreateResponse::Audio::Input::turn_detection?
+            # @param format_
+            #   The format of the input audio.
+            # @param noise_reduction
+            #   Configuration for input audio noise reduction. This can be set to `null` to turn
+            #   off. Noise reduction filters audio added to the input audio buffer before it is
+            #   sent to VAD and the model. Filtering the audio can improve VAD and turn
+            #   detection accuracy (reducing false positives) and model performance by improving
+            #   perception of the input audio.
+            # @param turn_detection
+            #   Configuration for turn detection, ether Server VAD or Semantic VAD. This can be
+            #   set to `null` to turn off, in which case the client must manually trigger model
+            #   response.
+            #
+            #   Server VAD means that the model will detect the start and end of speech based on
+            #   audio volume and respond at the end of user speech.
+            #
+            #   Semantic VAD is more advanced and uses a turn detection model (in conjunction
+            #   with VAD) to semantically estimate whether the user has finished speaking, then
+            #   dynamically sets a timeout based on this probability. For example, if user audio
+            #   trails off with "uhhm", the model will score a low probability of turn end and
+            #   wait longer for the user to continue speaking. This can be useful for more
+            #   natural conversations, but may have a higher latency.
+            #
+            #   For `gpt-realtime-whisper` transcription sessions, turn detection must be set to
+            #   `null`; VAD is not supported.
             def initialize: (
               ?format_: OpenAI::Models::Realtime::realtime_audio_formats,
               ?noise_reduction: OpenAI::Realtime::RealtimeSessionCreateResponse::Audio::Input::NoiseReduction,
@@ -210,12 +444,22 @@ module OpenAI
               { ?type: OpenAI::Models::Realtime::noise_reduction_type }
             class NoiseReduction < OpenAI::Internal::Type::BaseModel
+              # Type of noise reduction. `near_field` is for close-talking microphones such as
+              # headphones, `far_field` is for far-field microphones such as laptop or
+              # conference room microphones.
               attr_reader type: OpenAI::Models::Realtime::noise_reduction_type?
+              # Type of noise reduction. `near_field` is for close-talking microphones such as
+              # headphones, `far_field` is for far-field microphones such as laptop or
+              # conference room microphones.
               def type=: (
                 OpenAI::Models::Realtime::noise_reduction_type
               ) -> OpenAI::Models::Realtime::noise_reduction_type
+              # @param type
+              #   Type of noise reduction. `near_field` is for close-talking microphones such as
+              #   headphones, `far_field` is for far-field microphones such as laptop or
+              #   conference room microphones.
               def initialize: (
                 ?type: OpenAI::Models::Realtime::noise_reduction_type
               ) -> void
@@ -244,30 +488,126 @@ module OpenAI
                 }
               class ServerVad < OpenAI::Internal::Type::BaseModel
+                # Type of turn detection, `server_vad` to turn on simple Server VAD.
                 attr_accessor type: :server_vad
+                # Whether or not to automatically generate a response when a VAD stop event
+                # occurs. If `interrupt_response` is set to `false` this may fail to create a
+                # response if the model is already responding.
+                #
+                # If both `create_response` and `interrupt_response` are set to `false`, the model
+                # will never respond automatically but VAD events will still be emitted.
                 attr_reader create_response: bool?
+                # Whether or not to automatically generate a response when a VAD stop event
+                # occurs. If `interrupt_response` is set to `false` this may fail to create a
+                # response if the model is already responding.
+                #
+                # If both `create_response` and `interrupt_response` are set to `false`, the model
+                # will never respond automatically but VAD events will still be emitted.
                 def create_response=: (bool) -> bool
+                # Optional timeout after which a model response will be triggered automatically.
+                # This is useful for situations in which a long pause from the user is unexpected,
+                # such as a phone call. The model will effectively prompt the user to continue the
+                # conversation based on the current context.
+                #
+                # The timeout value will be applied after the last model response's audio has
+                # finished playing, i.e. it's set to the `response.done` time plus audio playback
+                # duration.
+                #
+                # An `input_audio_buffer.timeout_triggered` event (plus events associated with the
+                # Response) will be emitted when the timeout is reached. Idle timeout is currently
+                # only supported for `server_vad` mode.
                 attr_accessor idle_timeout_ms: Integer?
+                # Whether or not to automatically interrupt (cancel) any ongoing response with
+                # output to the default conversation (i.e. `conversation` of `auto`) when a VAD
+                # start event occurs. If `true` then the response will be cancelled, otherwise it
+                # will continue until complete.
+                #
+                # If both `create_response` and `interrupt_response` are set to `false`, the model
+                # will never respond automatically but VAD events will still be emitted.
                 attr_reader interrupt_response: bool?
+                # Whether or not to automatically interrupt (cancel) any ongoing response with
+                # output to the default conversation (i.e. `conversation` of `auto`) when a VAD
+                # start event occurs. If `true` then the response will be cancelled, otherwise it
+                # will continue until complete.
+                #
+                # If both `create_response` and `interrupt_response` are set to `false`, the model
+                # will never respond automatically but VAD events will still be emitted.
                 def interrupt_response=: (bool) -> bool
+                # Used only for `server_vad` mode. Amount of audio to include before the VAD
+                # detected speech (in milliseconds). Defaults to 300ms.
                 attr_reader prefix_padding_ms: Integer?
+                # Used only for `server_vad` mode. Amount of audio to include before the VAD
+                # detected speech (in milliseconds). Defaults to 300ms.
                 def prefix_padding_ms=: (Integer) -> Integer
+                # Used only for `server_vad` mode. Duration of silence to detect speech stop (in
+                # milliseconds). Defaults to 500ms. With shorter values the model will respond
+                # more quickly, but may jump in on short pauses from the user.
                 attr_reader silence_duration_ms: Integer?
+                # Used only for `server_vad` mode. Duration of silence to detect speech stop (in
+                # milliseconds). Defaults to 500ms. With shorter values the model will respond
+                # more quickly, but may jump in on short pauses from the user.
                 def silence_duration_ms=: (Integer) -> Integer
+                # Used only for `server_vad` mode. Activation threshold for VAD (0.0 to 1.0), this
+                # defaults to 0.5. A higher threshold will require louder audio to activate the
+                # model, and thus might perform better in noisy environments.
                 attr_reader threshold: Float?
+                # Used only for `server_vad` mode. Activation threshold for VAD (0.0 to 1.0), this
+                # defaults to 0.5. A higher threshold will require louder audio to activate the
+                # model, and thus might perform better in noisy environments.
                 def threshold=: (Float) -> Float
+                # @param create_response
+                #   Whether or not to automatically generate a response when a VAD stop event
+                #   occurs. If `interrupt_response` is set to `false` this may fail to create a
+                #   response if the model is already responding.
+                #
+                #   If both `create_response` and `interrupt_response` are set to `false`, the model
+                #   will never respond automatically but VAD events will still be emitted.
+                # @param idle_timeout_ms
+                #   Optional timeout after which a model response will be triggered automatically.
+                #   This is useful for situations in which a long pause from the user is unexpected,
+                #   such as a phone call. The model will effectively prompt the user to continue the
+                #   conversation based on the current context.
+                #
+                #   The timeout value will be applied after the last model response's audio has
+                #   finished playing, i.e. it's set to the `response.done` time plus audio playback
+                #   duration.
+                #
+                #   An `input_audio_buffer.timeout_triggered` event (plus events associated with the
+                #   Response) will be emitted when the timeout is reached. Idle timeout is currently
+                #   only supported for `server_vad` mode.
+                # @param interrupt_response
+                #   Whether or not to automatically interrupt (cancel) any ongoing response with
+                #   output to the default conversation (i.e. `conversation` of `auto`) when a VAD
+                #   start event occurs. If `true` then the response will be cancelled, otherwise it
+                #   will continue until complete.
+                #
+                #   If both `create_response` and `interrupt_response` are set to `false`, the model
+                #   will never respond automatically but VAD events will still be emitted.
+                # @param prefix_padding_ms
+                #   Used only for `server_vad` mode. Amount of audio to include before the VAD
+                #   detected speech (in milliseconds). Defaults to 300ms.
+                # @param silence_duration_ms
+                #   Used only for `server_vad` mode. Duration of silence to detect speech stop (in
+                #   milliseconds). Defaults to 500ms. With shorter values the model will respond
+                #   more quickly, but may jump in on short pauses from the user.
+                # @param threshold
+                #   Used only for `server_vad` mode. Activation threshold for VAD (0.0 to 1.0), this
+                #   defaults to 0.5. A higher threshold will require louder audio to activate the
+                #   model, and thus might perform better in noisy environments.
+                # @param type
+                #   Type of turn detection, `server_vad` to turn on simple Server VAD.
                 def initialize: (
                   ?create_response: bool,
                   ?idle_timeout_ms: Integer?,
@@ -298,22 +638,55 @@ module OpenAI
                 }
               class SemanticVad < OpenAI::Internal::Type::BaseModel
+                # Type of turn detection, `semantic_vad` to turn on Semantic VAD.
                 attr_accessor type: :semantic_vad
+                # Whether or not to automatically generate a response when a VAD stop event
+                # occurs.
                 attr_reader create_response: bool?
+                # Whether or not to automatically generate a response when a VAD stop event
+                # occurs.
                 def create_response=: (bool) -> bool
+                # Used only for `semantic_vad` mode. The eagerness of the model to respond. `low`
+                # will wait longer for the user to continue speaking, `high` will respond more
+                # quickly. `auto` is the default and is equivalent to `medium`. `low`, `medium`,
+                # and `high` have max timeouts of 8s, 4s, and 2s respectively.
                 attr_reader eagerness: OpenAI::Models::Realtime::RealtimeSessionCreateResponse::Audio::Input::TurnDetection::SemanticVad::eagerness?
+                # Used only for `semantic_vad` mode. The eagerness of the model to respond. `low`
+                # will wait longer for the user to continue speaking, `high` will respond more
+                # quickly. `auto` is the default and is equivalent to `medium`. `low`, `medium`,
+                # and `high` have max timeouts of 8s, 4s, and 2s respectively.
                 def eagerness=: (
                   OpenAI::Models::Realtime::RealtimeSessionCreateResponse::Audio::Input::TurnDetection::SemanticVad::eagerness
                 ) -> OpenAI::Models::Realtime::RealtimeSessionCreateResponse::Audio::Input::TurnDetection::SemanticVad::eagerness
+                # Whether or not to automatically interrupt any ongoing response with output to
+                # the default conversation (i.e. `conversation` of `auto`) when a VAD start event
+                # occurs.
                 attr_reader interrupt_response: bool?
+                # Whether or not to automatically interrupt any ongoing response with output to
+                # the default conversation (i.e. `conversation` of `auto`) when a VAD start event
+                # occurs.
                 def interrupt_response=: (bool) -> bool
+                # @param create_response
+                #   Whether or not to automatically generate a response when a VAD stop event
+                #   occurs.
+                # @param eagerness
+                #   Used only for `semantic_vad` mode. The eagerness of the model to respond. `low`
+                #   will wait longer for the user to continue speaking, `high` will respond more
+                #   quickly. `auto` is the default and is equivalent to `medium`. `low`, `medium`,
+                #   and `high` have max timeouts of 8s, 4s, and 2s respectively.
+                # @param interrupt_response
+                #   Whether or not to automatically interrupt any ongoing response with output to
+                #   the default conversation (i.e. `conversation` of `auto`) when a VAD start event
+                #   occurs.
+                # @param type
+                #   Type of turn detection, `semantic_vad` to turn on Semantic VAD.
                 def initialize: (
                   ?create_response: bool,
                   ?eagerness: OpenAI::Models::Realtime::RealtimeSessionCreateResponse::Audio::Input::TurnDetection::SemanticVad::eagerness,
@@ -354,22 +727,61 @@ module OpenAI
             }
           class Output < OpenAI::Internal::Type::BaseModel
+            # The format of the output audio.
             attr_reader format_: OpenAI::Models::Realtime::realtime_audio_formats?
+            # The format of the output audio.
             def format_=: (
               OpenAI::Models::Realtime::realtime_audio_formats
             ) -> OpenAI::Models::Realtime::realtime_audio_formats
+            # The speed of the model's spoken response as a multiple of the original speed.
+            # 1.0 is the default speed. 0.25 is the minimum speed. 1.5 is the maximum speed.
+            # This value can only be changed in between model turns, not while a response is
+            # in progress.
+            #
+            # This parameter is a post-processing adjustment to the audio after it is
+            # generated, it's also possible to prompt the model to speak faster or slower.
             attr_reader speed: Float?
+            # The speed of the model's spoken response as a multiple of the original speed.
+            # 1.0 is the default speed. 0.25 is the minimum speed. 1.5 is the maximum speed.
+            # This value can only be changed in between model turns, not while a response is
+            # in progress.
+            #
+            # This parameter is a post-processing adjustment to the audio after it is
+            # generated, it's also possible to prompt the model to speak faster or slower.
             def speed=: (Float) -> Float
+            # The voice the model uses to respond. Voice cannot be changed during the session
+            # once the model has responded with audio at least once. Current voice options are
+            # `alloy`, `ash`, `ballad`, `coral`, `echo`, `sage`, `shimmer`, `verse`, `marin`,
+            # and `cedar`. We recommend `marin` and `cedar` for best quality.
             attr_reader voice: OpenAI::Models::Realtime::RealtimeSessionCreateResponse::Audio::Output::voice?
+            # The voice the model uses to respond. Voice cannot be changed during the session
+            # once the model has responded with audio at least once. Current voice options are
+            # `alloy`, `ash`, `ballad`, `coral`, `echo`, `sage`, `shimmer`, `verse`, `marin`,
+            # and `cedar`. We recommend `marin` and `cedar` for best quality.
             def voice=: (
               OpenAI::Models::Realtime::RealtimeSessionCreateResponse::Audio::Output::voice
             ) -> OpenAI::Models::Realtime::RealtimeSessionCreateResponse::Audio::Output::voice
+            # @param format_
+            #   The format of the output audio.
+            # @param speed
+            #   The speed of the model's spoken response as a multiple of the original speed.
+            #   1.0 is the default speed. 0.25 is the minimum speed. 1.5 is the maximum speed.
+            #   This value can only be changed in between model turns, not while a response is
+            #   in progress.
+            #
+            #   This parameter is a post-processing adjustment to the audio after it is
+            #   generated, it's also possible to prompt the model to speak faster or slower.
+            # @param voice
+            #   The voice the model uses to respond. Voice cannot be changed during the session
+            #   once the model has responded with audio at least once. Current voice options are
+            #   `alloy`, `ash`, `ballad`, `coral`, `echo`, `sage`, `shimmer`, `verse`, `marin`,
+            #   and `cedar`. We recommend `marin` and `cedar` for best quality.
             def initialize: (
               ?format_: OpenAI::Models::Realtime::realtime_audio_formats,
               ?speed: Float,
@@ -526,44 +938,154 @@ module OpenAI
             }
           class McpTool < OpenAI::Internal::Type::BaseModel
+            # A label for this MCP server, used to identify it in tool calls.
             attr_accessor server_label: String
+            # The type of the MCP tool. Always `mcp`.
             attr_accessor type: :mcp
+            # The tool invocation context(s).
             attr_accessor allowed_callers: ::Array[OpenAI::Models::Realtime::RealtimeSessionCreateResponse::Tool::McpTool::allowed_caller]?
+            # List of allowed tool names or a filter object.
             attr_accessor allowed_tools: OpenAI::Models::Realtime::RealtimeSessionCreateResponse::Tool::McpTool::allowed_tools?
+            # An OAuth access token that can be used with a remote MCP server, either with a
+            # custom MCP server URL or a service connector. Your application must handle the
+            # OAuth authorization flow and provide the token here.
             attr_reader authorization: String?
+            # An OAuth access token that can be used with a remote MCP server, either with a
+            # custom MCP server URL or a service connector. Your application must handle the
+            # OAuth authorization flow and provide the token here.
             def authorization=: (String) -> String
+            # Identifier for service connectors, like those available in ChatGPT. One of
+            # `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more about
+            # service connectors
+            # [here](https://developers.openai.com/api/docs/guides/tools-connectors-mcp#connectors).
+            #
+            # This field is deprecated for models released after September 1, 2026. Use
+            # `server_url` to connect to a remote MCP server, or `tunnel_id` to connect
+            # through a Secure MCP Tunnel.
+            #
+            # Currently supported `connector_id` values are:
+            #
+            # - Dropbox: `connector_dropbox`
+            # - Gmail: `connector_gmail`
+            # - Google Calendar: `connector_googlecalendar`
+            # - Google Drive: `connector_googledrive`
+            # - Microsoft Teams: `connector_microsoftteams`
+            # - Outlook Calendar: `connector_outlookcalendar`
+            # - Outlook Email: `connector_outlookemail`
+            # - SharePoint: `connector_sharepoint`
             attr_reader connector_id: OpenAI::Models::Realtime::RealtimeSessionCreateResponse::Tool::McpTool::connector_id?
+            # Identifier for service connectors, like those available in ChatGPT. One of
+            # `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more about
+            # service connectors
+            # [here](https://developers.openai.com/api/docs/guides/tools-connectors-mcp#connectors).
+            #
+            # This field is deprecated for models released after September 1, 2026. Use
+            # `server_url` to connect to a remote MCP server, or `tunnel_id` to connect
+            # through a Secure MCP Tunnel.
+            #
+            # Currently supported `connector_id` values are:
+            #
+            # - Dropbox: `connector_dropbox`
+            # - Gmail: `connector_gmail`
+            # - Google Calendar: `connector_googlecalendar`
+            # - Google Drive: `connector_googledrive`
+            # - Microsoft Teams: `connector_microsoftteams`
+            # - Outlook Calendar: `connector_outlookcalendar`
+            # - Outlook Email: `connector_outlookemail`
+            # - SharePoint: `connector_sharepoint`
             def connector_id=: (
               OpenAI::Models::Realtime::RealtimeSessionCreateResponse::Tool::McpTool::connector_id
             ) -> OpenAI::Models::Realtime::RealtimeSessionCreateResponse::Tool::McpTool::connector_id
+            # Whether this MCP tool is deferred and discovered via tool search.
             attr_reader defer_loading: bool?
+            # Whether this MCP tool is deferred and discovered via tool search.
             def defer_loading=: (bool) -> bool
+            # Optional HTTP headers to send to the MCP server. Use for authentication or other
+            # purposes.
             attr_accessor headers: ::Hash[Symbol, String]?
+            # Specify which of the MCP server's tools require approval.
             attr_accessor require_approval: OpenAI::Models::Realtime::RealtimeSessionCreateResponse::Tool::McpTool::require_approval?
+            # Optional description of the MCP server, used to provide more context.
             attr_reader server_description: String?
+            # Optional description of the MCP server, used to provide more context.
             def server_description=: (String) -> String
+            # The URL for the MCP server. One of `server_url`, `connector_id`, or `tunnel_id`
+            # must be provided.
             attr_reader server_url: String?
+            # The URL for the MCP server. One of `server_url`, `connector_id`, or `tunnel_id`
+            # must be provided.
             def server_url=: (String) -> String
+            # The Secure MCP Tunnel ID to use instead of a direct server URL. One of
+            # `server_url`, `connector_id`, or `tunnel_id` must be provided.
             attr_reader tunnel_id: String?
+            # The Secure MCP Tunnel ID to use instead of a direct server URL. One of
+            # `server_url`, `connector_id`, or `tunnel_id` must be provided.
             def tunnel_id=: (String) -> String
+            # @param server_label
+            #   A label for this MCP server, used to identify it in tool calls.
+            # @param allowed_callers
+            #   The tool invocation context(s).
+            # @param allowed_tools
+            #   List of allowed tool names or a filter object.
+            # @param authorization
+            #   An OAuth access token that can be used with a remote MCP server, either with a
+            #   custom MCP server URL or a service connector. Your application must handle the
+            #   OAuth authorization flow and provide the token here.
+            # @param connector_id
+            #   Identifier for service connectors, like those available in ChatGPT. One of
+            #   `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more about
+            #   service connectors
+            #   [here](https://developers.openai.com/api/docs/guides/tools-connectors-mcp#connectors).
+            #
+            #   This field is deprecated for models released after September 1, 2026. Use
+            #   `server_url` to connect to a remote MCP server, or `tunnel_id` to connect
+            #   through a Secure MCP Tunnel.
+            #
+            #   Currently supported `connector_id` values are:
+            #
+            #   - Dropbox: `connector_dropbox`
+            #   - Gmail: `connector_gmail`
+            #   - Google Calendar: `connector_googlecalendar`
+            #   - Google Drive: `connector_googledrive`
+            #   - Microsoft Teams: `connector_microsoftteams`
+            #   - Outlook Calendar: `connector_outlookcalendar`
+            #   - Outlook Email: `connector_outlookemail`
+            #   - SharePoint: `connector_sharepoint`
+            # @param defer_loading
+            #   Whether this MCP tool is deferred and discovered via tool search.
+            # @param headers
+            #   Optional HTTP headers to send to the MCP server. Use for authentication or other
+            #   purposes.
+            # @param require_approval
+            #   Specify which of the MCP server's tools require approval.
+            # @param server_description
+            #   Optional description of the MCP server, used to provide more context.
+            # @param server_url
+            #   The URL for the MCP server. One of `server_url`, `connector_id`, or `tunnel_id`
+            #   must be provided.
+            # @param tunnel_id
+            #   The Secure MCP Tunnel ID to use instead of a direct server URL. One of
+            #   `server_url`, `connector_id`, or `tunnel_id` must be provided.
+            # @param type
+            #   The type of the MCP tool. Always `mcp`.
             def initialize: (
               server_label: String,
               ?allowed_callers: ::Array[OpenAI::Models::Realtime::RealtimeSessionCreateResponse::Tool::McpTool::allowed_caller]?,
@@ -616,14 +1138,31 @@ module OpenAI
                 { ?read_only: bool, ?tool_names: ::Array[String] }
               class McpToolFilter < OpenAI::Internal::Type::BaseModel
+                # Indicates whether or not a tool modifies data or is read-only. If an MCP server
+                # is
+                # [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),
+                # it will match this filter.
                 attr_reader read_only: bool?
+                # Indicates whether or not a tool modifies data or is read-only. If an MCP server
+                # is
+                # [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),
+                # it will match this filter.
                 def read_only=: (bool) -> bool
+                # List of allowed tool names.
                 attr_reader tool_names: ::Array[String]?
+                # List of allowed tool names.
                 def tool_names=: (::Array[String]) -> ::Array[String]
+                # @param read_only
+                #   Indicates whether or not a tool modifies data or is read-only. If an MCP server
+                #   is
+                #   [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),
+                #   it will match this filter.
+                # @param tool_names
+                #   List of allowed tool names.
                 def initialize: (
                   ?read_only: bool,
                   ?tool_names: ::Array[String]
@@ -679,18 +1218,26 @@ module OpenAI
                 }
               class McpToolApprovalFilter < OpenAI::Internal::Type::BaseModel
+                # A filter object to specify which tools are allowed.
                 attr_reader always: OpenAI::Realtime::RealtimeSessionCreateResponse::Tool::McpTool::RequireApproval::McpToolApprovalFilter::Always?
+                # A filter object to specify which tools are allowed.
                 def always=: (
                   OpenAI::Realtime::RealtimeSessionCreateResponse::Tool::McpTool::RequireApproval::McpToolApprovalFilter::Always
                 ) -> OpenAI::Realtime::RealtimeSessionCreateResponse::Tool::McpTool::RequireApproval::McpToolApprovalFilter::Always
+                # A filter object to specify which tools are allowed.
                 attr_reader never: OpenAI::Realtime::RealtimeSessionCreateResponse::Tool::McpTool::RequireApproval::McpToolApprovalFilter::Never?
+                # A filter object to specify which tools are allowed.
                 def never=: (
                   OpenAI::Realtime::RealtimeSessionCreateResponse::Tool::McpTool::RequireApproval::McpToolApprovalFilter::Never
                 ) -> OpenAI::Realtime::RealtimeSessionCreateResponse::Tool::McpTool::RequireApproval::McpToolApprovalFilter::Never
+                # @param always
+                #   A filter object to specify which tools are allowed.
+                # @param never
+                #   A filter object to specify which tools are allowed.
                 def initialize: (
                   ?always: OpenAI::Realtime::RealtimeSessionCreateResponse::Tool::McpTool::RequireApproval::McpToolApprovalFilter::Always,
                   ?never: OpenAI::Realtime::RealtimeSessionCreateResponse::Tool::McpTool::RequireApproval::McpToolApprovalFilter::Never
@@ -704,14 +1251,31 @@ module OpenAI
                 type always = { ?read_only: bool, ?tool_names: ::Array[String] }
                 class Always < OpenAI::Internal::Type::BaseModel
+                  # Indicates whether or not a tool modifies data or is read-only. If an MCP server
+                  # is
+                  # [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),
+                  # it will match this filter.
                   attr_reader read_only: bool?
+                  # Indicates whether or not a tool modifies data or is read-only. If an MCP server
+                  # is
+                  # [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),
+                  # it will match this filter.
                   def read_only=: (bool) -> bool
+                  # List of allowed tool names.
                   attr_reader tool_names: ::Array[String]?
+                  # List of allowed tool names.
                   def tool_names=: (::Array[String]) -> ::Array[String]
+                  # @param read_only
+                  #   Indicates whether or not a tool modifies data or is read-only. If an MCP server
+                  #   is
+                  #   [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),
+                  #   it will match this filter.
+                  # @param tool_names
+                  #   List of allowed tool names.
                   def initialize: (
                     ?read_only: bool,
                     ?tool_names: ::Array[String]
@@ -726,14 +1290,31 @@ module OpenAI
                 type never = { ?read_only: bool, ?tool_names: ::Array[String] }
                 class Never < OpenAI::Internal::Type::BaseModel
+                  # Indicates whether or not a tool modifies data or is read-only. If an MCP server
+                  # is
+                  # [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),
+                  # it will match this filter.
                   attr_reader read_only: bool?
+                  # Indicates whether or not a tool modifies data or is read-only. If an MCP server
+                  # is
+                  # [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),
+                  # it will match this filter.
                   def read_only=: (bool) -> bool
+                  # List of allowed tool names.
                   attr_reader tool_names: ::Array[String]?
+                  # List of allowed tool names.
                   def tool_names=: (::Array[String]) -> ::Array[String]
+                  # @param read_only
+                  #   Indicates whether or not a tool modifies data or is read-only. If an MCP server
+                  #   is
+                  #   [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),
+                  #   it will match this filter.
+                  # @param tool_names
+                  #   List of allowed tool names.
                   def initialize: (
                     ?read_only: bool,
                     ?tool_names: ::Array[String]
@@ -775,18 +1356,39 @@ module OpenAI
             { ?group_id: String, ?metadata: top, ?workflow_name: String }
           class TracingConfiguration < OpenAI::Internal::Type::BaseModel
+            # The group id to attach to this trace to enable filtering and grouping in the
+            # Traces Dashboard.
             attr_reader group_id: String?
+            # The group id to attach to this trace to enable filtering and grouping in the
+            # Traces Dashboard.
             def group_id=: (String) -> String
+            # The arbitrary metadata to attach to this trace to enable filtering in the Traces
+            # Dashboard.
             attr_reader metadata: top?
+            # The arbitrary metadata to attach to this trace to enable filtering in the Traces
+            # Dashboard.
             def metadata=: (top) -> top
+            # The name of the workflow to attach to this trace. This is used to name the trace
+            # in the Traces Dashboard.
             attr_reader workflow_name: String?
+            # The name of the workflow to attach to this trace. This is used to name the trace
+            # in the Traces Dashboard.
             def workflow_name=: (String) -> String
+            # @param group_id
+            #   The group id to attach to this trace to enable filtering and grouping in the
+            #   Traces Dashboard.
+            # @param metadata
+            #   The arbitrary metadata to attach to this trace to enable filtering in the Traces
+            #   Dashboard.
+            # @param workflow_name
+            #   The name of the workflow to attach to this trace. This is used to name the trace
+            #   in the Traces Dashboard.
             def initialize: (
               ?group_id: String,
               ?metadata: top,