ruby_llm-responses_api 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c2d9ce65eebe6420f01878669d81f90f999b738158b17eaa558dd6c88226c2c2
-  data.tar.gz: c432ef2dfcebb290debbbc5ac5e72038081f54fc054065da1bee09465ba99ba0
+  metadata.gz: 5eafd14a08ce95dc9637f022c3dcd0b88dc979314efd534ec3a3d5dbb2a6e396
+  data.tar.gz: 6b84beeec2204e791727bb969aac9b9e490e574204c78ab87ec6b69692f1ad7d
 SHA512:
-  metadata.gz: 39bbbb38a8b7183ff501d092eab938f0ab6572129ca3cd518057daa04b21117ea38eb8c19ab1a6755036b41f683f3124a1c0209ee91c5f547fe12590b673bbf3
-  data.tar.gz: 74346a9093b98f079b02deffc3d9f8cbe9b8bf681d33a843d4bd130d099976f78d66a61a6c2b5032d31a84190e25b7509fe4e83f39fa278be2f74f5980568544
+  metadata.gz: 5216a047aa783ed7b221e91f0173fd5785ae003b3006a9dcbcdb07effef569e73cac28fab1129f9e157e15f03a5219d18fdcfcc84c17406f3913fe8cdc1ed761
+  data.tar.gz: 3aa365e82445b4deb9f3b2dcda4ec47f096728f05c3f7a89eb9076be41ba81e873e2f513b4057391b84d6f1e1b8fd630ade743a46b0c2a37f9c2187eb43efbd6

data/CHANGELOG.md

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

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.
@@ -314,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

@@ -21,7 +21,7 @@ module RubyLLM
       #   ws.connect
       #   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
 
@@ -96,7 +96,7 @@ 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, &block)
+        def call(payload, &)
           ensure_connected!
           acquire_flight!
 
@@ -105,7 +105,7 @@ module RubyLLM
 
           envelope = { type: 'response.create', response: payload.except(:stream) }
           send_json(envelope)
-          accumulate_response(queue, &block)
+          accumulate_response(queue, &)
         ensure
           @mutex.synchronize { @message_queue = nil }
           release_flight!
@@ -122,7 +122,7 @@ 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)
+        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,
@@ -221,7 +221,7 @@ module RubyLLM
           headers
         end
 
-        def build_standalone_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?
@@ -231,7 +231,7 @@ module RubyLLM
           State.apply_state_params(response, extra)
           Compaction.apply_compaction(response, extra)
 
-          forwarded = extra.reject { |k, _| KNOWN_PARAMS.include?(k) }
+          forwarded = extra.except(*KNOWN_PARAMS)
           response.merge(forwarded)
         end
 

data/lib/ruby_llm/providers/openai_responses.rb

@@ -20,7 +20,8 @@ module RubyLLM
       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)
+                                params: params.except(:transport), schema: schema,
+                                thinking: thinking, &block)
         else
           super
         end
@@ -145,9 +146,25 @@ 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)
+      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(
@@ -184,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.1'
+    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.1
+  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