ruby_llm-responses_api 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea0573fba4558602d3dfae81efc02d6164a7fe30d05ac277302de4fe2ef91ba7
-  data.tar.gz: d1f6077b07879b754c2ea7c2bb9577473beec9059d0389a541891c389f37af79
+  metadata.gz: 7ca7cab6681d016096c3c578e5cb0c74f21af60ec03cc4fd8667263a95cd97ce
+  data.tar.gz: ed3d4931a835334aba4c351da61f4293464cfbeb3a3fb8399468b0a3665c962c
 SHA512:
-  metadata.gz: e407cfce50dd85f7ab4c2e35ca6dc0406efd26fd069238b9e6def78a725e9d3a4d62736328da0e3e8d3b8dbbb671f78bf13f632d645a5c9029521d45a54251b8
-  data.tar.gz: e96c18c0c53c7a6f5482246b990d78a4d3f9e868cf1818c990e2a4d447a4ec6b9f26a5b8925024c1f331a18d45a9b640ca7393e7d01156b38bbed5946acbd260
+  metadata.gz: 4ab75bc29fe723177cd82c988b89f298e367e363d9224998bf3cde0372eb94f153804b6ffc3f8ac75032a137c1ec7fe1d065ca7d7d8452dadabc0d27d24abfa9
+  data.tar.gz: e4b6f9837af18c683392a3436942e4aed6e03d245ab1ae0070b95c20111ec0aae01c35f44fd929808fe75c926257b2e2a0218b527f9f12744e8003d7decc6df4

data/CHANGELOG.md

@@ -5,6 +5,19 @@ 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.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,72 @@ 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'
+```
+
+### Basic usage
+
+```ruby
+ws = RubyLLM::ResponsesAPI::WebSocket.new(api_key: ENV['OPENAI_API_KEY'])
+ws.connect
+
+# Stream a response
+message = ws.create_response(
+  model: 'gpt-4o',
+  input: [{ type: 'message', role: 'user', content: 'Hello!' }]
+) do |chunk|
+  print chunk.content if chunk.content
+end
+
+puts "\n#{message.content}"
+```
+
+### Multi-turn conversations
+
+`previous_response_id` is tracked automatically across turns:
+
+```ruby
+ws.create_response(model: 'gpt-4o', input: [
+  { type: 'message', role: 'user', content: 'My name is Alice.' }
+])
+
+ws.create_response(model: 'gpt-4o', input: [
+  { type: 'message', role: 'user', content: "What's my name?" }
+])
+# => "Alice" (auto-chained via previous_response_id)
+```
+
+### With tools
+
+```ruby
+ws.create_response(
+  model: 'gpt-4o',
+  input: [{ type: 'message', role: 'user', content: 'Search for Ruby 3.4 release notes' }],
+  tools: [{ type: 'web_search_preview' }]
+)
+```
+
+### Warmup
+
+Pre-cache model weights without generating output:
+
+```ruby
+ws.warmup(model: 'gpt-4o')
+```
+
+### Cleanup
+
+```ruby
+ws.disconnect
+```
+
 ## Why Use the Responses API?
 
 - **Built-in tools** - Web search, code execution, file search, shell, apply patch without custom implementation
@@ -266,6 +332,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,292 @@
+# 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).
+      #
+      # Usage:
+      #   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: 'Hi' }]) do |chunk|
+      #     print chunk.content if chunk.content
+      #   end
+      #
+      #   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
+
+          # Route all messages to the current queue (swapped per request)
+          @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 response.create request and stream chunks via block.
+        # @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 top-level fields forwarded to the API
+        # @yield [RubyLLM::Chunk] each streamed chunk
+        # @return [RubyLLM::Message] the assembled final message
+        # @raise [ConcurrencyError] if another response is already in flight
+        # @raise [ConnectionError] if not connected
+        def create_response(model:, input:, tools: nil, previous_response_id: nil, instructions: nil, **extra, &block)
+          ensure_connected!
+          acquire_flight!
+
+          queue = Queue.new
+          @mutex.synchronize { @message_queue = queue }
+
+          payload = build_payload(
+            model: model, input: input, tools: tools,
+            previous_response_id: previous_response_id,
+            instructions: instructions, **extra
+          )
+
+          send_json(payload)
+          accumulate_response(queue, &block)
+        ensure
+          @mutex.synchronize { @message_queue = nil }
+          release_flight!
+        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_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) }
+          { type: 'response.create', response: 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
+
+          build_final_message(accumulator)
+        end
+
+        def track_response_id(data)
+          resp_id = data.dig('response', 'id')
+          @mutex.synchronize { @last_response_id = resp_id } if resp_id
+        end
+
+        def build_final_message(accumulator)
+          Message.new(
+            role: :assistant,
+            content: accumulator.content,
+            tool_calls: accumulator.tool_calls.empty? ? nil : accumulator.tool_calls,
+            model_id: accumulator.model_id,
+            response_id: @last_response_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/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.0'
 
     # 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.0
 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: