ruby_llm-responses_api 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ca7cab6681d016096c3c578e5cb0c74f21af60ec03cc4fd8667263a95cd97ce
-  data.tar.gz: ed3d4931a835334aba4c351da61f4293464cfbeb3a3fb8399468b0a3665c962c
+  metadata.gz: 5eafd14a08ce95dc9637f022c3dcd0b88dc979314efd534ec3a3d5dbb2a6e396
+  data.tar.gz: 6b84beeec2204e791727bb969aac9b9e490e574204c78ab87ec6b69692f1ad7d
 SHA512:
-  metadata.gz: 4ab75bc29fe723177cd82c988b89f298e367e363d9224998bf3cde0372eb94f153804b6ffc3f8ac75032a137c1ec7fe1d065ca7d7d8452dadabc0d27d24abfa9
-  data.tar.gz: e4b6f9837af18c683392a3436942e4aed6e03d245ab1ae0070b95c20111ec0aae01c35f44fd929808fe75c926257b2e2a0218b527f9f12744e8003d7decc6df4
+  metadata.gz: 5216a047aa783ed7b221e91f0173fd5785ae003b3006a9dcbcdb07effef569e73cac28fab1129f9e157e15f03a5219d18fdcfcc84c17406f3913fe8cdc1ed761
+  data.tar.gz: 3aa365e82445b4deb9f3b2dcda4ec47f096728f05c3f7a89eb9076be41ba81e873e2f513b4057391b84d6f1e1b8fd630ade743a46b0c2a37f9c2187eb43efbd6

data/CHANGELOG.md

@@ -5,6 +5,32 @@ 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.5.0] - 2026-02-25
+
+### Added
+
+- **Batch API** for processing many requests asynchronously at 50% lower cost
+  - `RubyLLM.batch(model:, provider:)` factory method
+  - `Batch#add` to queue requests with auto-generated or custom IDs
+  - `Batch#create!` to upload JSONL and create the batch in one call
+  - `Batch#wait!` to poll until completion with progress callbacks
+  - `Batch#results` returns a `Hash<custom_id, Message>` using the same parsing as `Chat`
+  - `Batch#errors`, `Batch#cancel!`, and status helpers (`completed?`, `in_progress?`, `failed?`)
+  - Resume from a previous session via `RubyLLM.batch(id: "batch_abc", provider: :openai_responses)`
+  - `RubyLLM.batches` to list existing batches
+  - `Batches` helper module with JSONL builder, URL helpers, and result parsing
+
+## [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

@@ -259,6 +259,44 @@ image_results  = RubyLLM::ResponsesAPI::BuiltInTools.parse_image_generation_resu
 citations      = RubyLLM::ResponsesAPI::BuiltInTools.extract_citations(message_content)
 ```
 
+## Batch API
+
+Process many requests asynchronously at 50% lower cost with a 24-hour completion window:
+
+```ruby
+# Create a batch
+batch = RubyLLM.batch(model: 'gpt-4o', provider: :openai_responses)
+
+# Add requests (auto-generates IDs or use your own)
+batch.add("What is Ruby?")
+batch.add("What is Python?", instructions: "Be brief", temperature: 0.5)
+batch.add("Translate: hello", id: "translate_1")
+
+# Submit (uploads JSONL file + creates batch)
+batch.create!
+batch.id  # => "batch_abc123"
+
+# Poll until done
+batch.wait!(interval: 60) { |b| puts "#{b.completed_count}/#{b.total_count}" }
+
+# Get results as Messages keyed by custom_id
+results = batch.results
+results["request_0"].content  # => "Ruby is a dynamic..."
+results["translate_1"].content  # => "Hola"
+
+# Resume from a previous session
+batch = RubyLLM.batch(id: "batch_abc123", provider: :openai_responses)
+batch.results
+
+# Cancel a running batch
+batch.cancel!
+
+# List existing batches
+RubyLLM.batches(provider: :openai_responses)
+```
+
+**Constraints**: No `web_search`/`code_interpreter` tools, no `previous_response_id` chaining, max 50k requests per batch, 200MB file limit.
+
 ## 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.
@@ -269,59 +307,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
 ```
 
@@ -333,6 +352,7 @@ ws.disconnect
 - **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
+- **Batch API** - Process bulk requests at 50% lower cost with 24-hour turnaround
 
 ## License
 

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

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+require 'stringio'
+
+module RubyLLM
+  module Providers
+    class OpenAIResponses
+      # High-level interface for OpenAI's Batch API.
+      # Hides JSONL serialization, file upload, polling, and result parsing
+      # behind a clean Ruby API that mirrors RubyLLM::Chat.
+      #
+      # @example
+      #   batch = RubyLLM.batch(model: 'gpt-4o', provider: :openai_responses)
+      #   batch.add("What is Ruby?")
+      #   batch.add("What is Python?", instructions: "Be brief")
+      #   batch.create!
+      #   batch.wait! { |b| puts "#{b.completed_count}/#{b.total_count}" }
+      #   batch.results  # => { "request_0" => Message, ... }
+      class Batch
+        attr_reader :id, :requests
+
+        # @param model [String] Model ID (e.g. 'gpt-4o')
+        # @param provider [Symbol, RubyLLM::Providers::OpenAIResponses] Provider slug or instance
+        # @param id [String, nil] Existing batch ID to resume
+        def initialize(model: nil, provider: :openai_responses, id: nil)
+          @model = model
+          @provider = resolve_provider(provider)
+          @requests = []
+          @request_counter = 0
+          @data = {}
+
+          return unless id
+
+          @id = id
+          refresh!
+        end
+
+        # Queue a request for inclusion in the batch.
+        # @param input [String, Array] User message or Responses API input array
+        # @param id [String, nil] Custom ID for this request (auto-generated if omitted)
+        # @param instructions [String, nil] System/developer instructions
+        # @param temperature [Float, nil] Sampling temperature
+        # @param tools [Array, nil] Tools configuration
+        # @return [self]
+        def add(input, id: nil, instructions: nil, temperature: nil, tools: nil, **extra) # rubocop:disable Metrics/ParameterLists
+          custom_id = id || "request_#{@request_counter}"
+          @request_counter += 1
+
+          body = { model: @model, input: Batches.normalize_input(input) }
+          body[:instructions] = instructions if instructions
+          body[:temperature] = temperature if temperature
+          body[:tools] = tools if tools
+          body.merge!(extra) unless extra.empty?
+
+          @requests << { custom_id: custom_id, body: body }
+          self
+        end
+
+        # Build JSONL, upload the file, and create the batch.
+        # @param metadata [Hash, nil] Optional metadata for the batch
+        # @return [self]
+        def create!(metadata: nil)
+          raise Error.new(nil, 'No requests added') if @requests.empty?
+          raise Error.new(nil, 'Batch already created') if @id
+
+          jsonl = Batches.build_jsonl(@requests)
+          file_id = upload_file(jsonl)
+
+          payload = {
+            input_file_id: file_id,
+            endpoint: '/v1/responses',
+            completion_window: '24h'
+          }
+          payload[:metadata] = metadata if metadata
+
+          response = @provider.instance_variable_get(:@connection).post(Batches.batches_url, payload)
+          @data = response.body
+          @id = @data['id']
+          self
+        end
+
+        # Fetch the latest batch status from the API.
+        # @return [self]
+        def refresh!
+          raise Error.new(nil, 'Batch not yet created') unless @id
+
+          response = @provider.instance_variable_get(:@connection).get(Batches.batch_url(@id))
+          @data = response.body
+          self
+        end
+
+        # @return [String, nil] Batch status
+        def status
+          @data['status']
+        end
+
+        # @return [Integer, nil] Number of completed requests
+        def completed_count
+          @data.dig('request_counts', 'completed')
+        end
+
+        # @return [Integer, nil] Total number of requests
+        def total_count
+          @data.dig('request_counts', 'total')
+        end
+
+        # @return [Integer, nil] Number of failed requests
+        def failed_count
+          @data.dig('request_counts', 'failed')
+        end
+
+        # @return [Boolean]
+        def completed?
+          status == Batches::COMPLETED
+        end
+
+        # @return [Boolean]
+        def in_progress?
+          Batches.pending?(status)
+        end
+
+        # @return [Boolean]
+        def failed?
+          status == Batches::FAILED
+        end
+
+        # @return [Boolean]
+        def expired?
+          status == Batches::EXPIRED
+        end
+
+        # @return [Boolean]
+        def cancelled?
+          status == Batches::CANCELLED
+        end
+
+        # Block until the batch reaches a terminal status.
+        # @param interval [Numeric] Seconds between polls (default: 30)
+        # @param timeout [Numeric, nil] Maximum seconds to wait
+        # @yield [Batch] Called after each poll
+        # @return [self]
+        def wait!(interval: 30, timeout: nil)
+          start_time = Time.now
+
+          loop do
+            refresh!
+            yield self if block_given?
+
+            break if Batches.terminal?(status)
+
+            if timeout && (Time.now - start_time) > timeout
+              raise Error.new(nil, "Batch polling timeout after #{timeout} seconds")
+            end
+
+            sleep interval
+          end
+
+          self
+        end
+
+        # Download and parse the output file into a Hash of Messages.
+        # @return [Hash<String, Message>] Results keyed by custom_id
+        def results
+          output_file_id = @data['output_file_id']
+          raise Error.new(nil, 'No output file available yet') unless output_file_id
+
+          jsonl = fetch_file_content(output_file_id)
+          Batches.parse_results_to_messages(jsonl)
+        end
+
+        # Download and parse the error file.
+        # @return [Array<Hash>] Error entries
+        def errors
+          error_file_id = @data['error_file_id']
+          return [] unless error_file_id
+
+          jsonl = fetch_file_content(error_file_id)
+          Batches.parse_errors(jsonl)
+        end
+
+        # Cancel the batch.
+        # @return [self]
+        def cancel!
+          raise Error.new(nil, 'Batch not yet created') unless @id
+
+          response = @provider.instance_variable_get(:@connection).post(Batches.cancel_batch_url(@id), {})
+          @data = response.body
+          self
+        end
+
+        private
+
+        def resolve_provider(provider)
+          case provider
+          when Symbol, String
+            slug = provider.to_sym
+            provider_class = RubyLLM::Provider.providers[slug]
+            raise Error.new(nil, "Unknown provider: #{slug}") unless provider_class
+
+            provider_class.new(RubyLLM.config)
+          else
+            provider
+          end
+        end
+
+        # Upload a JSONL string as a file to the Files API.
+        # @return [String] The uploaded file ID
+        def upload_file(jsonl)
+          io = StringIO.new(jsonl)
+          file_part = Faraday::Multipart::FilePart.new(io, 'application/jsonl', 'batch_requests.jsonl')
+
+          response = @provider.instance_variable_get(:@connection).post(Batches.files_url, {
+                                                                          file: file_part,
+                                                                          purpose: 'batch'
+                                                                        })
+          response.body['id']
+        end
+
+        # Download raw file content, bypassing JSON response middleware.
+        # @return [String] Raw file content
+        def fetch_file_content(file_id)
+          conn = @provider.instance_variable_get(:@connection)
+          response = conn.connection.get(Batches.file_content_url(file_id)) do |req|
+            req.headers.merge!(@provider.headers)
+          end
+          response.body
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module RubyLLM
+  module Providers
+    class OpenAIResponses
+      # Stateless helpers for the Batch API.
+      # Provides URL builders, JSONL serialization, status constants, and result parsing.
+      module Batches
+        module_function
+
+        # Status constants
+        VALIDATING = 'validating'
+        IN_PROGRESS = 'in_progress'
+        COMPLETED = 'completed'
+        FAILED = 'failed'
+        CANCELLED = 'cancelled'
+        CANCELLING = 'cancelling'
+        EXPIRED = 'expired'
+
+        TERMINAL_STATUSES = [COMPLETED, FAILED, CANCELLED, EXPIRED].freeze
+        PENDING_STATUSES = [VALIDATING, IN_PROGRESS, CANCELLING].freeze
+
+        # --- URL helpers ---
+
+        def files_url
+          'files'
+        end
+
+        def batches_url
+          'batches'
+        end
+
+        def batch_url(batch_id)
+          "batches/#{batch_id}"
+        end
+
+        def cancel_batch_url(batch_id)
+          "batches/#{batch_id}/cancel"
+        end
+
+        def file_content_url(file_id)
+          "files/#{file_id}/content"
+        end
+
+        # --- Status helpers ---
+
+        def terminal?(status)
+          TERMINAL_STATUSES.include?(status)
+        end
+
+        def pending?(status)
+          PENDING_STATUSES.include?(status)
+        end
+
+        # --- JSONL builder ---
+
+        # Build a JSONL string from an array of request hashes.
+        # Each request has: custom_id, body (the Responses API payload)
+        def build_jsonl(requests)
+          requests.map do |req|
+            JSON.generate({
+                            custom_id: req[:custom_id],
+                            method: 'POST',
+                            url: '/v1/responses',
+                            body: req[:body]
+                          })
+          end.join("\n")
+        end
+
+        # --- Input normalization ---
+
+        # Wraps a plain string into the Responses API input format.
+        def normalize_input(input)
+          case input
+          when String
+            [{ type: 'message', role: 'user', content: input }]
+          when Array
+            input
+          else
+            input
+          end
+        end
+
+        # --- Result parsing ---
+
+        # Parse JSONL output into an array of raw result hashes.
+        def parse_results(jsonl_string)
+          jsonl_string.each_line.filter_map do |line|
+            line = line.strip
+            next if line.empty?
+
+            JSON.parse(line)
+          end
+        end
+
+        # Parse JSONL output into a Hash of { custom_id => Message }.
+        # Reuses Chat.extract_output_text and Chat.extract_tool_calls to avoid duplication.
+        def parse_results_to_messages(jsonl_string)
+          results = parse_results(jsonl_string)
+          results.each_with_object({}) do |result, hash|
+            custom_id = result['custom_id']
+            response_body = result.dig('response', 'body')
+            next unless response_body
+
+            output = response_body['output'] || []
+            content = Chat.extract_output_text(output)
+            tool_calls = Chat.extract_tool_calls(output)
+            usage = response_body['usage'] || {}
+
+            hash[custom_id] = Message.new(
+              role: :assistant,
+              content: content,
+              tool_calls: tool_calls,
+              input_tokens: usage['input_tokens'],
+              output_tokens: usage['output_tokens'],
+              model_id: response_body['model']
+            )
+          end
+        end
+
+        # Parse JSONL error file into an array of error hashes.
+        def parse_errors(jsonl_string)
+          results = parse_results(jsonl_string)
+          results.select { |r| r.dig('response', 'status_code')&.>= 400 }
+        end
+      end
+    end
+  end
+end

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

@@ -12,7 +12,7 @@ module RubyLLM
 
         module_function
 
-        def render_payload(messages, tools:, temperature:, model:, stream: false, schema: nil, thinking: nil) # rubocop:disable Metrics/ParameterLists
+        def render_payload(messages, tools:, temperature:, model:, stream: false, schema: nil, thinking: nil) # rubocop:disable Metrics/ParameterLists,Lint/UnusedMethodArgument
           # Extract system messages for instructions
           system_messages = messages.select { |m| m.role == :system }
           non_system_messages = messages.reject { |m| m.role == :system }

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

@@ -191,7 +191,7 @@ module RubyLLM
         end
 
         def shell_tool(environment_type: 'container_auto', container_id: nil,
-                        network_policy: nil, memory_limit: nil)
+                       network_policy: nil, memory_limit: nil)
           env = if container_id
                   { type: 'container_reference', container_id: container_id }
                 else

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

@@ -11,16 +11,17 @@ 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
+      class WebSocket # rubocop:disable Metrics/ClassLength
         WEBSOCKET_PATH = '/v1/responses'
         KNOWN_PARAMS = %i[store metadata compact_threshold context_management].freeze
 
@@ -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, &)
           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, &)
+        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) # rubocop:disable Metrics/ParameterLists
+          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) # rubocop:disable Metrics/ParameterLists
           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?
@@ -219,8 +231,8 @@ module RubyLLM
           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) }
+          forwarded = extra.except(*KNOWN_PARAMS)
+          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,17 @@ 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}",
@@ -135,8 +146,53 @@ module RubyLLM
         response.body
       end
 
+      # --- Batch API ---
+
+      # List batches
+      # @param limit [Integer] Number of batches to return (default: 20)
+      # @param after [String, nil] Cursor for pagination
+      # @return [Hash] Batch listing with 'data' array
+      def list_batches(limit: 20, after: nil)
+        url = Batches.batches_url
+        params = { limit: limit }
+        params[:after] = after if after
+        response = @connection.get(url) do |req|
+          req.params.merge!(params)
+        end
+        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
+        @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)
@@ -145,8 +201,6 @@ module RubyLLM
         end
       end
 
-      public
-
       class << self
         def capabilities
           OpenAIResponses::Capabilities

data/lib/rubyllm_responses_api.rb

@@ -19,6 +19,8 @@ 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/model_registry'
 require_relative 'ruby_llm/providers/openai_responses/active_record_extension'
@@ -37,7 +39,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.5.0'
 
     # Shorthand access to built-in tool helpers
     BuiltInTools = Providers::OpenAIResponses::BuiltInTools
@@ -45,6 +47,22 @@ module RubyLLM
     Background = Providers::OpenAIResponses::Background
     Compaction = Providers::OpenAIResponses::Compaction
     Containers = Providers::OpenAIResponses::Containers
+    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
+
+    provider_class.new(config).list_batches(**kwargs)
+  end
 end

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.5.0
 platform: ruby
 authors:
 - Chris Hasinski
@@ -153,6 +153,8 @@ files:
 - lib/ruby_llm/providers/openai_responses/active_record_extension.rb
 - lib/ruby_llm/providers/openai_responses/background.rb
 - lib/ruby_llm/providers/openai_responses/base.rb
+- 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