openai 0.23.1 → 0.23.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c61159341c0fe919d9f1042f0c705f57d05fc656407e03498bdf1367f704b6ca
-  data.tar.gz: 26c9718404d8d1519acb3d9364f9918c623952679a0b29d11c159ebb070a6227
+  metadata.gz: 7603886aae923da50eb83881be4d69cf1b5be3616b9903a784f16bcd124c023d
+  data.tar.gz: 03feb2933c7a27590301dc9c805d66ce2e7f45e743515e7e46bf9bbf9d61dfe3
 SHA512:
-  metadata.gz: e5bebf2d7459cf64493d9ce74b839ad8c9326df50953ff064ecd9b5a912c077ebef0c0c38b6a95b40f01b7f37e161ed42be30d985e7b608ca76db18908da2d8d
-  data.tar.gz: 0a1fb39beb43b71336e7d0a398bbb56705c850de30f6eb110821b974967e21848d6cc5b626e57434df8bc247b4cd23f71f3c0b41ff425fe39b606ea44454fe2d
+  metadata.gz: 6de05c188535d0ed867bf936a6e97a7f452bd6924678b672d23f7868feeda7144df86dac454bfa29300d81844799c1ab77adc42767a314975d566acacb3aaefd
+  data.tar.gz: bf693ec699be028060d13db1fa9bd5ef3bb980118d5c4b292877bc6a16a88bd743ee10cd6c6a9d3828aa15d31e8e55058d660d831af3179050c68b110d8c705f

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.23.2 (2025-09-11)
+
+Full Changelog: [v0.23.1...v0.23.2](https://github.com/openai/openai-ruby/compare/v0.23.1...v0.23.2)
+
+### Chores
+
+* **api:** Minor docs and type updates for realtime ([ccef982](https://github.com/openai/openai-ruby/commit/ccef9827b31206fc9ba40d2b6165eeefda7621f5))
+
 ## 0.23.1 (2025-09-10)
 
 Full Changelog: [v0.23.0...v0.23.1](https://github.com/openai/openai-ruby/compare/v0.23.0...v0.23.1)

data/README.md

@@ -15,7 +15,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "openai", "~> 0.23.1"
+gem "openai", "~> 0.23.2"
 ```
 
 <!-- x-release-please-end -->

data/lib/openai/models/realtime/input_audio_buffer_timeout_triggered.rb

@@ -5,13 +5,15 @@ module OpenAI
     module Realtime
       class InputAudioBufferTimeoutTriggered < OpenAI::Internal::Type::BaseModel
         # @!attribute audio_end_ms
-        #   Millisecond offset where speech ended within the buffered audio.
+        #   Millisecond offset of audio written to the input audio buffer at the time the
+        #   timeout was triggered.
         #
         #   @return [Integer]
         required :audio_end_ms, Integer
 
         # @!attribute audio_start_ms
-        #   Millisecond offset where speech started within the buffered audio.
+        #   Millisecond offset of audio written to the input audio buffer that was after the
+        #   playback time of the last model response.
         #
         #   @return [Integer]
         required :audio_start_ms, Integer
@@ -35,11 +37,29 @@ module OpenAI
         required :type, const: :"input_audio_buffer.timeout_triggered"
 
         # @!method initialize(audio_end_ms:, audio_start_ms:, event_id:, item_id:, type: :"input_audio_buffer.timeout_triggered")
-        #   Returned when the server VAD timeout is triggered for the input audio buffer.
+        #   Some parameter documentations has been truncated, see
+        #   {OpenAI::Models::Realtime::InputAudioBufferTimeoutTriggered} for more details.
         #
-        #   @param audio_end_ms [Integer] Millisecond offset where speech ended within the buffered audio.
+        #   Returned when the Server VAD timeout is triggered for the input audio buffer.
+        #   This is configured with `idle_timeout_ms` in the `turn_detection` settings of
+        #   the session, and it indicates that there hasn't been any speech detected for the
+        #   configured duration.
         #
-        #   @param audio_start_ms [Integer] Millisecond offset where speech started within the buffered audio.
+        #   The `audio_start_ms` and `audio_end_ms` fields indicate the segment of audio
+        #   after the last model response up to the triggering time, as an offset from the
+        #   beginning of audio written to the input audio buffer. This means it demarcates
+        #   the segment of audio that was silent and the difference between the start and
+        #   end values will roughly match the configured timeout.
+        #
+        #   The empty audio will be committed to the conversation as an `input_audio` item
+        #   (there will be a `input_audio_buffer.committed` event) and a model response will
+        #   be generated. There may be speech that didn't trigger VAD but is still detected
+        #   by the model, so the model may respond with something relevant to the
+        #   conversation or a prompt to continue speaking.
+        #
+        #   @param audio_end_ms [Integer] Millisecond offset of audio written to the input audio buffer at the time the ti
+        #
+        #   @param audio_start_ms [Integer] Millisecond offset of audio written to the input audio buffer that was after the
         #
         #   @param event_id [String] The unique ID of the server event.
         #

data/lib/openai/models/realtime/realtime_audio_config_input.rb

@@ -36,17 +36,20 @@ module OpenAI
         # @!attribute 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.
+        #   response.
         #
-        #   @return [OpenAI::Models::Realtime::RealtimeAudioInputTurnDetection, nil]
-        optional :turn_detection, -> { OpenAI::Realtime::RealtimeAudioInputTurnDetection }
+        #   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.
+        #
+        #   @return [OpenAI::Models::Realtime::RealtimeAudioInputTurnDetection::ServerVad, OpenAI::Models::Realtime::RealtimeAudioInputTurnDetection::SemanticVad, nil]
+        optional :turn_detection, union: -> { OpenAI::Realtime::RealtimeAudioInputTurnDetection }, nil?: true
 
         # @!method initialize(format_: nil, noise_reduction: nil, transcription: nil, turn_detection: nil)
         #   Some parameter documentations has been truncated, see
@@ -58,7 +61,7 @@ module OpenAI
         #
         #   @param transcription [OpenAI::Models::Realtime::AudioTranscription] Configuration for input audio transcription, defaults to off and can be set to `
         #
-        #   @param turn_detection [OpenAI::Models::Realtime::RealtimeAudioInputTurnDetection] Configuration for turn detection, ether Server VAD or Semantic VAD. This can be
+        #   @param turn_detection [OpenAI::Models::Realtime::RealtimeAudioInputTurnDetection::ServerVad, OpenAI::Models::Realtime::RealtimeAudioInputTurnDetection::SemanticVad, nil] Configuration for turn detection, ether Server VAD or Semantic VAD. This can be
 
         # @see OpenAI::Models::Realtime::RealtimeAudioConfigInput#noise_reduction
         class NoiseReduction < OpenAI::Internal::Type::BaseModel

data/lib/openai/models/realtime/realtime_audio_input_turn_detection.rb

@@ -3,128 +3,184 @@
 module OpenAI
   module Models
     module Realtime
-      class RealtimeAudioInputTurnDetection < OpenAI::Internal::Type::BaseModel
-        # @!attribute create_response
-        #   Whether or not to automatically generate a response when a VAD stop event
-        #   occurs.
-        #
-        #   @return [Boolean, nil]
-        optional :create_response, OpenAI::Internal::Type::Boolean
-
-        # @!attribute 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.
-        #
-        #   @return [Symbol, OpenAI::Models::Realtime::RealtimeAudioInputTurnDetection::Eagerness, nil]
-        optional :eagerness, enum: -> { OpenAI::Realtime::RealtimeAudioInputTurnDetection::Eagerness }
-
-        # @!attribute idle_timeout_ms
-        #   Optional idle timeout after which turn detection will auto-timeout when no
-        #   additional audio is received and emits a `timeout_triggered` event.
-        #
-        #   @return [Integer, nil]
-        optional :idle_timeout_ms, Integer, nil?: true
-
-        # @!attribute 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.
-        #
-        #   @return [Boolean, nil]
-        optional :interrupt_response, OpenAI::Internal::Type::Boolean
-
-        # @!attribute prefix_padding_ms
-        #   Used only for `server_vad` mode. Amount of audio to include before the VAD
-        #   detected speech (in milliseconds). Defaults to 300ms.
-        #
-        #   @return [Integer, nil]
-        optional :prefix_padding_ms, Integer
-
-        # @!attribute 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.
-        #
-        #   @return [Integer, nil]
-        optional :silence_duration_ms, Integer
-
-        # @!attribute 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.
-        #
-        #   @return [Float, nil]
-        optional :threshold, Float
-
-        # @!attribute type
-        #   Type of turn detection.
-        #
-        #   @return [Symbol, OpenAI::Models::Realtime::RealtimeAudioInputTurnDetection::Type, nil]
-        optional :type, enum: -> { OpenAI::Realtime::RealtimeAudioInputTurnDetection::Type }
-
-        # @!method initialize(create_response: nil, eagerness: nil, idle_timeout_ms: nil, interrupt_response: nil, prefix_padding_ms: nil, silence_duration_ms: nil, threshold: nil, type: nil)
-        #   Some parameter documentations has been truncated, see
-        #   {OpenAI::Models::Realtime::RealtimeAudioInputTurnDetection} for more details.
-        #
-        #   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.
-        #
-        #   @param create_response [Boolean] Whether or not to automatically generate a response when a VAD stop event occurs
-        #
-        #   @param eagerness [Symbol, OpenAI::Models::Realtime::RealtimeAudioInputTurnDetection::Eagerness] Used only for `semantic_vad` mode. The eagerness of the model to respond. `low`
-        #
-        #   @param idle_timeout_ms [Integer, nil] Optional idle timeout after which turn detection will auto-timeout when
-        #
-        #   @param interrupt_response [Boolean] Whether or not to automatically interrupt any ongoing response with output to th
-        #
-        #   @param prefix_padding_ms [Integer] Used only for `server_vad` mode. Amount of audio to include before the VAD detec
-        #
-        #   @param silence_duration_ms [Integer] Used only for `server_vad` mode. Duration of silence to detect speech stop (in m
-        #
-        #   @param threshold [Float] Used only for `server_vad` mode. Activation threshold for VAD (0.0 to 1.0), this
-        #
-        #   @param type [Symbol, OpenAI::Models::Realtime::RealtimeAudioInputTurnDetection::Type] Type of turn detection.
-
-        # 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.
-        #
-        # @see OpenAI::Models::Realtime::RealtimeAudioInputTurnDetection#eagerness
-        module Eagerness
-          extend OpenAI::Internal::Type::Enum
-
-          LOW = :low
-          MEDIUM = :medium
-          HIGH = :high
-          AUTO = :auto
-
-          # @!method self.values
-          #   @return [Array<Symbol>]
+      # 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.
+      module RealtimeAudioInputTurnDetection
+        extend OpenAI::Internal::Type::Union
+
+        discriminator :type
+
+        # Server-side voice activity detection (VAD) which flips on when user speech is detected and off after a period of silence.
+        variant :server_vad, -> { OpenAI::Realtime::RealtimeAudioInputTurnDetection::ServerVad }
+
+        # Server-side semantic turn detection which uses a model to determine when the user has finished speaking.
+        variant :semantic_vad, -> { OpenAI::Realtime::RealtimeAudioInputTurnDetection::SemanticVad }
+
+        class ServerVad < OpenAI::Internal::Type::BaseModel
+          # @!attribute type
+          #   Type of turn detection, `server_vad` to turn on simple Server VAD.
+          #
+          #   @return [Symbol, :server_vad]
+          required :type, const: :server_vad
+
+          # @!attribute create_response
+          #   Whether or not to automatically generate a response when a VAD stop event
+          #   occurs.
+          #
+          #   @return [Boolean, nil]
+          optional :create_response, OpenAI::Internal::Type::Boolean
+
+          # @!attribute 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.
+          #
+          #   @return [Integer, nil]
+          optional :idle_timeout_ms, Integer, nil?: true
+
+          # @!attribute 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.
+          #
+          #   @return [Boolean, nil]
+          optional :interrupt_response, OpenAI::Internal::Type::Boolean
+
+          # @!attribute prefix_padding_ms
+          #   Used only for `server_vad` mode. Amount of audio to include before the VAD
+          #   detected speech (in milliseconds). Defaults to 300ms.
+          #
+          #   @return [Integer, nil]
+          optional :prefix_padding_ms, Integer
+
+          # @!attribute 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.
+          #
+          #   @return [Integer, nil]
+          optional :silence_duration_ms, Integer
+
+          # @!attribute 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.
+          #
+          #   @return [Float, nil]
+          optional :threshold, Float
+
+          # @!method initialize(create_response: nil, idle_timeout_ms: nil, interrupt_response: nil, prefix_padding_ms: nil, silence_duration_ms: nil, threshold: nil, type: :server_vad)
+          #   Some parameter documentations has been truncated, see
+          #   {OpenAI::Models::Realtime::RealtimeAudioInputTurnDetection::ServerVad} for more
+          #   details.
+          #
+          #   Server-side voice activity detection (VAD) which flips on when user speech is
+          #   detected and off after a period of silence.
+          #
+          #   @param create_response [Boolean] Whether or not to automatically generate a response when a VAD stop event occurs
+          #
+          #   @param idle_timeout_ms [Integer, nil] Optional timeout after which a model response will be triggered automatically. T
+          #
+          #   @param interrupt_response [Boolean] Whether or not to automatically interrupt any ongoing response with output to th
+          #
+          #   @param prefix_padding_ms [Integer] Used only for `server_vad` mode. Amount of audio to include before the VAD detec
+          #
+          #   @param silence_duration_ms [Integer] Used only for `server_vad` mode. Duration of silence to detect speech stop (in m
+          #
+          #   @param threshold [Float] Used only for `server_vad` mode. Activation threshold for VAD (0.0 to 1.0), this
+          #
+          #   @param type [Symbol, :server_vad] Type of turn detection, `server_vad` to turn on simple Server VAD.
         end
 
-        # Type of turn detection.
-        #
-        # @see OpenAI::Models::Realtime::RealtimeAudioInputTurnDetection#type
-        module Type
-          extend OpenAI::Internal::Type::Enum
+        class SemanticVad < OpenAI::Internal::Type::BaseModel
+          # @!attribute type
+          #   Type of turn detection, `semantic_vad` to turn on Semantic VAD.
+          #
+          #   @return [Symbol, :semantic_vad]
+          required :type, const: :semantic_vad
+
+          # @!attribute create_response
+          #   Whether or not to automatically generate a response when a VAD stop event
+          #   occurs.
+          #
+          #   @return [Boolean, nil]
+          optional :create_response, OpenAI::Internal::Type::Boolean
+
+          # @!attribute 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.
+          #
+          #   @return [Symbol, OpenAI::Models::Realtime::RealtimeAudioInputTurnDetection::SemanticVad::Eagerness, nil]
+          optional :eagerness,
+                   enum: -> { OpenAI::Realtime::RealtimeAudioInputTurnDetection::SemanticVad::Eagerness }
 
-          SERVER_VAD = :server_vad
-          SEMANTIC_VAD = :semantic_vad
+          # @!attribute 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.
+          #
+          #   @return [Boolean, nil]
+          optional :interrupt_response, OpenAI::Internal::Type::Boolean
 
-          # @!method self.values
-          #   @return [Array<Symbol>]
+          # @!method initialize(create_response: nil, eagerness: nil, interrupt_response: nil, type: :semantic_vad)
+          #   Some parameter documentations has been truncated, see
+          #   {OpenAI::Models::Realtime::RealtimeAudioInputTurnDetection::SemanticVad} for
+          #   more details.
+          #
+          #   Server-side semantic turn detection which uses a model to determine when the
+          #   user has finished speaking.
+          #
+          #   @param create_response [Boolean] Whether or not to automatically generate a response when a VAD stop event occurs
+          #
+          #   @param eagerness [Symbol, OpenAI::Models::Realtime::RealtimeAudioInputTurnDetection::SemanticVad::Eagerness] Used only for `semantic_vad` mode. The eagerness of the model to respond. `low`
+          #
+          #   @param interrupt_response [Boolean] Whether or not to automatically interrupt any ongoing response with output to th
+          #
+          #   @param type [Symbol, :semantic_vad] Type of turn detection, `semantic_vad` to turn on Semantic VAD.
+
+          # 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.
+          #
+          # @see OpenAI::Models::Realtime::RealtimeAudioInputTurnDetection::SemanticVad#eagerness
+          module Eagerness
+            extend OpenAI::Internal::Type::Enum
+
+            LOW = :low
+            MEDIUM = :medium
+            HIGH = :high
+            AUTO = :auto
+
+            # @!method self.values
+            #   @return [Array<Symbol>]
+          end
         end
+
+        # @!method self.variants
+        #   @return [Array(OpenAI::Models::Realtime::RealtimeAudioInputTurnDetection::ServerVad, OpenAI::Models::Realtime::RealtimeAudioInputTurnDetection::SemanticVad)]
       end
     end
   end

data/lib/openai/models/realtime/realtime_server_event.rb

@@ -208,7 +208,19 @@ module OpenAI
         # The event will include the full content of the Item except for audio data, which can be retrieved separately with a `conversation.item.retrieve` event if needed.
         variant :"conversation.item.done", -> { OpenAI::Realtime::ConversationItemDone }
 
-        # Returned when the server VAD timeout is triggered for the input audio buffer.
+        # Returned when the Server VAD timeout is triggered for the input audio buffer. This is configured
+        # with `idle_timeout_ms` in the `turn_detection` settings of the session, and it indicates that
+        # there hasn't been any speech detected for the configured duration.
+        #
+        # The `audio_start_ms` and `audio_end_ms` fields indicate the segment of audio after the last
+        # model response up to the triggering time, as an offset from the beginning of audio written
+        # to the input audio buffer. This means it demarcates the segment of audio that was silent and
+        # the difference between the start and end values will roughly match the configured timeout.
+        #
+        # The empty audio will be committed to the conversation as an `input_audio` item (there will be a
+        # `input_audio_buffer.committed` event) and a model response will be generated. There may be speech
+        # that didn't trigger VAD but is still detected by the model, so the model may respond with
+        # something relevant to the conversation or a prompt to continue speaking.
         variant :"input_audio_buffer.timeout_triggered", -> { OpenAI::Realtime::InputAudioBufferTimeoutTriggered }
 
         # Returned when an input audio transcription segment is identified for an item.