ruby_llm-responses_api 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ca7cab6681d016096c3c578e5cb0c74f21af60ec03cc4fd8667263a95cd97ce
-  data.tar.gz: ed3d4931a835334aba4c351da61f4293464cfbeb3a3fb8399468b0a3665c962c
+  metadata.gz: c2d9ce65eebe6420f01878669d81f90f999b738158b17eaa558dd6c88226c2c2
+  data.tar.gz: c432ef2dfcebb290debbbc5ac5e72038081f54fc054065da1bee09465ba99ba0
 SHA512:
-  metadata.gz: 4ab75bc29fe723177cd82c988b89f298e367e363d9224998bf3cde0372eb94f153804b6ffc3f8ac75032a137c1ec7fe1d065ca7d7d8452dadabc0d27d24abfa9
-  data.tar.gz: e4b6f9837af18c683392a3436942e4aed6e03d245ab1ae0070b95c20111ec0aae01c35f44fd929808fe75c926257b2e2a0218b527f9f12744e8003d7decc6df4
+  metadata.gz: 39bbbb38a8b7183ff501d092eab938f0ab6572129ca3cd518057daa04b21117ea38eb8c19ab1a6755036b41f683f3124a1c0209ee91c5f547fe12590b673bbf3
+  data.tar.gz: 74346a9093b98f079b02deffc3d9f8cbe9b8bf681d33a843d4bd130d099976f78d66a61a6c2b5032d31a84190e25b7509fe4e83f39fa278be2f74f5980568544

data/CHANGELOG.md

@@ -5,6 +5,17 @@ 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

data/README.md

@@ -269,59 +269,40 @@ Requires the `websocket-client-simple` gem:
 gem 'websocket-client-simple'
 ```
 
-### Basic usage
+### Usage
 
-```ruby
-ws = RubyLLM::ResponsesAPI::WebSocket.new(api_key: ENV['OPENAI_API_KEY'])
-ws.connect
+Just add `transport: :websocket` to your params -- the standard `chat.ask` API works as-is:
 
-# 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
+```ruby
+chat = RubyLLM.chat(model: 'gpt-4o', provider: :openai_responses)
+chat.with_params(transport: :websocket)
 
-puts "\n#{message.content}"
+chat.ask("Hello!")
+chat.ask("What's 2+2?")  # reuses the same WebSocket connection
 ```
 
-### Multi-turn conversations
-
-`previous_response_id` is tracked automatically across turns:
+Streaming works the same way:
 
 ```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)
+chat.ask("Tell me a story") { |chunk| print chunk.content }
 ```
 
-### With tools
+### 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: 'Search for Ruby 3.4 release notes' }],
-  tools: [{ type: 'web_search_preview' }]
-)
-```
-
-### Warmup
-
-Pre-cache model weights without generating output:
+  input: [{ type: 'message', role: 'user', content: 'Hello!' }]
+) { |chunk| print chunk.content }
 
-```ruby
+# Pre-cache model weights
 ws.warmup(model: 'gpt-4o')
-```
-
-### Cleanup
 
-```ruby
 ws.disconnect
 ```
 

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

@@ -11,14 +11,15 @@ module RubyLLM
       #
       # Requires the `websocket-client-simple` gem (soft dependency).
       #
-      # Usage:
+      # 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: [{ type: 'message', role: 'user', content: 'Hi' }]) do |chunk|
-      #     print chunk.content if chunk.content
-      #   end
-      #
+      #   ws.create_response(model: 'gpt-4o', input: [...]) { |chunk| ... }
       #   ws.disconnect
       class WebSocket
         WEBSOCKET_PATH = '/v1/responses'
@@ -73,7 +74,6 @@ module RubyLLM
             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)
@@ -89,35 +89,47 @@ module RubyLLM
           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
+        # 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
-        # @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)
+        def call(payload, &block)
           ensure_connected!
           acquire_flight!
 
           queue = Queue.new
           @mutex.synchronize { @message_queue = queue }
 
-          payload = build_payload(
+          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
           )
 
-          send_json(payload)
-          accumulate_response(queue, &block)
-        ensure
-          @mutex.synchronize { @message_queue = nil }
-          release_flight!
+          call(payload, &block)
         end
 
         # Warm up the connection by sending a response.create with generate: false.
@@ -209,7 +221,7 @@ module RubyLLM
           headers
         end
 
-        def build_payload(model:, input:, tools: nil, previous_response_id: nil, instructions: nil, **extra)
+        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?
@@ -220,7 +232,7 @@ module RubyLLM
           Compaction.apply_compaction(response, extra)
 
           forwarded = extra.reject { |k, _| KNOWN_PARAMS.include?(k) }
-          { type: 'response.create', response: response.merge(forwarded) }
+          response.merge(forwarded)
         end
 
         def send_json(payload)
@@ -247,7 +259,9 @@ module RubyLLM
             end
           end
 
-          build_final_message(accumulator)
+          message = accumulator.to_message(nil)
+          message.response_id = @last_response_id
+          message
         end
 
         def track_response_id(data)
@@ -255,16 +269,6 @@ module RubyLLM
           @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

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

@@ -37,7 +37,7 @@ RubyLLM::Providers::OpenAIResponses::ModelRegistry.register_all!
 module RubyLLM
   # ResponsesAPI namespace for direct access to helpers and version
   module ResponsesAPI
-    VERSION = '0.4.0'
+    VERSION = '0.4.1'
 
     # Shorthand access to built-in tool helpers
     BuiltInTools = Providers::OpenAIResponses::BuiltInTools

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-responses_api
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Chris Hasinski