openai 0.106.0 → 0.108.0

data/lib/openai/helpers/local_audio/process.rb

@@ -70,6 +70,7 @@ module OpenAI
         if @error_reader && !@error_reader.closed?
           chunk = @error_reader.read_nonblock(65_536, exception: false)
           @errors = true if chunk.is_a?(String) && !chunk.empty?
+          @error_reader.close if chunk.nil?
         end
 
         !!@errors
@@ -86,7 +87,9 @@ module OpenAI
             raise PlaybackError, "Audio player exited before the input ended." if @status
           end
 
-          io.wait_readable(0.05)
+          readers = [io]
+          readers << @error_reader if @error_reader && !@error_reader.closed?
+          IO.select(readers, nil, nil, 0.05)
         end
       end
 
@@ -96,7 +99,8 @@ module OpenAI
           check_deadline
           result = io.write_nonblock(bytes.byteslice(offset, 65_536), exception: false)
           if result == :wait_writable
-            io.wait_writable(0.05)
+            readers = @error_reader && !@error_reader.closed? ? [@error_reader] : []
+            IO.select(readers, [io], nil, 0.05)
           else
             offset += result
           end
@@ -110,7 +114,13 @@ module OpenAI
         until @status
           check_deadline
           reap
-          sleep(0.01) unless @status
+          unless @status
+            if @error_reader && !@error_reader.closed?
+              @error_reader.wait_readable(0.01)
+            else
+              sleep(0.01)
+            end
+          end
         end
 
         @status

data/lib/openai/helpers/models/embedding.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "../../models/embedding"
+
+module OpenAI
+  module Models
+    class Embedding
+      alias_method :embedding_without_base64, :embedding
+      private :embedding_without_base64
+
+      def embedding
+        value = self[:embedding]
+        return embedding_without_base64 unless value.is_a?(String)
+
+        # The generated setter replaces this per-field state on assignment.
+        cached = @coerced[:embedding]
+        return cached if cached.is_a?(Array)
+
+        # Base64 embedding values contain little-endian float32 samples.
+        decoded = begin
+          value.unpack1("m0")
+        rescue ArgumentError
+          nil
+        end
+
+        return embedding_without_base64 unless decoded && (decoded.bytesize % 4).zero?
+
+        @coerced[:embedding] = decoded.unpack("e*")
+      end
+
+      # Equal embeddings still have equal raw data, so the inherited hash remains valid.
+      def ==(other)
+        return false unless super
+        return true unless self[:embedding].is_a?(String)
+
+        embedding == other.embedding
+      rescue OpenAI::Errors::ConversionError
+        true
+      end
+    end
+  end
+end

data/lib/openai/helpers/realtime/connection.rb

@@ -33,7 +33,7 @@ module OpenAI
       # Parse raw JSON as a typed server event. Valid events that are newer than this
       # SDK remain observable as {UnknownServerEvent} values.
       def parse_event(data)
-        parsed = JSON.parse(data, symbolize_names: true)
+        parsed = parse_json(data)
         type = event_type(parsed)
         unless @server_event_names.key?(type.to_s)
           return OpenAI::Realtime::UnknownServerEvent.new(data: parsed)
@@ -46,14 +46,16 @@ module OpenAI
           state: state
         )
         if (cause = coercion_error(state))
-          raise OpenAI::Errors::RealtimeProtocolError.new(data: data, cause: cause)
+          raise OpenAI::Errors::RealtimeProtocolError.new(data: data, cause: cause), cause: nil
         end
 
-        event
+        validate_wire_field_names!(event, parsed)
       rescue OpenAI::Errors::RealtimeProtocolError
         raise
+      rescue SystemStackError
+        raise OpenAI::Errors::RealtimeProtocolError.new(data: data), cause: nil
       rescue StandardError => e
-        raise OpenAI::Errors::RealtimeProtocolError.new(data: data, cause: e)
+        raise OpenAI::Errors::RealtimeProtocolError.new(data: data, cause: e), cause: nil
       end
 
       # Validate, encode, and send a typed client event.
@@ -61,6 +63,15 @@ module OpenAI
         send_raw(encode_client_event(event))
       end
 
+      private def write_text(text)
+        return super unless @recovery
+
+        # Recovery owns admission and uncertain sends; rejecting a full queue
+        # has not attempted a physical write and must leave this connection usable.
+        @recovery.write(text)
+        nil
+      end
+
       # Whether automatic recovery is opening or preparing a replacement socket.
       def reconnecting? = @recovery ? @recovery.reconnecting? : false
 
@@ -83,6 +94,10 @@ module OpenAI
           validate_discriminator!(event, @client_event_names, kind: "client")
         end
 
+        # Preserve permissive raw JSON keys while checking original typed models
+        # before union conversion can replace their identities or renamed fields.
+        validate_event_tree!(event, strict_keys: false)
+
         normalized = OpenAI::Internal::Type::Converter.dump(
           OpenAI::Realtime::RealtimeClientEvent,
           event
@@ -99,7 +114,9 @@ module OpenAI
 
         payload = OpenAI::Internal::Type::Converter.dump(OpenAI::Realtime::RealtimeClientEvent, coerced)
         validate_discriminator!(payload, @client_event_names, kind: "client")
-        JSON.generate(payload)
+        generate_json(payload)
+      rescue SystemStackError
+        raise ArgumentError, "Invalid Realtime client event.", cause: nil
       rescue StandardError => e
         raise ArgumentError.new("Invalid Realtime client event."), cause: e
       end

data/lib/openai/helpers/realtime/recovery.rb

@@ -76,7 +76,7 @@ module OpenAI
 
       def take_pending_messages
         @mutex.synchronize do
-          raise state_error("Cannot remove queued events while flushing.") if @flushing
+          raise state_error("Cannot remove queued events while flushing."), cause: nil if @flushing
 
           messages = @pending
           @pending = []
@@ -106,7 +106,7 @@ module OpenAI
 
           if @state != :open || @flushing
             if @max_queue_bytes.zero? || @pending_bytes + [text.bytesize, 1].max > @max_queue_bytes
-              raise OpenAI::Errors::RealtimeQueueFullError
+              raise OpenAI::Errors::RealtimeQueueFullError, cause: nil
             end
 
             @pending << text.dup.freeze
@@ -124,13 +124,15 @@ module OpenAI
 
       def flush_pending
         if Fiber.current.equal?(@owner_fiber)
-          raise state_error("Queue flush interrupted; remaining events were not sent.") unless flush
+          raise state_error("Queue flush interrupted; remaining events were not sent."), cause: nil unless flush
           return nil
         end
 
         reply = @mutex.synchronize do
           raise @error, cause: nil if @error
-          raise state_error("Cannot flush until the replacement connection is ready.") unless @state == :open
+          unless @state == :open
+            raise state_error("Cannot flush until the replacement connection is ready."), cause: nil
+          end
 
           register(:flush).tap { @commands << [:flush, nil, _1, @generation] }
         end
@@ -304,8 +306,14 @@ module OpenAI
             # Shutdown must not mask the operation's result or prevent cleanup.
             nil
           ensure
-            physical.abort
-            @physical = nil
+            pending_error = $ERROR_INFO
+            begin
+              physical.abort
+            rescue StandardError
+              raise if pending_error.nil?
+            ensure
+              @physical = nil
+            end
           end
         end
       end
@@ -348,7 +356,11 @@ module OpenAI
               uncertain_message: @inflight
             )
           elsif @state != :closed
-            @state = :recovering
+            if recoverable?(e) && @attempts < @max_attempts
+              @state = :recovering
+            else
+              fail_locked("Realtime reconnect stopped; the connection could not be recovered.")
+            end
           end
         end
 

data/lib/openai/helpers/realtime/translation.rb

@@ -25,36 +25,11 @@ module OpenAI
   module Realtime
     # Future event data is accessible explicitly without leaking in diagnostics.
     class UnknownTranslationServerEvent < OpenAI::Realtime::UnknownServerEvent
-      def inspect = "#<#{self.class} type=#{@type.inspect}>"
-      alias to_s inspect
-
-      private def freeze_json(value)
-        pending = [value]
-        visited = {}.compare_by_identity
-        until pending.empty?
-          item = pending.pop
-          next if visited.key?(item)
-          visited[item] = true
-          case item
-          when Hash
-            item.each { |key, val| pending.push(key, val) }
-          when Array
-            pending.concat(item)
-          end
-
-          item.freeze
-        end
-
-        value
-      end
     end
 
     # Opening does not send any events. session.close flushes remaining output;
     # read through session.closed before leaving the block to consume it.
-    class TranslationConnection < OpenAI::WebSocket::Connection
-      include OpenAI::WebSocket::Protocol
-      include OpenAI::WebSocket::GuardedConnection
-
+    class TranslationConnection < OpenAI::WebSocket::TypedConnection
       # Timeout implementations before Ruby 4 raise StandardError through the
       # scheduler. Cross transport error wrappers without changing raw callers.
       # rubocop:disable Lint/InheritException
@@ -66,21 +41,17 @@ module OpenAI
 
       # @api private
       def initialize(socket:, url:)
-        super
+        super(
+          socket: socket,
+          url: url,
+          client_event: OpenAI::Realtime::RealtimeTranslationClientEvent,
+          server_event: OpenAI::Realtime::RealtimeTranslationServerEvent
+        )
         @poisoned = false
         @closed = false
         @write_mutex = Mutex.new
         @read_state_mutex = Mutex.new
         @active_reads = 0
-        @server_event_types = OpenAI::Realtime::RealtimeTranslationServerEvent.variants.to_h do |variant|
-          [variant.fields.fetch(:type).fetch(:const).to_s, variant]
-        end
-
-        @client_event_names = discriminator_values(OpenAI::Realtime::RealtimeTranslationClientEvent)
-      end
-
-      def send_event(event)
-        send_raw(encode_client_event(event))
       end
 
       # Request a final flush and yield every trailing event, including
@@ -101,10 +72,21 @@ module OpenAI
         require "timeout"
 
         @read_state_mutex.synchronize do
+          if @finish_owner
+            raise(
+              connection_error("Translation finish must run on the existing receive owner, between reads."),
+              cause: nil
+            )
+          end
+
+          # SDK .cause accessors can expose diagnostics hidden from native rendering.
+          raise @finish_error, cause: Exception.instance_method(:cause).bind_call(@finish_error) if @finish_error
           return @finish_terminal if @finish_terminal
-          raise @finish_error if @finish_error
-          if @active_reads.positive? || @finish_requested || @finish_owner
-            raise connection_error("Translation finish must run on the existing receive owner, between reads.")
+          if @active_reads.positive? || @finish_requested
+            raise(
+              connection_error("Translation finish must run on the existing receive owner, between reads."),
+              cause: nil
+            )
           end
 
           @finish_owner = Fiber.current
@@ -114,14 +96,13 @@ module OpenAI
           Timeout.timeout(seconds, FinishTimeout) do
             write_text(encode_client_event(type: "session.close"), finish: true)
             while (event = receive)
+              terminal = event.is_a?(OpenAI::Realtime::RealtimeTranslationSessionClosedEvent)
+              @read_state_mutex.synchronize { @finish_terminal = event } if terminal
               yield(event)
-              if event.is_a?(OpenAI::Realtime::RealtimeTranslationSessionClosedEvent)
-                @read_state_mutex.synchronize { @finish_terminal = event }
-                return event
-              end
+              return event if terminal
             end
 
-            raise connection_error("Translation socket closed before session.closed.")
+            raise connection_error("Translation socket closed before session.closed."), cause: nil
           end
 
         rescue FinishTimeout
@@ -139,10 +120,10 @@ module OpenAI
       private def write_text(text, finish: false)
         @write_mutex.synchronize do
           if @finish_requested || (@finish_owner && !finish)
-            raise connection_error("Cannot send after Translation finish was requested.")
+            raise connection_error("Cannot send after Translation finish was requested."), cause: nil
           end
 
-          raise connection_error("Cannot send on a closed Realtime Translation WebSocket.") if closed?
+          raise connection_error("Cannot send on a closed Realtime Translation WebSocket."), cause: nil if closed?
           @finish_requested = true if finish
           super(text)
         end
@@ -151,7 +132,10 @@ module OpenAI
       private def read_raw_message
         @read_state_mutex.synchronize do
           if @finish_owner && @finish_owner != Fiber.current
-            raise connection_error("Translation finish must run on the existing receive owner, between reads.")
+            raise(
+              connection_error("Translation finish must run on the existing receive owner, between reads."),
+              cause: nil
+            )
           end
 
           @active_reads += 1
@@ -164,133 +148,17 @@ module OpenAI
         end
       end
 
-      private def encode_client_event(event)
-        validate_client_tree!(event)
-        union = OpenAI::Realtime::RealtimeTranslationClientEvent
-        payload = OpenAI::Internal::Type::Converter.dump(union, event)
-        type = payload[:type] || payload["type"] if payload.is_a?(Hash)
-        raise ArgumentError unless (type.is_a?(String) || type.is_a?(Symbol)) && @client_event_names.key?(type.to_s)
-
-        coerced = coerce_event(union, payload, outbound: true)
-        serialized = OpenAI::Internal::Type::Converter.dump(union, coerced)
-        validate_client_tree!(serialized, json_only: true)
-        JSON.generate(serialized, max_nesting: false)
-      rescue StandardError, SystemStackError
-        raise ArgumentError, "Invalid Realtime Translation client event.", cause: nil
-      end
-
-      # A merged string-keyed JSON event and symbol-keyed override must not
-      # silently change the command or the configuration that is sent.
-      private def validate_client_tree!(event, json_only: false)
-        visited = {}.compare_by_identity
-        pending = [event]
-        until pending.empty?
-          item = pending.pop
-          next if visited.key?(item)
-          visited[item] = true
-          case item
-          when OpenAI::Internal::Type::BaseModel
-            raise ArgumentError if json_only
-            validate_model_constants!(item)
-            pending << item.to_h
-          when Hash
-            names = {}
-            item.each do |key, value|
-              raise ArgumentError unless key.is_a?(String) || key.is_a?(Symbol)
-              name = key.to_s
-              raise ArgumentError if names.key?(name)
-              names[name] = true
-              pending << value
-            end
-
-          when Array
-            pending.concat(item)
-          when NilClass, TrueClass, FalseClass, String, Integer, Float, Symbol
-            next
-          else
-            raise ArgumentError if json_only
-          end
-        end
-      end
-
-      private def validate_model_constants!(model)
-        model.to_h.each do |name, actual|
-          key = name.is_a?(String) ? name.to_sym : name
-          field = model.class.known_fields[key]
-          next unless field
-          const = field.fetch(:const)
-          next if const == OpenAI::Internal::OMIT
-          if const.is_a?(Symbol)
-            raise ArgumentError unless (actual.is_a?(String) || actual.is_a?(Symbol)) && actual.to_s == const.to_s
-          elsif actual != const
-            raise ArgumentError
-          end
-        end
-      end
+      private :parse_event
 
-      private def parse_event(data)
-        parsed = JSON.parse(data, symbolize_names: true, max_nesting: false)
-        type = event_type(parsed, message: "Realtime Translation server event must be an object with a string type")
-        model = @server_event_types[type.to_s]
-        unless model
-          return OpenAI::Realtime::UnknownTranslationServerEvent.new(data: parsed)
-        end
+      private def coerce_client_event(payload) = coerce_event(@client_event, payload, outbound: true)
 
-        # The converter copies unknown wire fields after known ones. A wire
-        # key spelled like a renamed Ruby field must not overwrite typed data.
-        model.fields.each do |name, field|
-          raise ArgumentError if name != field.fetch(:api_name) && parsed.key?(name)
-        end
+      private def coerce(type, value) = coerce_event(type, value)
 
-        coerce_event(OpenAI::Realtime::RealtimeTranslationServerEvent, parsed)
-      rescue StandardError, SystemStackError
-        raise OpenAI::Errors::TranslationProtocolError.new, cause: nil
-      end
+      private def client_event_error_message = "Invalid Realtime Translation client event."
 
-      private def coerce_event(union, payload, outbound: false)
-        state = OpenAI::Internal::Type::Converter.new_coerce_state(request_only: outbound)
-        event = OpenAI::Internal::Type::Converter.coerce(union, payload, state: state)
-        raise ArgumentError if state[:error] || !state.fetch(:exactness).fetch(:no).zero?
-        ancestors = {}.compare_by_identity
-        pending = [[event, false]]
-        until pending.empty?
-          value, exiting = pending.pop
-          if exiting
-            ancestors.delete(value)
-            next
-          end
+      private def unknown_server_event(payload) = OpenAI::Realtime::UnknownTranslationServerEvent.new(data: payload)
 
-          children = case value
-          when OpenAI::Internal::Type::BaseModel
-            data = value.to_h
-            validate_model_constants!(value)
-            value.class.fields.each do |name, field|
-              const = field.fetch(:const)
-              if field.fetch(:required) &&
-                  field.fetch(:mode) != (outbound ? :coerce : :dump) &&
-                  (!outbound || const == OpenAI::Internal::OMIT) &&
-                  !data.key?(name)
-                raise ArgumentError
-              end
-            end
-
-            data.values
-          when Hash
-            value.values
-          when Array
-            value
-          else
-            next
-          end
-
-          raise ArgumentError if ancestors.key?(value)
-          ancestors[value] = true
-          pending << [value, true]
-          children.each { |child| pending << [child, false] }
-        end
-
-        event
-      end
+      private def protocol_error = OpenAI::Errors::TranslationProtocolError.new
 
       private def transport_error = OpenAI::Errors::TranslationConnectionError.new(url: @url)
       private def failed_read_message = "Cannot read from a failed Realtime Translation WebSocket."

data/lib/openai/helpers/realtime/unknown_server_event.rb

@@ -4,6 +4,8 @@ module OpenAI
   module Realtime
     # A valid JSON event whose discriminator is newer than this SDK version.
     class UnknownServerEvent
+      include OpenAI::WebSocket::Protocol
+
       # @return [Symbol]
       attr_reader :type
 
@@ -25,20 +27,11 @@ module OpenAI
       # @return [Hash{Symbol=>Object}]
       def to_h = @data
 
-      private def freeze_json(value)
-        case value
-        when Hash
-          value.each do |key, item|
-            freeze_json(key)
-            freeze_json(item)
-          end
+      # Remote values, including the discriminator, require explicit access.
+      def inspect = "#<#{self.class}>"
 
-        when Array
-          value.each { |item| freeze_json(item) }
-        end
+      alias to_s inspect
 
-        value.freeze
-      end
     end
   end
 end

data/lib/openai/helpers/responses_websocket/connection.rb

@@ -51,7 +51,13 @@ module OpenAI
         assert_owner!
         raise connection_error("Cannot send on a closed Responses WebSocket.") if poisoned? || closed?
 
-        write_encoded(JSON.generate(encode_client_event(event)))
+        encoded = begin
+          generate_json(encode_client_event(event))
+        rescue SystemStackError
+          raise OpenAI::Errors::ResponsesClientEventError.new, cause: nil
+        end
+
+        write_encoded(encoded)
       rescue OpenAI::Errors::ResponsesConnectionError,
         OpenAI::Errors::ResponsesClientEventError,
         OpenAI::Errors::ResponsesSendError
@@ -107,21 +113,22 @@ module OpenAI
       def closed? = @state == :closed || super
 
       private def parse_event(data)
-        parsed = JSON.parse(data, symbolize_names: true)
+        parsed = parse_json(data)
         type = event_type(parsed, message: "Responses server event must be a JSON object")
         unless @server_event_names.key?(type.to_s)
           return OpenAI::Responses::UnknownServerEvent.new(data: parsed)
         end
 
         state = OpenAI::Internal::Type::Converter.new_coerce_state
-        OpenAI::Internal::Type::Converter.coerce(
+        event = OpenAI::Internal::Type::Converter.coerce(
           OpenAI::Responses::ResponsesServerEvent,
           parsed,
           state: state
         )
+        validate_wire_field_names!(event, parsed)
       rescue OpenAI::Errors::ResponsesProtocolError
         raise
-      rescue StandardError
+      rescue StandardError, SystemStackError
         raise OpenAI::Errors::ResponsesProtocolError.new, cause: nil
       end
 
@@ -209,34 +216,33 @@ module OpenAI
         raise connection_error("Responses WebSocket connections are single-owner.")
       end
 
-      private def validate_event_tree!(value, active = {}.compare_by_identity)
-        case value
-        when OpenAI::Internal::Type::BaseModel
-          guard_cycle!(value, active)
-          begin
-            data = value.to_h
-            reject_duplicate_serialized_model_keys!(value.class, data)
-            validate_event_tree!(data, active)
-          ensure
+      private def validate_event_tree!(value)
+        active = {}.compare_by_identity
+        pending = [[value, false]]
+        until pending.empty?
+          value, exiting = pending.pop
+          if exiting
             active.delete(value)
+            next
           end
 
-        when Hash
-          guard_cycle!(value, active)
-          reject_duplicate_semantic_keys!(value)
-          begin
-            value.each_value { |item| validate_event_tree!(item, active) }
-          ensure
-            active.delete(value)
+          children = case value
+          when OpenAI::Internal::Type::BaseModel
+            data = value.to_h
+            reject_duplicate_serialized_model_keys!(value.class, data)
+            [data]
+          when Hash
+            reject_duplicate_semantic_keys!(value)
+            value.values
+          when Array
+            value
+          else
+            next
           end
 
-        when Array
           guard_cycle!(value, active)
-          begin
-            value.each { |item| validate_event_tree!(item, active) }
-          ensure
-            active.delete(value)
-          end
+          pending << [value, true]
+          children.reverse_each { |child| pending << [child, false] }
         end
 
         nil
@@ -272,18 +278,33 @@ module OpenAI
       end
 
       private def normalize_event_keys(value)
-        case value
-        when Hash
-          value.to_h do |key, item|
+        return value unless value.is_a?(Hash) || value.is_a?(Array)
+
+        result = value.is_a?(Hash) ? {} : []
+        copies = {}.compare_by_identity
+        copies[value] = result
+        pending = [[value, result]]
+        until pending.empty?
+          source, destination = pending.pop
+          entries = source.is_a?(Hash) ? source.each_pair : source.each_with_index.lazy.map { |item, index|
+            [index, item]
+          }
+          entries.each do |key, item|
+            if item.is_a?(Hash) || item.is_a?(Array)
+              unless copies.key?(item)
+                copies[item] = item.is_a?(Hash) ? {} : []
+                pending << [item, copies.fetch(item)]
+              end
+
+              item = copies.fetch(item)
+            end
+
             normalized_key = key.is_a?(String) ? key.to_sym : key
-            [normalized_key, normalize_event_keys(item)]
+            destination[normalized_key] = item
           end
-
-        when Array
-          value.map { |item| normalize_event_keys(item) }
-        else
-          value
         end
+
+        result
       end
 
       private def connection_error(message)

data/lib/openai/helpers/responses_websocket/incremental.rb

@@ -11,6 +11,8 @@ module OpenAI
     # are retained exactly as received, never filled from provisional output.
     # Call reset to discard all retained state.
     class IncrementalResponse
+      include OpenAI::WebSocket::Protocol
+
       attr_reader :phase
 
       def initialize
@@ -236,10 +238,12 @@ module OpenAI
       # references. Returned snapshots and incoming events must not share strings.
       def copy(value)
         data = OpenAI::Internal::Type::BaseModel.recursively_to_h(value, convert: false)
-        data = JSON.parse(JSON.generate(data), symbolize_names: true)
+        data = parse_json(generate_json(data))
         return data unless value.is_a?(OpenAI::Internal::Type::BaseModel)
 
         OpenAI::Internal::Type::Converter.coerce(value.class, data)
+      rescue SystemStackError
+        raise SessionError, "Could not copy the Responses WebSocket event.", cause: nil
       end
     end
   end