openai 0.85.0 → 0.86.0

data/lib/openai/helpers/websocket/connection_manager.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module WebSocket
+    # Shared block-scoped WebSocket opening and cleanup.
+    #
+    # @api private
+    class ConnectionManager
+      RESERVED_TRANSPORT_OPTIONS = [
+        :alpn_protocols,
+        :headers,
+        :hostname,
+        :port,
+        :protocol,
+        :scheme,
+        :ssl_context,
+        :timeout,
+        :url
+      ].freeze
+
+      # @api private
+      def initialize(
+        transport:,
+        transport_options:,
+        default_transport:,
+        connection_class:,
+        request:,
+        block_error_message:,
+        abort_after_block:,
+        transport_error_message: "transport must respond to open",
+        reserved_options_error_message: nil
+      )
+        @transport = transport
+        @default_transport = default_transport
+        @connection_class = connection_class
+        @request = request
+        @block_error_message = block_error_message
+        @abort_after_block = abort_after_block
+        @transport_error_message = transport_error_message
+        @reserved_options_error_message = reserved_options_error_message
+        @transport_options = validated_transport_options(transport_options)
+      end
+
+      # @api private
+      def open
+        raise ArgumentError, @block_error_message unless block_given?
+
+        transport = @transport || @default_transport.call
+        raise ArgumentError, @transport_error_message unless transport.respond_to?(:open)
+
+        @request.call do |request, mark_handshake_completed|
+          transport
+            .open(
+              url: request.fetch(:url),
+              headers: request.fetch(:headers),
+              timeout: request.fetch(:timeout),
+              **@transport_options
+            ) do |socket|
+              mark_handshake_completed.call
+              connection = @connection_class.new(socket: socket, url: request.fetch(:url))
+              begin
+                yield(connection)
+              ensure
+                cleanup(connection)
+              end
+            end
+        end
+      end
+
+      private def validated_transport_options(transport_options)
+        options = transport_options.dup.freeze
+        reserved = options.keys.select do |key|
+          (key.is_a?(String) || key.is_a?(Symbol)) && RESERVED_TRANSPORT_OPTIONS.include?(key.to_sym)
+        end
+
+        unless reserved.empty?
+          message = if @reserved_options_error_message
+            @reserved_options_error_message.call(reserved)
+          else
+            "transport_options cannot include #{reserved.map(&:inspect).join(", ")}"
+          end
+
+          raise ArgumentError, message
+        end
+
+        options
+      end
+
+      private def cleanup(connection)
+        pending_error = $ERROR_INFO
+        begin
+          if @abort_after_block.call(connection, pending_error)
+            connection.abort
+          else
+            connection.close
+          end
+
+        rescue StandardError
+          raise if pending_error.nil?
+        end
+      end
+    end
+  end
+end

data/lib/openai/helpers/websocket/errors.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Errors
+    # Base class for SDK WebSocket connection failures.
+    #
+    # @api private
+    class WebSocketConnectionError < OpenAI::Errors::Error
+      attr_reader :url, :http_status
+
+      def cause = @cause.nil? ? super : @cause
+
+      # @api private
+      def initialize(url:, message: nil, cause: nil, http_status: nil)
+        @url = sanitized_error_url(url)
+        @cause = cause
+        @http_status = http_status
+        super(message || default_message)
+      end
+
+      private def default_message = "WebSocket connection error."
+
+      private def sanitized_error_url(url) = url
+    end
+
+    # Base class for malformed WebSocket messages.
+    #
+    # @api private
+    class WebSocketProtocolError < OpenAI::Errors::Error
+    end
+  end
+end

data/lib/openai/helpers/websocket/protocol.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module WebSocket
+    # Shared helpers for discriminated JSON WebSocket events.
+    #
+    # @api private
+    module Protocol
+      private def discriminator_values(union)
+        union.variants.to_h do |variant|
+          value = variant.fields.fetch(:type).fetch(:const)
+          [value.to_s, true]
+        end
+      end
+
+      private def event_type(event, message:)
+        raise ArgumentError, message unless event.is_a?(Hash)
+
+        type = event[:type]
+        return type if type.is_a?(String) || type.is_a?(Symbol)
+
+        raise ArgumentError, message
+      end
+    end
+  end
+end

data/lib/openai/helpers/websocket.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Internal, product-neutral WebSocket runtime shared by SDK WebSocket APIs.
+# Product helpers keep their event models and resource facades separate.
+require_relative "websocket/errors"
+require_relative "websocket/connection"
+require_relative "websocket/connection_manager"
+require_relative "websocket/protocol"
+require_relative "websocket/async_websocket_transport"
+require_relative "websocket/client_request"

data/lib/openai/internal/conversation_cursor_page.rb

@@ -5,7 +5,7 @@ module OpenAI
     # @generic Elem
     #
     # @example
-    #   if conversation_cursor_page.has_next?
+    #   if conversation_cursor_page.next_page?
     #     conversation_cursor_page = conversation_cursor_page.next_page
     #   end
     #

data/lib/openai/internal/cursor_page.rb

@@ -5,7 +5,7 @@ module OpenAI
     # @generic Elem
     #
     # @example
-    #   if cursor_page.has_next?
+    #   if cursor_page.next_page?
     #     cursor_page = cursor_page.next_page
     #   end
     #

data/lib/openai/internal/next_cursor_page.rb

@@ -5,7 +5,7 @@ module OpenAI
     # @generic Elem
     #
     # @example
-    #   if next_cursor_page.has_next?
+    #   if next_cursor_page.next_page?
     #     next_cursor_page = next_cursor_page.next_page
     #   end
     #

data/lib/openai/internal/page.rb

@@ -5,7 +5,7 @@ module OpenAI
     # @generic Elem
     #
     # @example
-    #   if page.has_next?
+    #   if page.next_page?
     #     page = page.next_page
     #   end
     #

data/lib/openai/internal/transport/base_client.rb

@@ -3,6 +3,7 @@
 require "ipaddr"
 
 require_relative "../logging"
+require_relative "../type/duplicable_response_carrier"
 
 module OpenAI
   module Internal
@@ -413,7 +414,10 @@ module OpenAI
 
           path = OpenAI::Internal::Util.interpolate_path(uninterpolated_path)
 
-          query = OpenAI::Internal::Util.deep_merge(req[:query].to_h, opts[:extra_query].to_h)
+          query = OpenAI::Internal::Transport::RequestBodyMerge.merge(
+            req[:query].to_h,
+            opts[:extra_query].to_h
+          )
 
           url = OpenAI::Internal::Util.join_parsed_uri(
             @base_url_components,
@@ -473,7 +477,7 @@ module OpenAI
           in :get | :head | :options | :trace
             nil
           else
-            OpenAI::Internal::Util.deep_merge(*[req[:body], opts[:extra_body]].compact)
+            OpenAI::Internal::Transport::RequestBodyMerge.merge(req[:body], opts[:extra_body])
           end
 
           # Generated methods always pass `req[:body]` for operations that define a
@@ -498,6 +502,22 @@ module OpenAI
           self.class.request_body_replayable?(request[:body])
         end
 
+        # A connection failure has an unknown outcome unless the transport can
+        # prove that no request bytes were sent. Retrying an ambiguous failure
+        # is only safe when the HTTP method itself is idempotent or the caller
+        # supplied a stable idempotency key.
+        #
+        # @api private
+        private def request_retryable_after_connection_error?(request, error:)
+          return true if false.equal?(error.request_may_have_been_sent?)
+          return true if Net::HTTP::IDEMPOTENT_METHODS_.include?(request.fetch(:method).to_s.upcase)
+
+          idempotency_header = @idempotency_header || "idempotency-key"
+          request.fetch(:headers).any? do |name, value|
+            name.to_s.casecmp?(idempotency_header) && !value.to_s.empty?
+          end
+        end
+
         # @api private
         #
         # @param headers [Hash{String=>String}]
@@ -592,6 +612,7 @@ module OpenAI
           authorized_url = url.class.new(*URI.split(url.to_s))
           prepared_request = request
           trusted_origin = request[:redirect_trusted_origin]
+          request_dispatched = false
 
           begin
             encoded_headers, encoded_body = OpenAI::Internal::Util.encode_content(
@@ -653,6 +674,7 @@ module OpenAI
               timeout: timeout
             )
             log_context.request_started(input, redirect_count: redirect_count)
+            request_dispatched = true
             http_response = @requester.execute(input)
             unless http_response.is_a?(OpenAI::HTTPClient::Response)
               raise TypeError, "`http_client#execute` must return an OpenAI::HTTPClient::Response"
@@ -688,6 +710,13 @@ module OpenAI
             )
           end
 
+          if status.is_a?(OpenAI::Errors::APIConnectionError) &&
+              (retry_count >= max_retries ||
+                (request_dispatched &&
+                  !request_retryable_after_connection_error?(prepared_request, error: status)))
+            raise status
+          end
+
           case status
           in ..299
             http_response
@@ -720,8 +749,6 @@ module OpenAI
               send_retry_header: send_retry_header,
               &context_provider
             )
-          in OpenAI::Errors::APIConnectionError if retry_count >= max_retries
-            raise status
           in (400..) | OpenAI::Errors::APIConnectionError
             self.class.reap_connection!(status, stream: stream)
 
@@ -874,12 +901,18 @@ module OpenAI
 
           unwrap = req[:unwrap]
           response_metadata = response.metadata
+          direct_binary_response = model.is_a?(Class) && model <= StringIO
           include_raw_body = req[:options].to_h[:include_raw_body] == true &&
             (req[:page] ||
-              (model.is_a?(Class) && model <= OpenAI::Internal::Type::BaseModel) ||
+              (model.is_a?(Class) &&
+                (model <= OpenAI::Internal::Type::BaseModel || direct_binary_response)) ||
               model.is_a?(OpenAI::Internal::Type::Union))
           raw_body = nil
-          decoded = if include_raw_body
+          decoded = if direct_binary_response
+            body = response.body.to_a.join
+            raw_body = body if include_raw_body
+            StringIO.new(body)
+          elsif include_raw_body
             OpenAI::Internal::Util.decode_content(response.headers, stream: response.body) do |body|
               raw_body = body
             end
@@ -887,11 +920,11 @@ module OpenAI
             OpenAI::Internal::Util.decode_content(response.headers, stream: response.body)
           end
 
-          if include_raw_body && !decoded.is_a?(StringIO)
+          if include_raw_body && (!decoded.is_a?(StringIO) || direct_binary_response)
             response_metadata = OpenAI::ResponseMetadata.new(
               status: response.status,
               headers: response.headers,
-              body: raw_body&.freeze
+              body: decoded.is_a?(StringIO) ? raw_body&.dup&.freeze : raw_body&.freeze
             )
           end
 
@@ -912,6 +945,10 @@ module OpenAI
             OpenAI::Internal::Type::Converter.coerce(model, unwrapped).tap do |result|
               if result.is_a?(OpenAI::Internal::Type::BaseModel)
                 result._set_last_response(response_metadata)
+              elsif result.is_a?(StringIO) && direct_binary_response
+                result
+                  .extend(OpenAI::ResponseCarrier, OpenAI::Internal::Type::DuplicableResponseCarrier)
+                  ._set_last_response(response_metadata)
               end
             end
           end

data/lib/openai/internal/transport/request_body_merge.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Internal
+    module Transport
+      # @api private
+      #
+      # Reconciles exact string/symbol counterparts while preserving the
+      # existing deep-merge behavior for request body overrides.
+      module RequestBodyMerge
+        class << self
+          # @api private
+          #
+          # @param body [Object, nil]
+          # @param extra_body [Object, nil]
+          #
+          # @return [Object, nil]
+          def merge(body, extra_body)
+            values = [body, extra_body].compact
+            return OpenAI::Internal::Util.deep_merge(*values) unless values.length == 2
+
+            merge_hashes(values.fetch(0), values.fetch(1))
+          end
+
+          private
+
+          # @api private
+          #
+          # @param body [Object]
+          # @param extra_body [Object]
+          # @param key_source [Object] original body layer used for counterpart lookup
+          #
+          # @return [Object]
+          def merge_hashes(body, extra_body, key_source: body)
+            unless body.is_a?(Hash) && extra_body.is_a?(Hash)
+              return OpenAI::Internal::Util.deep_merge(body, extra_body)
+            end
+
+            merged = body.dup
+            wire_keys = {}
+            source = key_source.is_a?(Hash) ? key_source : {}
+            source.each_key do |key|
+              wire_keys[key.to_s] ||= key if key.is_a?(String) || key.is_a?(Symbol)
+            end
+
+            extra_body.each do |extra_key, extra_value|
+              key = extra_key
+              if !merged.key?(extra_key) && (extra_key.is_a?(String) || extra_key.is_a?(Symbol))
+                key = wire_keys.fetch(extra_key.to_s, extra_key)
+              end
+
+              merged[key] = if merged.key?(key)
+                body_value = merged.fetch(key)
+                if body_value.is_a?(Hash) && extra_value.is_a?(Hash)
+                  source_value = source.fetch(key, nil)
+                  merge_hashes(body_value, extra_value, key_source: source_value)
+                else
+                  extra_value
+                end
+              else
+                extra_value
+              end
+            end
+
+            merged
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openai/internal/type/base_page.rb

@@ -59,8 +59,8 @@ module OpenAI
         # @param page_data [Object]
         def initialize(client:, req:, response_metadata:, page_data:)
           options = req[:options].to_h
-          query = OpenAI::Internal::Util
-            .deep_merge(req[:query].to_h, options[:extra_query].to_h)
+          query = OpenAI::Internal::Transport::RequestBodyMerge
+            .merge(req[:query].to_h, options[:extra_query].to_h)
             .to_h { |key, value| [key == "after" ? :after : key, value] }
 
           @client = client

data/lib/openai/internal/type/base_stream.rb

@@ -19,6 +19,14 @@ module OpenAI
         # @return [Hash{String=>String}]
         def headers = last_response.headers
 
+        # The ID of the API request, returned via the x-request-id response
+        # header.
+        #
+        # @api public
+        #
+        # @return [String, nil]
+        def _request_id = last_response.request_id
+
         # Metadata from the HTTP response that opened this stream.
         #
         # @api public

data/lib/openai/internal/type/converter.rb

@@ -122,7 +122,10 @@ module OpenAI
           #
           # @return [Hash{Symbol=>Object}]
           def meta_info(type_info, spec)
-            [spec, type_info].grep(Hash).first.to_h.except(:const, :enum, :union, :nil?)
+            [type_info, spec]
+              .grep(Hash)
+              .reduce({}, :merge)
+              .except(:const, :enum, :union, :nil?)
           end
 
           # @api private
@@ -208,7 +211,12 @@ module OpenAI
                   return value
                 else
                   Kernel.then do
-                    return Integer(value).tap { exactness[:maybe] += 1 }
+                    # Wire text is decimal. `Integer(str)` would read a leading `0` as
+                    # octal and `0x`/`0b` as other bases, so "010" became 8 and "08"
+                    # failed outright. Non-strings keep the unbased call, which accepts
+                    # Float and other numerics that reject an explicit base.
+                    coerced = value.is_a?(String) ? Integer(value, 10) : Integer(value)
+                    return coerced.tap { exactness[:maybe] += 1 }
                   rescue ArgumentError, TypeError => e
                     state[:error] = e
                   end

data/lib/openai/internal/type/duplicable_response_carrier.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Internal
+    module Type
+      # Preserve response metadata behavior when callers duplicate a direct
+      # binary response.
+      #
+      # @api private
+      module DuplicableResponseCarrier
+        # @api private
+        #
+        # @return [StringIO]
+        def dup(...)
+          super.tap do |copy|
+            copy.extend(OpenAI::ResponseCarrier, OpenAI::Internal::Type::DuplicableResponseCarrier)
+            copy._set_last_response(last_response)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openai/internal/type/file_input.rb

@@ -41,7 +41,7 @@ module OpenAI
         class << self
           # @api private
           #
-          # @param value [StringIO, String, Object]
+          # @param value [Pathname, StringIO, IO, String, OpenAI::FilePart, Object]
           #
           # @param state [Hash{Symbol=>Object}] .
           #
@@ -55,14 +55,14 @@ module OpenAI
           #
           #   @option state [Integer] :branched
           #
-          # @return [StringIO, Object]
+          # @return [Pathname, StringIO, IO, OpenAI::FilePart, Object]
           def coerce(value, state:)
             exactness = state.fetch(:exactness)
             case value
             in String
               exactness[:yes] += 1
               StringIO.new(value)
-            in StringIO
+            in Pathname | StringIO | IO | OpenAI::FilePart
               exactness[:yes] += 1
               value
             else

data/lib/openai/internal/type/union.rb

@@ -100,8 +100,25 @@ module OpenAI
             return nil if key == OpenAI::Internal::OMIT
 
             key = key.to_sym if key.is_a?(String)
-            _, found = known_variants.find { |k,| k == key }
-            found&.call
+            _, found = known_variants.find { |k,| !k.nil? && k == key }
+            return found.call if found
+
+            known_variants.each do |variant_key, variant_fn|
+              next unless variant_key.nil?
+
+              target = variant_fn.call
+              next unless target.is_a?(Class) && target <= OpenAI::Internal::Type::BaseModel
+
+              field = target.known_fields[@discriminator]
+              next unless field
+
+              type = field.fetch(:type_fn).call
+              next unless OpenAI::Internal::Type::Enum === type
+
+              return target if type === key
+            end
+
+            OpenAI::Internal::Type::Unknown
           else
             nil
           end
@@ -167,7 +184,7 @@ module OpenAI
           exactness = state.fetch(:exactness)
 
           alternatives = []
-          known_variants.each do |_, variant_fn|
+          known_variants.each_with_index do |(_, variant_fn), index|
             target = variant_fn.call
             exact = state[:exactness] = {yes: 0, no: 0, maybe: 0}
             state[:branched] += 1
@@ -180,7 +197,10 @@ module OpenAI
               state[:error] = error || previous_error
               return coerced
             elsif maybe.positive?
-              alternatives << [[-yes, -maybe, no], exact, coerced, error]
+              # `Array#sort_by!` is not stable, so equally-ranked variants would
+              # otherwise be ordered arbitrarily. Break ties on declaration order
+              # to keep the chosen variant the same across platforms and runs.
+              alternatives << [[-yes, -maybe, no, index], exact, coerced, error]
             end
           end