ruby_llm-responses_api 0.6.0 → 1.0.0

data/lib/ruby_llm/providers/openai_responses/protocol.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class OpenAIResponses
+      # Native Responses rendering/parsing, with state scoped to this provider.
+      class Protocol < OpenAI::Responses
+        def render(messages, provider_options: {}, **)
+          @response_options = RubyLLM::Support::Utils.deep_symbolize_keys(provider_options)
+          payload = super(messages, provider_options: @response_options.except(:transport), **)
+          @store_response = payload[:store] != false
+          payload
+        end
+
+        def render_payload(messages, **)
+          state = @response_options || {}
+          parent = if state.key?(:previous_response_id)
+                     state[:previous_response_id]
+                   elsif state[:store] != false
+                     messages.rfind { |message| message.role == :assistant && message.response_id }&.response_id
+                   end
+          payload = super(new_messages(messages, parent), **)
+          payload[:store] = state.fetch(:store, true)
+          payload[:previous_response_id] = parent if parent
+          payload
+        end
+
+        def apply_compaction(payload, compaction)
+          warn_ignored_compaction_options(compaction)
+          entry = { type: 'compaction' }
+          entry[:compact_threshold] = compaction[:at] if compaction[:at]
+          payload.merge(context_management: [entry])
+        end
+
+        def apply_end_user(payload, identifier)
+          payload.merge(safety_identifier: identifier)
+        end
+
+        def supports_provider_file_references?
+          true
+        end
+
+        def parse_completion_body(data, raw:)
+          decorate_message(super, data)
+        end
+
+        def build_final_chunk(data)
+          decorate_message(super, data.fetch('response', {}))
+        end
+
+        # Public event entry point for the standalone WebSocket client.
+        def parse_event(data)
+          build_chunk(data)
+        end
+
+        def stream_response(payload, additional_headers = {})
+          accumulator = StreamAccumulator.new
+          response = stream_events(stream_url, payload, additional_headers) do |data|
+            chunk = build_chunk(data)
+            accumulator.add(chunk)
+            yield chunk
+          end
+          accumulator.to_message(response)
+        end
+
+        def stream_events(url, payload, additional_headers = {}, &)
+          return super unless websocket?
+
+          @usage_tracker&.start
+          @provider.responses_websocket(additional_headers).stream_events(payload, &)
+        end
+
+        def sync_response(payload, additional_headers = {})
+          return super unless websocket?
+
+          stream_response(payload, additional_headers) { |chunk| @usage_tracker&.observe(chunk) }
+        end
+
+        private
+
+        def websocket?
+          @response_options && @response_options[:transport]&.to_sym == :websocket
+        end
+
+        def new_messages(messages, parent)
+          return messages unless parent
+
+          anchor = messages.rindex { |message| message.role == :assistant && message.response_id == parent }
+          return messages unless anchor
+
+          messages.each_with_index.filter_map { |message, index| message if message.role == :system || index > anchor }
+        end
+
+        def decorate_message(message, data)
+          message.response_id = data['id'] unless @store_response == false || data['store'] == false
+          message.built_in_tool_events = BuiltInTools.extract_events(data['output'] || [])
+          message.responses_api_body = data
+          message
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/openai_responses/stream_accumulator.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class OpenAIResponses
+      # Extends the native stream accumulator to carry built_in_tool_events and
+      # response_id from chunks through to the final assembled Message.
+      # Without this the accumulator drops everything off the Chunk it does
+      # not know about — including response_id, which breaks
+      # previous_response_id chaining on the next turn for any streamed chat.
+      class StreamAccumulator < RubyLLM::Protocol::StreamAccumulator
+        def add(chunk)
+          super
+          @response_id = chunk.response_id if chunk.respond_to?(:response_id) && chunk.response_id
+
+          @responses_api_body = chunk.responses_api_body if chunk.responses_api_body
+          events = chunk_built_in_events(chunk)
+          return if events.nil? || events.empty?
+
+          @built_in_tool_events ||= []
+          @built_in_tool_events.concat(events)
+        end
+
+        def to_message(response)
+          if @responses_api_body
+            # A completed stream supplies the same response object as a sync call.
+            response = Faraday::Response.new(status: response&.status || 200,
+                                             response_headers: response&.headers || {}, body: @responses_api_body)
+          end
+          message = super
+          if @built_in_tool_events && !@built_in_tool_events.empty? && message.respond_to?(:built_in_tool_events=)
+            message.built_in_tool_events = @built_in_tool_events
+          end
+          message.response_id = @response_id if @response_id && message.respond_to?(:response_id=)
+          message
+        end
+
+        private
+
+        def chunk_built_in_events(chunk)
+          return nil unless chunk.respond_to?(:built_in_tool_events)
+
+          chunk.built_in_tool_events
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/openai_responses/web_socket.rb

@@ -13,7 +13,7 @@ module RubyLLM
       #
       # Integrated usage (recommended):
       #   chat = RubyLLM.chat(model: 'gpt-4o', provider: :openai_responses)
-      #   chat.with_params(transport: :websocket)
+      #   chat.with_provider_options(transport: :websocket)
       #   chat.ask("Hello!")
       #
       # Standalone usage (advanced):
@@ -34,15 +34,16 @@ module RubyLLM
         # @param project_id [String, nil] OpenAI project ID
         # @param client_class [#connect, nil] WebSocket client class (for testing)
         # @param response_timeout [Numeric] seconds to wait for a response event
-        # rubocop:disable Metrics/ParameterLists
+        # rubocop:disable-next Metrics/ParameterLists
         def initialize(api_key:, api_base: 'https://api.openai.com/v1', organization_id: nil, project_id: nil,
-                       client_class: nil, response_timeout: 60)
+                       client_class: nil, response_timeout: 60, headers: {})
           @api_key = api_key
           @api_base = api_base
           @organization_id = organization_id
           @project_id = project_id
           @client_class = client_class
           @response_timeout = response_timeout
+          @headers = headers
 
           @ws = nil
           @mutex = Mutex.new
@@ -51,7 +52,6 @@ module RubyLLM
           @last_response_id = nil
           @message_queue = nil
         end
-        # rubocop:enable Metrics/ParameterLists
 
         # Open the WebSocket connection. Blocks until the connection is established.
         # @param timeout [Numeric] seconds to wait for the connection (default: 10)
@@ -96,19 +96,43 @@ module RubyLLM
         # @param payload [Hash] Responses API payload (model, input, tools, etc.)
         # @yield [RubyLLM::Chunk] each streamed chunk
         # @return [RubyLLM::Message] the assembled final message
-        def call(payload, &)
+        def call(payload)
+          config = RubyLLM.config.dup
+          config.openai_api_key = @api_key
+          provider = OpenAIResponses.new(config)
+          protocol = Protocol.new(provider)
+          accumulator = StreamAccumulator.new
+          stream_events(payload) do |data|
+            chunk = protocol.parse_event(data)
+            chunk.response_id = nil if payload[:store] == false
+            accumulator.add(chunk)
+            yield chunk if block_given?
+          end
+          accumulator.to_message(nil)
+        end
+
+        # Shared by the standalone client and the native RubyLLM protocol.
+        def stream_events(payload)
           ensure_connected!
           acquire_flight!
-
+          acquired = true
           queue = Queue.new
           @mutex.synchronize { @message_queue = queue }
+          send_json({ type: 'response.create' }.merge(payload.except(:stream)))
+
+          loop do
+            data = next_event(queue)
+            yield data
+            next unless %w[response.completed response.incomplete].include?(data['type'])
 
-          envelope = { type: 'response.create' }.merge(payload.except(:stream))
-          send_json(envelope)
-          accumulate_response(queue, &)
+            @last_response_id = payload[:store] == false ? nil : data.dig('response', 'id')
+            return nil
+          end
         ensure
-          @mutex.synchronize { @message_queue = nil }
-          release_flight!
+          if acquired
+            @mutex.synchronize { @message_queue = nil }
+            release_flight!
+          end
         end
 
         # Send a response.create request using raw Responses API format.
@@ -122,14 +146,14 @@ module RubyLLM
         # @param extra [Hash] additional fields forwarded to the API
         # @yield [RubyLLM::Chunk] each streamed chunk
         # @return [RubyLLM::Message] the assembled final message
-        def create_response(model:, input:, tools: nil, previous_response_id: nil, instructions: nil, **extra, &block) # rubocop:disable Metrics/ParameterLists
+        def create_response(model:, input:, tools: nil, previous_response_id: nil, instructions: nil, **extra, &) # rubocop:disable Metrics/ParameterLists
           payload = build_standalone_payload(
             model: model, input: input, tools: tools,
             previous_response_id: previous_response_id,
             instructions: instructions, **extra
           )
 
-          call(payload, &block)
+          call(payload, &)
         end
 
         # Warm up the connection by sending a response.create with generate: false.
@@ -138,33 +162,7 @@ module RubyLLM
         # @param extra [Hash] additional fields
         # @return [void]
         def warmup(model:, **extra)
-          ensure_connected!
-          acquire_flight!
-
-          queue = Queue.new
-          @mutex.synchronize { @message_queue = queue }
-
-          payload = { type: 'response.create', model: model, generate: false }.merge(extra)
-
-          send_json(payload)
-
-          loop do
-            data = queue.pop
-            break if data.nil?
-
-            parsed = JSON.parse(data)
-            event_type = parsed['type']
-
-            if event_type == 'error'
-              error_msg = parsed.dig('error', 'message') || 'Warmup error'
-              raise ResponseError, error_msg
-            end
-
-            break if event_type == 'response.completed'
-          end
-        ensure
-          @mutex.synchronize { @message_queue = nil }
-          release_flight!
+          stream_events({ model: model, generate: false }.merge(extra)) { |_event| nil }
         end
 
         # Disconnect the WebSocket.
@@ -226,13 +224,13 @@ module RubyLLM
           }
           headers['OpenAI-Organization'] = @organization_id if @organization_id
           headers['OpenAI-Project'] = @project_id if @project_id
-          headers
+          headers.merge(@headers)
         end
 
         def build_standalone_payload(model:, input:, tools: nil, previous_response_id: nil, instructions: nil, **extra) # rubocop:disable Metrics/ParameterLists
-          prev_id = previous_response_id || @last_response_id
+          prev_id = previous_response_id || (@last_response_id unless extra[:store] == false)
           response = { model: model, input: input }
-          response[:tools] = tools.map { |t| Tools.tool_for(t) } if tools&.any?
+          response[:tools] = tools if tools&.any?
           response[:previous_response_id] = prev_id if prev_id
           response[:instructions] = instructions if instructions
 
@@ -247,43 +245,19 @@ module RubyLLM
           @ws.send(JSON.generate(payload))
         end
 
-        def accumulate_response(queue, &block)
-          accumulator = StreamAccumulator.new
-          built_in_events = []
-
-          loop do
-            raw = pop_response_event(queue)
-            if raw == RESPONSE_TIMEOUT
-              raise ConnectionError, "Timed out waiting for WebSocket response after #{@response_timeout} seconds"
-            end
-
-            break if raw.nil?
-
-            data = JSON.parse(raw)
-            event_type = data['type']
-
-            chunk = Streaming.build_chunk(data)
-            accumulator.add(chunk)
-            block&.call(chunk)
-
-            next unless event_type == 'response.completed'
-
-            track_response_id(data)
-            built_in_events.concat(BuiltInTools.extract_events(data.dig('response', 'output') || []))
-            break
+        def next_event(queue)
+          raw = pop_response_event(queue)
+          if raw == RESPONSE_TIMEOUT
+            raise ConnectionError, "Timed out waiting for WebSocket response after #{@response_timeout} seconds"
           end
+          raise ConnectionError, 'WebSocket closed before the response completed' if raw.nil?
 
-          message = accumulator.to_message(nil)
-          message.response_id = @last_response_id
-          if message.respond_to?(:built_in_tool_events=) && built_in_events.any?
-            message.built_in_tool_events = built_in_events
+          data = JSON.parse(raw)
+          if %w[error response.failed].include?(data['type'])
+            error = data['error'] || data.dig('response', 'error') || data
+            raise RubyLLM::Error, error['message'] || 'WebSocket response failed'
           end
-          message
-        end
-
-        def track_response_id(data)
-          resp_id = data.dig('response', 'id')
-          @mutex.synchronize { @last_response_id = resp_id } if resp_id
+          data
         end
 
         def ensure_connected!

data/lib/ruby_llm/providers/openai_responses.rb

@@ -6,36 +6,11 @@ module RubyLLM
     # Implements the new Responses API which provides built-in tools,
     # stateful conversations, background mode, and MCP support.
     class OpenAIResponses
-      include OpenAIResponses::Chat
-      include OpenAIResponses::Streaming
-      include OpenAIResponses::Tools
-      include OpenAIResponses::Models
-      include OpenAIResponses::Media
-
-      def api_base
-        @config.openai_api_base || 'https://api.openai.com/v1'
-      end
-
-      # Override to support WebSocket transport via with_params(transport: :websocket).
-      # rubocop:disable Metrics/ParameterLists
-      def complete(messages, tools:, temperature:, model:, params: {}, headers: {},
-                   schema: nil, thinking: nil, tool_prefs: nil, &block)
-        if params[:transport]&.to_sym == :websocket
-          ws_complete(messages, tools: tools, temperature: temperature, model: model,
-                                params: params.except(:transport), schema: schema,
-                                thinking: thinking, &block)
-        else
-          super
-        end
-      end
-      # rubocop:enable Metrics/ParameterLists
+      protocol :responses, OpenAIResponses::Protocol, batches: Protocols::Responses::Batches
+      protocol :files, Protocols::OpenAI::Files
 
-      def headers
-        {
-          'Authorization' => "Bearer #{@config.openai_api_key}",
-          'OpenAI-Organization' => @config.openai_organization_id,
-          'OpenAI-Project' => @config.openai_project_id
-        }.compact
+      def protocol_for(_model, **)
+        protocols.fetch(:responses)
       end
 
       # Retrieve a stored response by ID
@@ -185,56 +160,45 @@ module RubyLLM
         response.body
       end
 
-      private
-
-      def ws_complete(messages, tools:, temperature:, model:, params:, schema:, thinking:, &block) # rubocop:disable Metrics/ParameterLists
-        normalized_temperature = maybe_normalize_temperature(temperature, model)
-
-        payload = Utils.deep_merge(
-          render_payload(
-            messages,
-            tools: tools,
-            temperature: normalized_temperature,
-            model: model,
-            stream: true,
-            schema: schema,
-            thinking: thinking
-          ),
-          params
-        )
-
-        ws_connection.connect unless ws_connection.connected?
-        ws_connection.call(payload, &block)
-      end
-
-      def ws_connection
+      # Headers are part of the handshake, so a changed set uses a new connection.
+      def responses_websocket(additional_headers = {})
+        if @ws_connection && @ws_headers != additional_headers
+          @ws_connection.disconnect
+          @ws_connection = nil
+        end
+        @ws_headers = additional_headers.dup
         @ws_connection ||= WebSocket.new(
-          api_key: @config.openai_api_key,
-          api_base: api_base,
-          organization_id: @config.openai_organization_id,
-          project_id: @config.openai_project_id
+          api_key: @config.openai_api_key, api_base: api_base,
+          organization_id: @config.openai_organization_id, project_id: @config.openai_project_id,
+          headers: additional_headers
         )
+        @ws_connection.connect unless @ws_connection.connected?
+        @ws_connection
       end
 
-      # DELETE request via the underlying Faraday connection
-      # RubyLLM::Connection only exposes get/post, so we use Faraday directly
+      private
+
       def delete_request(url)
-        @connection.connection.delete(url) do |req|
-          req.headers.merge!(headers)
-        end
+        @connection.delete(url)
       end
 
       class << self
-        def capabilities
-          OpenAIResponses::Capabilities
+        def configuration_options
+          %i[
+            openai_api_key
+            openai_api_base
+            openai_organization_id
+            openai_project_id
+          ]
         end
 
         def configuration_requirements
           %i[openai_api_key]
         end
 
-        def slug
-          'openai_responses'
+        def models_dev_alias(model_id, models, provider_model = nil)
+          source = models["openai:#{model_id}"] || super
+          source && RubyLLM::Model.new(source.to_h.merge(provider: 'openai_responses'))
         end
       end
     end

data/lib/rubyllm_responses_api.rb

@@ -1,49 +1,22 @@
 # frozen_string_literal: true
 
 require 'ruby_llm'
-
-# Provider class must be loaded first to define the class
 require_relative 'ruby_llm/providers/openai_responses/base'
 
-# Core modules
-require_relative 'ruby_llm/providers/openai_responses/capabilities'
-require_relative 'ruby_llm/providers/openai_responses/media'
-require_relative 'ruby_llm/providers/openai_responses/tools'
-require_relative 'ruby_llm/providers/openai_responses/models'
-require_relative 'ruby_llm/providers/openai_responses/streaming'
-require_relative 'ruby_llm/providers/openai_responses/chat'
-
-# Advanced features
-require_relative 'ruby_llm/providers/openai_responses/built_in_tools'
-require_relative 'ruby_llm/providers/openai_responses/state'
-require_relative 'ruby_llm/providers/openai_responses/background'
-require_relative 'ruby_llm/providers/openai_responses/compaction'
-require_relative 'ruby_llm/providers/openai_responses/containers'
-require_relative 'ruby_llm/providers/openai_responses/batches'
-require_relative 'ruby_llm/providers/openai_responses/batch'
-require_relative 'ruby_llm/providers/openai_responses/message_extension'
-require_relative 'ruby_llm/providers/openai_responses/stream_accumulator_extension'
-require_relative 'ruby_llm/providers/openai_responses/chat_extension'
-require_relative 'ruby_llm/providers/openai_responses/model_registry'
-require_relative 'ruby_llm/providers/openai_responses/active_record_extension'
-require_relative 'ruby_llm/providers/openai_responses/web_socket'
-
-# Include all modules in the provider class
+%w[
+  built_in_tools state background compaction containers message_extension
+  stream_accumulator chat_extension model_registry active_record_extension
+  protocol web_socket batches batch
+].each { |name| require_relative "ruby_llm/providers/openai_responses/#{name}" }
 require_relative 'ruby_llm/providers/openai_responses'
 
-# Register the provider
 RubyLLM::Provider.register :openai_responses, RubyLLM::Providers::OpenAIResponses
 
-# Register models for this provider
-RubyLLM::Providers::OpenAIResponses::ModelRegistry.register_all!
-
-# Extend RubyLLM module with ResponsesAPI namespace
 module RubyLLM
-  # ResponsesAPI namespace for direct access to helpers and version
+  # Responses-specific helpers. RubyLLM's native batch factory is unchanged.
   module ResponsesAPI
-    VERSION = '0.6.0'
+    VERSION = '1.0.0'
 
-    # Shorthand access to built-in tool helpers
     BuiltInTools = Providers::OpenAIResponses::BuiltInTools
     State = Providers::OpenAIResponses::State
     Background = Providers::OpenAIResponses::Background
@@ -52,19 +25,13 @@ module RubyLLM
     Batches = Providers::OpenAIResponses::Batches
     Batch = Providers::OpenAIResponses::Batch
     WebSocket = Providers::OpenAIResponses::WebSocket
-  end
-
-  # Create a new Batch for bulk request processing
-  def self.batch(...)
-    Providers::OpenAIResponses::Batch.new(...)
-  end
 
-  # List existing batches
-  def self.batches(provider: :openai_responses, **kwargs)
-    slug = provider.to_sym
-    provider_class = Provider.providers[slug]
-    raise Error.new(nil, "Unknown provider: #{slug}") unless provider_class
+    def self.batch(...)
+      Batch.new(...)
+    end
 
-    provider_class.new(config).list_batches(**kwargs)
+    def self.batches(provider: :openai_responses, **)
+      RubyLLM::Provider.resolve!(provider).new(RubyLLM.config).list_batches(**)
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-responses_api
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Chris Hasinski
@@ -13,16 +13,16 @@ dependencies:
   name: ruby_llm
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.13'
+        version: 2.1.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.13'
+        version: 2.1.1
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
@@ -83,16 +83,16 @@ dependencies:
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: 2.9.5
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: 2.9.5
 - !ruby/object:Gem::Dependency
   name: vcr
   requirement: !ruby/object:Gem::Requirement
@@ -147,6 +147,7 @@ extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - LICENSE.txt
+- MIGRATION.md
 - README.md
 - lib/ruby_llm-responses_api.rb
 - lib/ruby_llm/providers/openai_responses.rb
@@ -156,19 +157,14 @@ files:
 - lib/ruby_llm/providers/openai_responses/batch.rb
 - lib/ruby_llm/providers/openai_responses/batches.rb
 - lib/ruby_llm/providers/openai_responses/built_in_tools.rb
-- lib/ruby_llm/providers/openai_responses/capabilities.rb
-- lib/ruby_llm/providers/openai_responses/chat.rb
 - lib/ruby_llm/providers/openai_responses/chat_extension.rb
 - lib/ruby_llm/providers/openai_responses/compaction.rb
 - lib/ruby_llm/providers/openai_responses/containers.rb
-- lib/ruby_llm/providers/openai_responses/media.rb
 - lib/ruby_llm/providers/openai_responses/message_extension.rb
 - lib/ruby_llm/providers/openai_responses/model_registry.rb
-- lib/ruby_llm/providers/openai_responses/models.rb
+- lib/ruby_llm/providers/openai_responses/protocol.rb
 - lib/ruby_llm/providers/openai_responses/state.rb
-- lib/ruby_llm/providers/openai_responses/stream_accumulator_extension.rb
-- lib/ruby_llm/providers/openai_responses/streaming.rb
-- lib/ruby_llm/providers/openai_responses/tools.rb
+- lib/ruby_llm/providers/openai_responses/stream_accumulator.rb
 - lib/ruby_llm/providers/openai_responses/web_socket.rb
 - lib/rubyllm_responses_api.rb
 homepage: https://github.com/khasinski/ruby_llm-responses_api
@@ -186,14 +182,17 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: '4.0'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: '5.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.20
 specification_version: 4
 summary: OpenAI Responses API provider for RubyLLM
 test_files: []