openai 0.84.0 → 0.86.0

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

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Responses
+    # A live, typed Responses WebSocket connection.
+    class Connection < OpenAI::WebSocket::Connection
+      include OpenAI::WebSocket::Protocol
+
+      # @return [OpenAI::Responses::ConnectionResources::Response]
+      attr_reader :response
+
+      # @api private
+      def initialize(socket:, url:)
+        super
+        @poisoned = false
+        @state = :open
+        @owner_thread = Thread.current.object_id
+        @reading = false
+        @server_event_names = discriminator_values(OpenAI::Responses::ResponsesServerEvent)
+        @response = OpenAI::Responses::ConnectionResources::Response.new(self)
+      end
+
+      def each
+        return enum_for(__method__) unless block_given?
+
+        with_read_lease do
+          while (event = read_one)
+            yield(event)
+          end
+        end
+
+        self
+      end
+
+      def receive
+        with_read_lease { read_one }
+      end
+
+      # Receive the next raw WebSocket message while preserving Responses'
+      # single-owner and one-reader guarantees.
+      #
+      # @api private
+      def receive_raw
+        with_read_lease { read_raw }
+      end
+
+      # Validate, encode, and send a Responses client event.
+      #
+      # @return [nil]
+      def send_event(event)
+        assert_owner!
+        raise connection_error("Cannot send on a closed Responses WebSocket.") if poisoned? || closed?
+
+        write_encoded(JSON.generate(encode_client_event(event)))
+      rescue OpenAI::Errors::ResponsesConnectionError,
+        OpenAI::Errors::ResponsesClientEventError,
+        OpenAI::Errors::ResponsesSendError
+        raise
+      rescue StandardError
+        raise OpenAI::Errors::ResponsesClientEventError.new, cause: nil
+      end
+
+      # Send an already encoded text message while preserving Responses'
+      # single-owner and terminal-write guarantees.
+      #
+      # @api private
+      def send_raw(data)
+        assert_owner!
+        raise connection_error("Cannot send on a closed Responses WebSocket.") if poisoned? || closed?
+
+        super
+      end
+
+      # @api private
+      def poisoned? = @poisoned
+
+      def close(code: 1000, reason: "")
+        assert_owner!
+        return if socket_closed?
+        return abort if poisoned?
+
+        super
+        @state = :closed
+        nil
+      rescue OpenAI::Errors::ResponsesConnectionError
+        raise
+      rescue StandardError
+        @state = :closed
+        raise OpenAI::Errors::ResponsesConnectionError.new(url: @url), cause: nil
+      end
+
+      # @api private
+      def abort
+        assert_owner!
+        return if socket_closed?
+
+        super
+        @state = :closed
+        nil
+      rescue OpenAI::Errors::ResponsesConnectionError
+        raise
+      rescue StandardError
+        @state = :closed
+        raise OpenAI::Errors::ResponsesConnectionError.new(url: @url), cause: nil
+      end
+
+      def closed? = @state == :closed || super
+
+      private def parse_event(data)
+        parsed = JSON.parse(data, symbolize_names: true)
+        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(
+          OpenAI::Responses::ResponsesServerEvent,
+          parsed,
+          state: state
+        )
+      rescue OpenAI::Errors::ResponsesProtocolError
+        raise
+      rescue StandardError
+        raise OpenAI::Errors::ResponsesProtocolError.new, cause: nil
+      end
+
+      private def read_one
+        data = read_raw
+        return nil if data.nil?
+
+        parse_event(data.to_str)
+      rescue OpenAI::Errors::ResponsesProtocolError, OpenAI::Errors::ResponsesConnectionError
+        raise
+      rescue StandardError
+        raise OpenAI::Errors::ResponsesConnectionError.new(url: @url), cause: nil
+      end
+
+      private def read_raw
+        assert_owner!
+        return nil if closed?
+
+        data = begin
+          read_raw_message
+        rescue OpenAI::Errors::ResponsesConnectionError
+          @poisoned = true
+          raise
+        rescue StandardError
+          @poisoned = true
+          raise OpenAI::Errors::ResponsesConnectionError.new(url: @url), cause: nil
+        end
+
+        @state = :closed if data.nil?
+        data
+      end
+
+      private def encode_client_event(event)
+        validate_event_tree!(event)
+        payload = if event.is_a?(Hash)
+          OpenAI::Internal::Type::Unknown.dump(event, state: {can_retry: true})
+        else
+          OpenAI::Internal::Type::Converter.dump(OpenAI::Responses::ResponsesClientEvent, event)
+        end
+
+        raise OpenAI::Errors::ResponsesClientEventError.new unless payload.is_a?(Hash)
+
+        normalize_event_keys(payload)
+      rescue OpenAI::Errors::ResponsesClientEventError
+        raise
+      rescue StandardError
+        raise OpenAI::Errors::ResponsesClientEventError.new, cause: nil
+      end
+
+      private def write_encoded(data)
+        send_raw(data)
+      end
+
+      private def write_text(text)
+        super
+      rescue StandardError
+        @poisoned = true
+        raise OpenAI::Errors::ResponsesSendError.new(url: @url), cause: nil
+      end
+
+      private def with_read_lease
+        acquired = false
+        assert_owner!
+        if @reading
+          raise connection_error("Responses WebSocket already has an active reader.")
+        end
+
+        @reading = true
+        acquired = true
+        yield
+      ensure
+        @reading = false if acquired
+      end
+
+      private def assert_owner!
+        return if @owner_thread == Thread.current.object_id
+
+        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
+            active.delete(value)
+          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)
+          end
+
+        when Array
+          guard_cycle!(value, active)
+          begin
+            value.each { |item| validate_event_tree!(item, active) }
+          ensure
+            active.delete(value)
+          end
+        end
+
+        nil
+      end
+
+      private def reject_duplicate_serialized_model_keys!(model, data)
+        serialized_keys = data.keys.map do |key|
+          name = key.is_a?(String) ? key.to_sym : key
+          field = model.known_fields[name]
+          field ? field.fetch(:api_name) : name
+        end
+
+        return if serialized_keys.map(&:to_s).uniq.length == serialized_keys.length
+
+        raise OpenAI::Errors::ResponsesClientEventError.new
+      end
+
+      private def guard_cycle!(value, active)
+        raise OpenAI::Errors::ResponsesClientEventError.new if active.key?(value)
+
+        active[value] = true
+      end
+
+      private def reject_duplicate_semantic_keys!(payload)
+        keys = payload.keys
+        unless keys.all? { |key| key.is_a?(String) || key.is_a?(Symbol) }
+          raise OpenAI::Errors::ResponsesClientEventError.new
+        end
+
+        return if keys.map(&:to_s).uniq.length == keys.length
+
+        raise OpenAI::Errors::ResponsesClientEventError.new
+      end
+
+      private def normalize_event_keys(value)
+        case value
+        when Hash
+          value.to_h do |key, item|
+            normalized_key = key.is_a?(String) ? key.to_sym : key
+            [normalized_key, normalize_event_keys(item)]
+          end
+
+        when Array
+          value.map { |item| normalize_event_keys(item) }
+        else
+          value
+        end
+      end
+
+      private def connection_error(message)
+        OpenAI::Errors::ResponsesConnectionError.new(url: @url, message: message)
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Responses
+    # Internal block-scoped lifecycle manager for Responses WebSocket connections.
+    #
+    # @api private
+    class ConnectionManager < OpenAI::WebSocket::ConnectionManager
+      # @api private
+      def initialize(client:, websocket_base_url:, transport:, request_options:, transport_options:)
+        base_url = websocket_base_url&.to_s&.dup&.freeze
+        request = lambda do |&request_block|
+          client.with_responses_websocket_connection_request(
+            websocket_base_url: base_url,
+            options: request_options,
+            &request_block
+          )
+        end
+
+        super(
+          transport: transport,
+          transport_options: transport_options,
+          default_transport: -> { OpenAI::Responses::Transports::AsyncWebSocket.new },
+          connection_class: OpenAI::Responses::Connection,
+          request: request,
+          block_error_message: "A block is required to open a Responses WebSocket.",
+          abort_after_block: lambda do |connection, pending_error|
+            !pending_error.nil? || connection.poisoned?
+          end
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Responses
+    module ConnectionResources
+      class Response
+        # @api private
+        def initialize(connection)
+          @connection = connection
+        end
+
+        # Send a response.create event over this connection.
+        #
+        # @return [nil]
+        def create(**params)
+          event_params = params.reject { |key, _value| key == :type || key == "type" }
+          @connection.send_event(**event_params, type: :"response.create")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Errors
+    # Raised when a Responses WebSocket cannot be opened or used.
+    class ResponsesConnectionError < OpenAI::Errors::WebSocketConnectionError
+      # @return [Exception, nil]
+      def cause = nil
+
+      private def default_message = "Responses WebSocket connection error."
+
+      private def sanitized_error_url(url)
+        sanitized = url.dup
+        sanitized.user = nil if sanitized.respond_to?(:user=)
+        sanitized.password = nil if sanitized.respond_to?(:password=)
+        sanitized.query = nil if sanitized.respond_to?(:query=)
+        sanitized.fragment = nil if sanitized.respond_to?(:fragment=)
+        sanitized
+      rescue ArgumentError, URI::Error
+        URI("wss://invalid")
+      end
+    end
+
+    # Raised when a Responses WebSocket message is malformed.
+    class ResponsesProtocolError < OpenAI::Errors::WebSocketProtocolError
+      def cause = nil
+
+      # @api private
+      def initialize
+        super("Invalid Responses WebSocket event.")
+      end
+    end
+
+    # Raised before a malformed client event can be written.
+    class ResponsesClientEventError < OpenAI::Errors::Error
+      def cause = nil
+
+      # @api private
+      def initialize
+        super("Invalid Responses WebSocket client event.")
+      end
+    end
+
+    # Raised when a write may or may not have reached the server.
+    class ResponsesSendError < ResponsesConnectionError
+      # @return [Symbol, :unknown]
+      attr_reader :outcome
+
+      # @api private
+      def initialize(url:)
+        @outcome = :unknown
+        super(url: url, message: "Responses WebSocket send outcome is unknown.")
+      end
+    end
+  end
+end

data/lib/openai/helpers/responses_websocket/resources/responses_extension.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Helpers
+    module ResponsesWebSocket
+      # Ruby-native WebSocket entry point layered onto the generated Responses resource.
+      module Connections
+        def connect(
+          websocket_base_url: nil,
+          request_options: nil,
+          transport: nil,
+          transport_options: {},
+          &block
+        )
+          raise ArgumentError, "A block is required to open a Responses WebSocket." unless block
+
+          manager = OpenAI::Responses::ConnectionManager.new(
+            client: @client,
+            websocket_base_url: websocket_base_url,
+            transport: transport,
+            request_options: request_options,
+            transport_options: transport_options
+          )
+          manager.open(&block)
+        end
+      end
+    end
+  end
+end
+
+OpenAI::Resources::Responses.include(OpenAI::Helpers::ResponsesWebSocket::Connections)

data/lib/openai/helpers/responses_websocket/transports/async_websocket.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Responses
+    module Transports
+      # Responses facade for the shared optional async WebSocket transport.
+      #
+      # @api private
+      class AsyncWebSocket < OpenAI::WebSocket::AsyncWebSocketTransport
+        def initialize
+          error_factory = lambda do |url:, message: nil, http_status: nil, **_options|
+            OpenAI::Errors::ResponsesConnectionError.new(
+              url: url,
+              message: message,
+              http_status: http_status
+            )
+          end
+
+          super(
+            product_name: "Responses",
+            error_class: OpenAI::Errors::ResponsesConnectionError,
+            error_factory: error_factory,
+            dependency_message: "Responses WebSockets require the async-websocket gem. Add it to your Gemfile."
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Responses
+    # A valid JSON event whose discriminator is newer than this SDK version.
+    class UnknownServerEvent
+      # @return [Symbol]
+      attr_reader :type
+
+      # @return [Hash{Symbol=>Object}]
+      attr_reader :data
+
+      # @return [Object]
+      attr_reader :stream_id
+
+      # @api private
+      def initialize(data:)
+        value = data.fetch(:type)
+        unless value.is_a?(String) || value.is_a?(Symbol)
+          raise ArgumentError, "Responses server event type must be a string or symbol"
+        end
+
+        @type = value.to_sym
+        @stream_id = data[:stream_id]
+        @data = freeze_json(data)
+        freeze
+      end
+
+      # @return [Hash{Symbol=>Object}]
+      def to_h = @data
+
+      # Keep routine diagnostics payload-free. Callers that explicitly need the
+      # unknown JSON can use {#data} or {#to_h}.
+      def inspect = "#<#{self.class} type=#{@type.inspect}>"
+
+      alias to_s inspect
+
+      private def freeze_json(value)
+        case value
+        when Hash
+          value.each do |key, item|
+            freeze_json(key)
+            freeze_json(item)
+          end
+
+        when Array
+          value.each { |item| freeze_json(item) }
+        end
+
+        value.freeze
+      end
+    end
+  end
+end

data/lib/openai/helpers/responses_websocket.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Responses WebSocket mode is a custom SDK runtime layered on generated
+# Responses protocol models. Generated HTTP resources remain generator-owned.
+require_relative "responses_websocket/errors"
+require_relative "responses_websocket/unknown_server_event"
+require_relative "responses_websocket/connection_resources"
+require_relative "responses_websocket/connection"
+require_relative "responses_websocket/connection_manager"
+require_relative "responses_websocket/transports/async_websocket"
+require_relative "responses_websocket/client_extension"
+require_relative "responses_websocket/resources/responses_extension"

data/lib/openai/helpers/sorbet.rb

@@ -259,6 +259,11 @@ module OpenAI
           super
         end
 
+        def retrieve(response_id, params = {})
+          reject_sorbet_function_tools!(params)
+          super
+        end
+
         def stream(params)
           reject_sorbet_streaming_formats!(params)
           super
@@ -281,7 +286,8 @@ module OpenAI
         end
 
         private def reject_sorbet_function_tools!(params = {})
-          tools = Array(params[:tools])
+          params = params.to_h if params.is_a?(OpenAI::Internal::Type::BaseModel)
+          tools = Array(params[:tools]).dup
           tools.concat(Array(params["tools"])) if params.is_a?(Hash)
 
           if tools.any? { sorbet_adapter?(_1) }