ruby_llm-responses_api 0.3.1 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea0573fba4558602d3dfae81efc02d6164a7fe30d05ac277302de4fe2ef91ba7
-  data.tar.gz: d1f6077b07879b754c2ea7c2bb9577473beec9059d0389a541891c389f37af79
+  metadata.gz: c2d9ce65eebe6420f01878669d81f90f999b738158b17eaa558dd6c88226c2c2
+  data.tar.gz: c432ef2dfcebb290debbbc5ac5e72038081f54fc054065da1bee09465ba99ba0
 SHA512:
-  metadata.gz: e407cfce50dd85f7ab4c2e35ca6dc0406efd26fd069238b9e6def78a725e9d3a4d62736328da0e3e8d3b8dbbb671f78bf13f632d645a5c9029521d45a54251b8
-  data.tar.gz: e96c18c0c53c7a6f5482246b990d78a4d3f9e868cf1818c990e2a4d447a4ec6b9f26a5b8925024c1f331a18d45a9b640ca7393e7d01156b38bbed5946acbd260
+  metadata.gz: 39bbbb38a8b7183ff501d092eab938f0ab6572129ca3cd518057daa04b21117ea38eb8c19ab1a6755036b41f683f3124a1c0209ee91c5f547fe12590b673bbf3
+  data.tar.gz: 74346a9093b98f079b02deffc3d9f8cbe9b8bf681d33a843d4bd130d099976f78d66a61a6c2b5032d31a84190e25b7509fe4e83f39fa278be2f74f5980568544

data/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.1] - 2026-02-24
+
+### Added
+
+- `chat.with_params(transport: :websocket)` integration with standard `chat.ask` interface
+- `WebSocket#call` for accepting pre-built payloads from the provider
+
+### Fixed
+
+- WebSocket responses now preserve token counts from `StreamAccumulator`
+
+## [0.4.0] - 2026-02-24
+
+### Added
+
+- **WebSocket mode** for lower-latency agentic workflows with persistent `wss://` connections
+  - `RubyLLM::ResponsesAPI::WebSocket` standalone class
+  - Streamed responses via `create_response` with block
+  - Automatic `previous_response_id` chaining across turns
+  - `warmup` for server-side model weight caching (`generate: false`)
+  - Thread-safe with one-at-a-time response constraint
+  - Supports all existing helpers: `State`, `Compaction`, `Tools`
+  - Soft dependency on `websocket-client-simple` (lazy require with clear error)
+
 ## [0.3.1] - 2026-02-18
 
 ### Fixed

data/README.md

@@ -259,6 +259,53 @@ image_results  = RubyLLM::ResponsesAPI::BuiltInTools.parse_image_generation_resu
 citations      = RubyLLM::ResponsesAPI::BuiltInTools.extract_citations(message_content)
 ```
 
+## WebSocket Mode
+
+For agentic workflows with many tool-call round trips, WebSocket mode provides lower latency by maintaining a persistent connection instead of HTTP requests per turn.
+
+Requires the `websocket-client-simple` gem:
+
+```ruby
+gem 'websocket-client-simple'
+```
+
+### Usage
+
+Just add `transport: :websocket` to your params -- the standard `chat.ask` API works as-is:
+
+```ruby
+chat = RubyLLM.chat(model: 'gpt-4o', provider: :openai_responses)
+chat.with_params(transport: :websocket)
+
+chat.ask("Hello!")
+chat.ask("What's 2+2?")  # reuses the same WebSocket connection
+```
+
+Streaming works the same way:
+
+```ruby
+chat.ask("Tell me a story") { |chunk| print chunk.content }
+```
+
+### Direct WebSocket access
+
+For advanced use cases (raw Responses API format, warmup, explicit connection management):
+
+```ruby
+ws = RubyLLM::ResponsesAPI::WebSocket.new(api_key: ENV['OPENAI_API_KEY'])
+ws.connect
+
+ws.create_response(
+  model: 'gpt-4o',
+  input: [{ type: 'message', role: 'user', content: 'Hello!' }]
+) { |chunk| print chunk.content }
+
+# Pre-cache model weights
+ws.warmup(model: 'gpt-4o')
+
+ws.disconnect
+```
+
 ## Why Use the Responses API?
 
 - **Built-in tools** - Web search, code execution, file search, shell, apply patch without custom implementation
@@ -266,6 +313,7 @@ citations      = RubyLLM::ResponsesAPI::BuiltInTools.extract_citations(message_c
 - **Simpler multi-turn** - No need to send full message history on each request
 - **Server-side compaction** - Run multi-hour agent sessions without hitting context limits
 - **Containers** - Persistent execution environments with networking and file management
+- **WebSocket mode** - Lower-latency persistent connections for agentic tool-call loops
 
 ## License
 

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

@@ -0,0 +1,296 @@
+# frozen_string_literal: true
+
+require 'timeout'
+
+module RubyLLM
+  module Providers
+    class OpenAIResponses
+      # WebSocket transport for the OpenAI Responses API.
+      # Provides lower-latency agentic workflows by maintaining a persistent
+      # wss:// connection instead of HTTP requests per turn.
+      #
+      # Requires the `websocket-client-simple` gem (soft dependency).
+      #
+      # Integrated usage (recommended):
+      #   chat = RubyLLM.chat(model: 'gpt-4o', provider: :openai_responses)
+      #   chat.with_params(transport: :websocket)
+      #   chat.ask("Hello!")
+      #
+      # Standalone usage (advanced):
+      #   ws = RubyLLM::ResponsesAPI::WebSocket.new(api_key: ENV['OPENAI_API_KEY'])
+      #   ws.connect
+      #   ws.create_response(model: 'gpt-4o', input: [...]) { |chunk| ... }
+      #   ws.disconnect
+      class WebSocket
+        WEBSOCKET_PATH = '/v1/responses'
+        KNOWN_PARAMS = %i[store metadata compact_threshold context_management].freeze
+
+        attr_reader :last_response_id
+
+        # @param api_key [String] OpenAI API key
+        # @param api_base [String] API base URL (https scheme; converted to wss)
+        # @param organization_id [String, nil] OpenAI organization ID
+        # @param project_id [String, nil] OpenAI project ID
+        # @param client_class [#connect, nil] WebSocket client class (for testing)
+        def initialize(api_key:, api_base: 'https://api.openai.com/v1', organization_id: nil, project_id: nil,
+                       client_class: nil)
+          @api_key = api_key
+          @api_base = api_base
+          @organization_id = organization_id
+          @project_id = project_id
+          @client_class = client_class
+
+          @ws = nil
+          @mutex = Mutex.new
+          @connected = false
+          @in_flight = false
+          @last_response_id = nil
+          @message_queue = nil
+        end
+
+        # Open the WebSocket connection. Blocks until the connection is established.
+        # @param timeout [Numeric] seconds to wait for the connection (default: 10)
+        # @raise [ConnectionError] if the connection cannot be established
+        # @return [self]
+        def connect(timeout: 10)
+          client_class = @client_class || resolve_client_class
+
+          ready = Queue.new
+          error_holder = []
+
+          @ws = client_class.connect(build_ws_url, headers: build_headers)
+
+          @ws.on(:open) { ready.push(:ok) }
+
+          @ws.on(:error) do |e|
+            error_holder << e
+            ready.push(:error) unless @connected
+          end
+
+          @ws.on(:close) do
+            @mutex.synchronize do
+              @connected = false
+              @message_queue&.push(nil)
+            end
+          end
+
+          @ws.on(:message) do |msg|
+            q = @mutex.synchronize { @message_queue }
+            q&.push(msg.data)
+          end
+
+          result = pop_with_timeout(ready, timeout)
+          if result == :error || result.nil?
+            err = error_holder.first
+            raise ConnectionError, "WebSocket connection failed: #{err&.message || 'timeout'}"
+          end
+
+          @mutex.synchronize { @connected = true }
+          self
+        end
+
+        # Send a pre-built payload over WebSocket, streaming chunks via block.
+        # This is the integration point for Provider#complete -- it accepts the
+        # same payload hash that render_payload returns.
+        #
+        # @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, &block)
+          ensure_connected!
+          acquire_flight!
+
+          queue = Queue.new
+          @mutex.synchronize { @message_queue = queue }
+
+          envelope = { type: 'response.create', response: payload.except(:stream) }
+          send_json(envelope)
+          accumulate_response(queue, &block)
+        ensure
+          @mutex.synchronize { @message_queue = nil }
+          release_flight!
+        end
+
+        # Send a response.create request using raw Responses API format.
+        # Useful for standalone usage outside the RubyLLM chat interface.
+        #
+        # @param model [String] model ID
+        # @param input [Array<Hash>] input items in Responses API format
+        # @param tools [Array<Hash>, nil] tool definitions
+        # @param previous_response_id [String, nil] chain to a prior response
+        # @param instructions [String, nil] system/developer instructions
+        # @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)
+          payload = build_standalone_payload(
+            model: model, input: input, tools: tools,
+            previous_response_id: previous_response_id,
+            instructions: instructions, **extra
+          )
+
+          call(payload, &block)
+        end
+
+        # Warm up the connection by sending a response.create with generate: false.
+        # Caches model weights server-side without generating output.
+        # @param model [String] model ID
+        # @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',
+            response: { 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!
+        end
+
+        # Disconnect the WebSocket.
+        # @return [void]
+        def disconnect
+          @ws&.close
+          @mutex.synchronize { @connected = false }
+        end
+
+        # @return [Boolean]
+        def connected?
+          @mutex.synchronize { @connected }
+        end
+
+        # Close and reopen the connection.
+        # @return [self]
+        def reconnect(timeout: 10)
+          disconnect
+          connect(timeout: timeout)
+        end
+
+        # Custom error types
+        class ConnectionError < StandardError; end
+        class ConcurrencyError < StandardError; end
+        class ResponseError < StandardError; end
+
+        private
+
+        def resolve_client_class
+          require 'websocket-client-simple'
+          ::WebSocket::Client::Simple
+        rescue LoadError
+          raise LoadError,
+                'The websocket-client-simple gem is required for WebSocket mode. ' \
+                "Add `gem 'websocket-client-simple'` to your Gemfile."
+        end
+
+        def build_ws_url
+          base = @api_base.sub(%r{/v1\z}, '')
+          host = base.sub(%r{\Ahttps?://}, '')
+          "wss://#{host}#{WEBSOCKET_PATH}"
+        end
+
+        def build_headers
+          headers = {
+            'Authorization' => "Bearer #{@api_key}",
+            'OpenAI-Beta' => 'responses.websocket=v1'
+          }
+          headers['OpenAI-Organization'] = @organization_id if @organization_id
+          headers['OpenAI-Project'] = @project_id if @project_id
+          headers
+        end
+
+        def build_standalone_payload(model:, input:, tools: nil, previous_response_id: nil, instructions: nil, **extra)
+          prev_id = previous_response_id || @last_response_id
+          response = { model: model, input: input }
+          response[:tools] = tools.map { |t| Tools.tool_for(t) } if tools&.any?
+          response[:previous_response_id] = prev_id if prev_id
+          response[:instructions] = instructions if instructions
+
+          State.apply_state_params(response, extra)
+          Compaction.apply_compaction(response, extra)
+
+          forwarded = extra.reject { |k, _| KNOWN_PARAMS.include?(k) }
+          response.merge(forwarded)
+        end
+
+        def send_json(payload)
+          @ws.send(JSON.generate(payload))
+        end
+
+        def accumulate_response(queue, &block)
+          accumulator = StreamAccumulator.new
+
+          loop do
+            raw = queue.pop
+            break if raw.nil?
+
+            data = JSON.parse(raw)
+            event_type = data['type']
+
+            chunk = Streaming.build_chunk(data)
+            accumulator.add(chunk)
+            block&.call(chunk)
+
+            if event_type == 'response.completed'
+              track_response_id(data)
+              break
+            end
+          end
+
+          message = accumulator.to_message(nil)
+          message.response_id = @last_response_id
+          message
+        end
+
+        def track_response_id(data)
+          resp_id = data.dig('response', 'id')
+          @mutex.synchronize { @last_response_id = resp_id } if resp_id
+        end
+
+        def ensure_connected!
+          raise ConnectionError, 'WebSocket is not connected. Call #connect first.' unless connected?
+        end
+
+        def acquire_flight!
+          @mutex.synchronize do
+            raise ConcurrencyError, 'Another response is already in flight.' if @in_flight
+
+            @in_flight = true
+          end
+        end
+
+        def release_flight!
+          @mutex.synchronize { @in_flight = false }
+        end
+
+        def pop_with_timeout(queue, seconds)
+          Timeout.timeout(seconds) { queue.pop }
+        rescue Timeout::Error
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/openai_responses.rb

@@ -16,6 +16,16 @@ module RubyLLM
         @config.openai_api_base || 'https://api.openai.com/v1'
       end
 
+      # Override to support WebSocket transport via with_params(transport: :websocket)
+      def complete(messages, tools:, temperature:, model:, params: {}, headers: {}, schema: nil, thinking: nil, &block) # rubocop:disable Metrics/ParameterLists
+        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
+
       def headers
         {
           'Authorization' => "Bearer #{@config.openai_api_key}",
@@ -137,6 +147,35 @@ module RubyLLM
 
       private
 
+      def ws_complete(messages, tools:, temperature:, model:, params:, schema:, thinking:, &block)
+        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
+        @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
+        )
+      end
+
       # DELETE request via the underlying Faraday connection
       # RubyLLM::Connection only exposes get/post, so we use Faraday directly
       def delete_request(url)

data/lib/rubyllm_responses_api.rb

@@ -22,6 +22,7 @@ require_relative 'ruby_llm/providers/openai_responses/containers'
 require_relative 'ruby_llm/providers/openai_responses/message_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
 require_relative 'ruby_llm/providers/openai_responses'
@@ -36,7 +37,7 @@ RubyLLM::Providers::OpenAIResponses::ModelRegistry.register_all!
 module RubyLLM
   # ResponsesAPI namespace for direct access to helpers and version
   module ResponsesAPI
-    VERSION = '0.3.1'
+    VERSION = '0.4.1'
 
     # Shorthand access to built-in tool helpers
     BuiltInTools = Providers::OpenAIResponses::BuiltInTools
@@ -44,5 +45,6 @@ module RubyLLM
     Background = Providers::OpenAIResponses::Background
     Compaction = Providers::OpenAIResponses::Compaction
     Containers = Providers::OpenAIResponses::Containers
+    WebSocket = Providers::OpenAIResponses::WebSocket
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-responses_api
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.1
 platform: ruby
 authors:
 - Chris Hasinski
@@ -121,6 +121,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: websocket-client-simple
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
 description: A RubyLLM provider that implements OpenAI's Responses API, providing
   access to built-in tools (web search, code interpreter, file search, shell, apply
   patch), stateful conversations, server-side compaction, containers API, background
@@ -151,6 +165,7 @@ files:
 - lib/ruby_llm/providers/openai_responses/state.rb
 - lib/ruby_llm/providers/openai_responses/streaming.rb
 - lib/ruby_llm/providers/openai_responses/tools.rb
+- lib/ruby_llm/providers/openai_responses/web_socket.rb
 - lib/rubyllm_responses_api.rb
 homepage: https://github.com/khasinski/ruby_llm-responses_api
 licenses: