openai 0.107.0 → 0.109.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e70580b3709d068f537d9eed65ea7e9da96f89e0e2260b36ebf23a9c3590ecf1
-  data.tar.gz: 83910cf81a9410c93588e877cca7f88e3d70cbe07e8eed3cd0789b08e3299a0c
+  metadata.gz: 54cd64155cb1af2bb57a7c61bc15355979a7c0d9e50951ce7e893911fcfe473b
+  data.tar.gz: 29101b3385b4be69545f1bd5516c90329c34d1e6f0bf303f28b5ea379b36fde8
 SHA512:
-  metadata.gz: 0e854d18548c800c72da1eb04b022befc61b36ccd3e1d24fa732db7b66a0d5c3fdca08a73dd0be579f97ad2c24fbf94f318c42e800eea5b9a8118b35b18b6cbe
-  data.tar.gz: 8dd6d3894a1137351eea2bcdad51308b46cdf025de798e913bc1f64c198beb31a264140dcd1c2d901249a21f0bea4c22a6ea61ed274a54f9f031fef73a457cf3
+  metadata.gz: b3d15cf0ee35ec3f58df82ea2f7249b62e63c02c1ee5351d0d6e95f50d1929c707a458225ee71e8568f816149a7c8346788286b22ba9ec38faeb42d3e511746c
+  data.tar.gz: b0e8720cecf2f4f600f7ac05226a8cbbba2eae974a81e0312b9d8ac88bef0bc7e4883a591ec2ac0fa2e9b30de13a79607a23b4a904f03f945fc10a79bb4a3913

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [0.109.0](https://github.com/openai/openai-ruby/compare/v0.108.0...v0.109.0) (2026-10-21)
+
+
+### Features
+
+* add Vertex AI support for the Responses API ([#952](https://github.com/openai/openai-ruby/issues/952)) ([98f5359](https://github.com/openai/openai-ruby/commit/98f5359e3ad2133abc5e914610fe7bbd2a058f8d))
+
+## [0.108.0](https://github.com/openai/openai-ruby/compare/v0.107.0...v0.108.0) (2026-10-21)
+
+
+### Features
+
+* add a bounded Chat Completions tool runner ([#943](https://github.com/openai/openai-ruby/issues/943)) ([db9f85f](https://github.com/openai/openai-ruby/commit/db9f85f42ac3f3d76678db18941c46e0468267a9))
+* **api:** add custom voice consent management ([#951](https://github.com/openai/openai-ruby/issues/951)) ([fc5256c](https://github.com/openai/openai-ruby/commit/fc5256c4332a1cf5b3d9567874c1d24085b574a1))
+
+
+### Bug Fixes
+
+* preserve accepted JSON through Responses session helpers ([#939](https://github.com/openai/openai-ruby/issues/939)) ([bdea98a](https://github.com/openai/openai-ruby/commit/bdea98a74c9ea093020c82375259baa6b23468d0))
+* preserve Realtime restore errors if abort fails ([#940](https://github.com/openai/openai-ruby/issues/940)) ([3f09468](https://github.com/openai/openai-ruby/commit/3f094684e1618878a6d4936acf1c970ef426afac))
+
+
+### Chores
+
+* **api:** clarify cache-write token totals ([#948](https://github.com/openai/openai-ruby/issues/948)) ([b0cb84d](https://github.com/openai/openai-ruby/commit/b0cb84db1759785b37a49b64b3f5398a63d81b1a))
+* **api:** preserve client configuration compatibility ([#944](https://github.com/openai/openai-ruby/issues/944)) ([4d9bb59](https://github.com/openai/openai-ruby/commit/4d9bb5986fcd13b36634d4396a5745eb9ad1de77))
+* **api:** preserve embedding helper loading ([#946](https://github.com/openai/openai-ruby/issues/946)) ([2965c7f](https://github.com/openai/openai-ruby/commit/2965c7fa3a66eeeb1ef77d37d67f6b73ca4d9701))
+* **api:** preserve SDK compatibility ([#949](https://github.com/openai/openai-ruby/issues/949)) ([38cd9bd](https://github.com/openai/openai-ruby/commit/38cd9bdbdd653470c85a534a0026dac2f2f448f1))
+* enforce zero customizations in generated files ([#950](https://github.com/openai/openai-ruby/issues/950)) ([b87c892](https://github.com/openai/openai-ruby/commit/b87c8928395a12c8e608c1b682e1ba9c1a984c75))
+
 ## [0.107.0](https://github.com/openai/openai-ruby/compare/v0.106.0...v0.107.0) (2026-10-20)
 
 

data/README.md

@@ -15,7 +15,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "openai", "~> 0.107.0"
+gem "openai", "~> 0.109.0"
 ```
 
 <!-- x-release-please-end -->
@@ -50,6 +50,54 @@ stream.each do |event|
 end
 ```
 
+### Automatic Chat Completions tool runner
+
+`client.chat.completions.run_tools` runs your function callbacks, sends their results
+back to the model, and returns the final `ChatCompletion`. It accepts the same
+messages, function-tool definitions (including `OpenAI::BaseModel` schemas), and
+request options as `create`:
+
+```ruby
+completion = client.chat.completions.run_tools(
+  model: "gpt-4o-mini",
+  messages: [{role: :user, content: "What is the weather in Seattle?"}],
+  tools: [WeatherArguments], # An OpenAI::BaseModel with a city field.
+  tool_handlers: {
+    "WeatherArguments" => -> (arguments) { {temperature_c: 18, city: arguments.fetch("city")} }
+  },
+  max_rounds: 10
+)
+puts(completion.choices.first.message.content)
+```
+
+Handlers receive a parsed JSON object with **string keys**; validate application
+requirements in your callback. String results are sent unchanged; other results
+are JSON encoded. Callbacks execute sequentially, including when the model requests
+multiple tools in one response. Setting `parallel_tool_calls: false` limits each
+response to one tool call; the runner rejects larger batches before callbacks run.
+Every advertised tool must have a matching handler.
+The runner validates each batch before invoking callbacks, rejects repeated call
+IDs, enforces the initial `tool_choice` before returning or invoking callbacks, and
+enforces the `tool_choice.allowed_tools.tools` subset on every round. It
+does not mutate your input messages or append the conversation to them.
+
+This helper is non-streaming and supports one completion choice and function tools.
+`max_rounds` limits API calls, including the final answer; it raises
+`OpenAI::Helpers::Chat::ToolRunner::MaxRoundsError` before executing tools in the
+last allowed round. A forced `tool_choice` applies to the first round, then switches
+to `auto` while preserving any allowed-tools list. Other invalid or incomplete tool
+responses raise `OpenAI::Helpers::Chat::ToolRunner::Error`.
+
+Callback, transport, and API errors stop the run and propagate to your application.
+Callback exception text is never submitted as a tool result, and HTTP retries do
+not rerun callbacks. Earlier callback side effects are not rolled back; starting another run
+can execute tools again. Use application-level idempotency where needed. Request
+timeouts apply per API call, not to callback execution or the entire run.
+Caller-supplied request idempotency keys are scoped to each round, so retries keep
+the same key without colliding with the next round.
+
+See [the complete example](examples/chat/tool_runner.rb).
+
 ### Agents final output (beta)
 
 Collect final output from an Agents creation stream:
@@ -508,6 +556,12 @@ client = OpenAI::Client.new(
 
 See [bedrock.md](bedrock.md) for authentication precedence, static and refreshable credentials, endpoint configuration, and SigV4 request constraints.
 
+## Google Vertex AI
+
+Use `OpenAI::Providers.vertex` with the Responses API. See [vertex.md](vertex.md)
+for setup with Google Application Default Credentials, a credentials object, or
+an access-token callback.
+
 ## Workload Identity Authentication
 
 For secure, automated environments like cloud-managed Kubernetes, Azure, and GCP, you can use workload identity authentication with short-lived tokens from cloud identity providers instead of long-lived API keys.

data/examples/chat/tool_runner.rb

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../../lib/openai"
+
+class WeatherArguments < OpenAI::BaseModel
+  required :city, String
+end
+
+client = OpenAI::Client.new
+calls = 0
+completion = client.chat.completions.run_tools(
+  model: "gpt-4o-mini",
+  messages: [{role: :user, content: "What is the weather in Seattle? Use the provided weather tool."}],
+  tools: [WeatherArguments],
+  tool_choice: {type: :function, function: {name: "WeatherArguments"}},
+  tool_handlers: {
+    "WeatherArguments" => -> (arguments) do
+      calls += 1
+      # Replace this synthetic result with your weather service.
+      {city: arguments.fetch("city"), temperature_c: 18, condition: "rain"}
+    end
+  },
+  max_rounds: 5
+)
+
+unless calls.positive? &&
+    completion.choices.first.finish_reason == :stop &&
+    !completion.choices.first.message.content.to_s.empty?
+  abort("Expected a weather callback and a final answer")
+end
+
+puts("Tool runner completed.")

data/lib/openai/client.rb

@@ -206,8 +206,8 @@ module OpenAI
     # @param base_url [String, nil] Override the default base URL for the API, e.g.,
     # `"https://api.example.com/v2/"`. Defaults to `ENV["OPENAI_BASE_URL"]`
     #
-    # @param data_residency [Symbol, String, nil] Select `global`, `us`, `eu`, or
-    #   `ae`. Mutually exclusive with an explicit `base_url` or `provider`.
+    # @param data_residency [Symbol, String, nil] Select `global`, `us`, `eu`, `ae`.
+    #   Mutually exclusive with an explicit `base_url` or `provider`.
     #   This selects an endpoint; project and model eligibility still apply.
     #
     # @param default_headers [Hash{String=>String, nil}, nil] Extra headers to send

data/lib/openai/helpers/chat/tool_runner.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+require_relative "../../internal/request_options_scope"
+
+module OpenAI
+  module Helpers
+    module Chat
+      # Executes a bounded, non-streaming Chat Completions function-tool loop.
+      class ToolRunner
+        class Error < StandardError
+        end
+
+        class MaxRoundsError < Error
+        end
+
+        # @api private
+        def initialize(completions:, params:, tool_handlers:, max_rounds:)
+          unless max_rounds.is_a?(Integer) && max_rounds.positive?
+            raise ArgumentError, "max_rounds must be a positive integer"
+          end
+
+          @completions = completions
+          @max_rounds = max_rounds
+          @params, options = OpenAI::Chat::CompletionCreateParams.dump_request(params)
+          @request_options = OpenAI::Internal::RequestOptionsScope.new(options)
+          @handlers = tool_handlers.to_h.dup
+          validate_options(options)
+
+          # Validate a separate copy: schema conversion must not replace the models
+          # used by create to parse the final completion's structured output.
+          definitions, = OpenAI::Chat::CompletionCreateParams.dump_request(params)
+          completions.get_structured_output_models(definitions)
+          names = definitions.fetch(:tools).map do |tool|
+            unless tool[:type] == :function || tool[:type] == "function"
+              raise ArgumentError, "run_tools supports function tools only"
+            end
+
+            name = tool.dig(:function, :name)
+            unless name.is_a?(String) && !name.empty? && @handlers[name].respond_to?(:call)
+              raise ArgumentError, "Each function tool must have a named callable in tool_handlers"
+            end
+
+            name
+          end
+
+          unless names.uniq.length == names.length && @handlers.keys.sort == names.sort
+            raise ArgumentError, "Tool definitions and tool_handlers must have matching, unique string names"
+          end
+
+          @allowed_names = allowed_tool_names(names)
+          @seen = {}
+          @params.fetch(:messages).each do |message|
+            Array(message[:tool_calls]).each { |call| @seen[call[:id]] = true }
+          end
+        end
+
+        # @api private
+        def run
+          @max_rounds.times do |round|
+            completion = create_completion(round)
+            assistant, prepared = prepare_completion(completion, round)
+            return completion unless assistant
+
+            @params[:messages] << assistant
+            prepared.each do |call, handler, arguments|
+              output = handler.call(arguments)
+              content = output.is_a?(String) ? output.dup : JSON.generate(output)
+              @params[:messages] << {role: :tool, tool_call_id: call[:id], content: content}
+            end
+
+            # A forced tool choice applies to the first round; allow a final answer.
+            # Preserve the caller's allowed-tools restriction, when supplied.
+            choice = @params[:tool_choice]
+            @params[:tool_choice] = if choice.is_a?(Hash) && choice[:type].to_s == "allowed_tools"
+              choice.merge(allowed_tools: choice.fetch(:allowed_tools).merge(mode: :auto))
+            else
+              :auto
+            end
+          end
+        end
+
+        private
+
+        def create_completion(round)
+          @completions.create_for_tool_runner(
+            @params.merge(request_options: @request_options.child("chat.tool_runner.round.#{round}"))
+          )
+        end
+
+        # Keep response validation separate from transport and callback execution.
+        def prepare_completion(completion, round)
+          unless completion.choices.length == 1
+            raise Error, "run_tools requires exactly one completion choice"
+          end
+
+          choice = completion.choices.first
+          message = choice.message
+          unless message.to_h.key?(:role) && message.role == :assistant
+            raise Error, "Expected an assistant message"
+          end
+
+          [:content, :refusal].each do |field|
+            value = message[field]
+            unless message.to_h.key?(field) && (value.nil? || value.is_a?(String))
+              raise Error, "Expected assistant content and refusal to be strings or null"
+            end
+          end
+
+          audio = message.audio
+          if audio && (!audio[:id].is_a?(String) || audio[:id].empty?)
+            raise Error, "Expected an audio reference with a nonempty string ID"
+          end
+
+          calls = message.tool_calls || []
+          if @params[:parallel_tool_calls] == false && calls.length > 1
+            raise Error, "Model returned multiple tool calls with parallel_tool_calls disabled"
+          end
+
+          validate_tool_choice(calls)
+          if choice.finish_reason == :stop && calls.empty? && message.function_call.nil?
+            return [nil, nil]
+          end
+
+          unless [:stop, :tool_calls].include?(choice.finish_reason) && !calls.empty? && message.function_call.nil?
+            raise Error, "Completion did not finish normally or provide complete function tool calls"
+          end
+
+          if round + 1 == @max_rounds
+            raise MaxRoundsError, "Tool runner reached max_rounds before a final completion"
+          end
+
+          # Prepare the entire batch before allowing any callback side effects.
+          prepared = calls.map { |call| prepare(call) }
+          assistant = message.to_h.slice(:role, :content, :refusal)
+          assistant[:tool_calls] = prepared.map { |call, _handler, _arguments| call }
+          assistant[:audio] = {id: audio.id} if audio
+          [assistant, prepared]
+        rescue KeyError, NoMethodError, TypeError, OpenAI::Errors::ConversionError
+          raise Error, "Malformed Chat Completion response", cause: nil
+        end
+
+        def validate_tool_choice(calls)
+          choice = @params[:tool_choice]
+          if choice == :none || choice == "none"
+            raise Error, "Model requested tools when tool_choice is none" unless calls.empty?
+            return
+          end
+
+          required = choice == :required || choice == "required"
+          if choice.is_a?(Hash)
+            case (choice[:type] || choice["type"]).to_s
+            when "allowed_tools"
+              required = choice.fetch(:allowed_tools).fetch(:mode).to_s == "required"
+            when "function"
+              required = true
+              function = choice[:function] || choice["function"]
+              name = function[:name] || function["name"]
+              unless calls.all? { |call| call.function.name == name }
+                raise Error, "Model did not call the forced function tool"
+              end
+            end
+          end
+
+          raise Error, "Model returned no tool calls for a required tool choice" if required && calls.empty?
+        end
+
+        def allowed_tool_names(names)
+          choice = @params[:tool_choice]
+          return names unless choice.is_a?(Hash) && (choice[:type] || choice["type"]).to_s == "allowed_tools"
+
+          choice = OpenAI::Chat::ChatCompletionAllowedToolChoice.dump(choice, state: {can_retry: true})
+          @params[:tool_choice] = choice
+          allowed = choice[:allowed_tools]
+          unless allowed.is_a?(Hash) && allowed[:tools].is_a?(Array)
+            raise ArgumentError, "allowed_tools must include a tools array"
+          end
+
+          allowed[:tools].map do |tool|
+            type = nil
+            function = nil
+            name = nil
+            type = tool[:type] || tool["type"] if tool.is_a?(Hash)
+            function = tool[:function] || tool["function"] if tool.is_a?(Hash)
+            name = function[:name] || function["name"] if function.is_a?(Hash)
+            unless type.to_s == "function" && names.include?(name)
+              raise ArgumentError, "allowed_tools must reference registered function tools"
+            end
+
+            name
+          end
+        end
+
+        def validate_options(options)
+          unless @params[:n].nil? || @params[:n] == 1
+            raise ArgumentError, "run_tools supports n: 1 only"
+          end
+
+          if @params[:stream] || @params[:functions] || @params[:function_call]
+            raise ArgumentError, "run_tools requires non-streaming function tools"
+          end
+
+          controlled = %w[messages tools tool_choice parallel_tool_calls n stream functions function_call]
+          if options[:extra_body]&.keys&.any? { |key| controlled.include?(key.to_s) }
+            raise ArgumentError, "extra_body cannot override tool runner control parameters"
+          end
+
+          unless @params[:messages].is_a?(Array) && @params[:tools].is_a?(Array)
+            raise ArgumentError, "messages and tools must be arrays"
+          end
+
+          unless @handlers.keys.all? { |name| name.is_a?(String) }
+            raise ArgumentError, "tool_handlers keys must be strings"
+          end
+        end
+
+        def prepare(call)
+          unless call.is_a?(OpenAI::Chat::ChatCompletionMessageFunctionToolCall) &&
+              [:function, "function"].include?(call[:type]) &&
+              call[:id].is_a?(String) &&
+              !call.id.empty? &&
+              !@seen.key?(call.id)
+            raise Error, "Expected a function tool call with a new, nonempty ID"
+          end
+
+          function = call.function
+          unless function.is_a?(OpenAI::Chat::ChatCompletionMessageFunctionToolCall::Function) &&
+              function[:name].is_a?(String) &&
+              function[:arguments].is_a?(String)
+            raise Error, "Expected a function tool payload"
+          end
+
+          handler = @handlers[function.name]
+          raise Error, "Model requested an unregistered function tool" unless handler
+          unless @allowed_names.include?(function.name)
+            raise Error, "Model requested a function tool that is not allowed"
+          end
+
+          arguments = begin
+            JSON.parse(function.arguments)
+          rescue JSON::ParserError, TypeError
+            raise Error, "Function arguments must be a valid JSON object", cause: nil
+          end
+
+          raise Error, "Function arguments must be a JSON object" unless arguments.is_a?(Hash)
+
+          @seen[call.id] = true
+          wire_call = {
+            id: call.id,
+            type: :function,
+            function: {name: function.name, arguments: function.arguments}
+          }
+          [wire_call, handler, arguments]
+        rescue OpenAI::Errors::ConversionError
+          raise Error, "Malformed function tool payload", cause: nil
+        end
+      end
+    end
+  end
+end

data/lib/openai/helpers/client_runtime.rb

@@ -101,6 +101,17 @@ module OpenAI
 
     # @api private
     private def send_request(request, redirect_count:, retry_count:, send_retry_header:)
+      if (wrapper = @provider_runtime&.wrap_request)
+        return wrapper.call(request, request_replayable?(request), retry_count) do |attempt, attempt_retry_count|
+          super(
+            attempt,
+            redirect_count: redirect_count,
+            retry_count: attempt_retry_count,
+            send_retry_header: send_retry_header
+          )
+        end
+      end
+
       if @workload_identity_auth && x509_transport?(@requester)
         canonical_headers = @requester.validate_api_request!(
           url: request.fetch(:url),

data/lib/openai/helpers/realtime/recovery.rb

@@ -306,8 +306,14 @@ module OpenAI
             # Shutdown must not mask the operation's result or prevent cleanup.
             nil
           ensure
-            physical.abort
-            @physical = nil
+            pending_error = $ERROR_INFO
+            begin
+              physical.abort
+            rescue StandardError
+              raise if pending_error.nil?
+            ensure
+              @physical = nil
+            end
           end
         end
       end

data/lib/openai/helpers/responses_websocket/incremental.rb

@@ -11,6 +11,8 @@ module OpenAI
     # are retained exactly as received, never filled from provisional output.
     # Call reset to discard all retained state.
     class IncrementalResponse
+      include OpenAI::WebSocket::Protocol
+
       attr_reader :phase
 
       def initialize
@@ -236,10 +238,12 @@ module OpenAI
       # references. Returned snapshots and incoming events must not share strings.
       def copy(value)
         data = OpenAI::Internal::Type::BaseModel.recursively_to_h(value, convert: false)
-        data = JSON.parse(JSON.generate(data), symbolize_names: true)
+        data = parse_json(generate_json(data))
         return data unless value.is_a?(OpenAI::Internal::Type::BaseModel)
 
         OpenAI::Internal::Type::Converter.coerce(value.class, data)
+      rescue SystemStackError
+        raise SessionError, "Could not copy the Responses WebSocket event.", cause: nil
       end
     end
   end

data/lib/openai/helpers/responses_websocket/session.rb

@@ -55,6 +55,8 @@ module OpenAI
 
     # @api private
     class SessionAccumulator
+      include OpenAI::WebSocket::Protocol
+
       attr_reader :final_response, :error
 
       def initialize(limit)
@@ -93,10 +95,10 @@ module OpenAI
         if type == "response.output_item.done"
           # Retain wire data independently of the mutable event returned by receive.
           completed_item = OpenAI::Internal::Type::BaseModel.recursively_to_h(event.item, convert: false)
-          @items[event.output_index] = JSON.parse(JSON.generate(completed_item), symbolize_names: true)
+          @items[event.output_index] = parse_json(generate_json(completed_item))
         elsif %w[response.completed response.failed response.incomplete].include?(type)
           data = OpenAI::Internal::Type::BaseModel.recursively_to_h(event, convert: false)
-          data = JSON.parse(JSON.generate(data), symbolize_names: true)
+          data = parse_json(generate_json(data))
           response = data.fetch(:response)
           if response[:output].nil?
             response = response.merge(output: @items.sort.map { |_index, item| item.to_h })
@@ -117,7 +119,7 @@ module OpenAI
           @state.handle_event(@decoder.decode(data))
         end
 
-      rescue StandardError => error
+      rescue StandardError, SystemStackError => error
         @error = error.is_a?(SessionError) ? error : SessionError.new("Could not collect the Responses final response.")
         clear
       end
@@ -313,6 +315,8 @@ module OpenAI
 
     # Owns one connection and one Async reader. Use only its lanes to receive.
     class Session
+      include OpenAI::WebSocket::Protocol
+
       attr_reader :limits, :default
 
       def self.open(
@@ -531,7 +535,7 @@ module OpenAI
         value = @lanes.fetch(data[:stream_id], @lanes[nil])
         return unless value
 
-        bytes = JSON.generate(data).bytesize
+        bytes = generate_json(data).bytesize
         if @events >= @limits.max_events || @bytes + bytes > @limits.max_bytes
           raise BufferError, "The Responses session exceeded its buffered event budget."
         end
@@ -544,6 +548,9 @@ module OpenAI
           consumed(bytes)
           raise
         end
+
+      rescue SystemStackError
+        raise SessionError, "Could not buffer the Responses WebSocket event.", cause: nil
       end
 
       private def stop_reader

data/lib/openai/helpers/streaming/chat_completion_resource.rb

@@ -1,9 +1,61 @@
 # frozen_string_literal: true
 
+require_relative "../chat/tool_runner"
+
 module OpenAI
   module Resources
     class Chat
       class Completions
+        # Run function tools until the model returns a final, non-streaming completion.
+        # Handlers receive a JSON object with string keys. String results are sent
+        # verbatim; other results are JSON encoded. Callback errors propagate without
+        # retrying callbacks or sending their exception text to the model.
+        # max_rounds bounds API calls (including the final answer), defaulting to 10.
+        # A forced tool choice applies only to the first round. Callbacks run serially.
+        #
+        # @param tool_handlers [Hash{String=>#call}]
+        # @param max_rounds [Integer]
+        # @param params [Hash] Other Chat Completions create parameters.
+        # @return [OpenAI::Models::Chat::ChatCompletion]
+        def run_tools(model:, messages:, tools:, tool_handlers:, max_rounds: 10, **params)
+          OpenAI::Helpers::Chat::ToolRunner
+            .new(
+              completions: self,
+              params: params.merge(model: model, messages: messages, tools: tools),
+              tool_handlers: tool_handlers,
+              max_rounds: max_rounds
+            )
+            .run
+        end
+
+        # @api private
+        # Buffer through the normal transport, then decode inside the runner's
+        # error boundary. Transport exceptions remain outside that boundary.
+        def create_for_tool_runner(params)
+          parsed, options = OpenAI::Chat::CompletionCreateParams.dump_request(params)
+          model, tool_models = get_structured_output_models(parsed)
+          parse = OpenAI::Helpers::StructuredOutput::ChatCompletionParser.build_unwrap(model, tool_models)
+          response = @client.request(
+            method: :post,
+            path: "chat/completions",
+            body: parsed,
+            model: StringIO,
+            security: {bearer_auth: true},
+            options: options
+          )
+
+          begin
+            raw = JSON.parse(response.string, symbolize_names: true)
+            completion = OpenAI::Internal::Type::Converter.coerce(OpenAI::Chat::ChatCompletion, parse.call(raw))
+            completion._set_last_response(response.last_response)
+            completion
+          rescue JSON::ParserError, KeyError, NoMethodError, TypeError, OpenAI::Errors::ConversionError
+            raise OpenAI::Helpers::Chat::ToolRunner::Error, "Malformed Chat Completion response", cause: nil
+          ensure
+            response.close
+          end
+        end
+
         def stream(params)
           parsed, options = OpenAI::Chat::CompletionCreateParams.dump_request(params)
 

data/lib/openai/internal/provider.rb

@@ -11,6 +11,7 @@ module OpenAI
         :name,
         :base_url,
         :prepare_request,
+        :wrap_request,
         :authentication_headers,
         keyword_init: true
       )

data/lib/openai/models/admin/organization/usage_audio_speeches_response.rb

@@ -243,8 +243,8 @@ module OpenAI
                 optional :input_cache_write_30m_tokens, Integer, nil?: true
 
                 # @!attribute input_cache_write_tokens
-                #   The aggregated number of input tokens written to the cache with a 30-minute
-                #   retention period.
+                #   The aggregated number of input tokens written to the cache across 30-minute and
+                #   12-hour retention periods.
                 #
                 #   @return [Integer, nil]
                 optional :input_cache_write_tokens, Integer
@@ -382,8 +382,8 @@ module OpenAI
                 #     retention period. May be absent or null for older responses.
                 #
                 #   @param input_cache_write_tokens [Integer]
-                #     The aggregated number of input tokens written to the cache with a 30-minute
-                #     retention period.
+                #     The aggregated number of input tokens written to the cache across 30-minute and
+                #     12-hour retention periods.
                 #
                 #   @param input_cached_audio_tokens [Integer]
                 #     The aggregated number of cached audio input tokens used.

data/lib/openai/models/admin/organization/usage_audio_transcriptions_response.rb

@@ -245,8 +245,8 @@ module OpenAI
                 optional :input_cache_write_30m_tokens, Integer, nil?: true
 
                 # @!attribute input_cache_write_tokens
-                #   The aggregated number of input tokens written to the cache with a 30-minute
-                #   retention period.
+                #   The aggregated number of input tokens written to the cache across 30-minute and
+                #   12-hour retention periods.
                 #
                 #   @return [Integer, nil]
                 optional :input_cache_write_tokens, Integer
@@ -384,8 +384,8 @@ module OpenAI
                 #     retention period. May be absent or null for older responses.
                 #
                 #   @param input_cache_write_tokens [Integer]
-                #     The aggregated number of input tokens written to the cache with a 30-minute
-                #     retention period.
+                #     The aggregated number of input tokens written to the cache across 30-minute and
+                #     12-hour retention periods.
                 #
                 #   @param input_cached_audio_tokens [Integer]
                 #     The aggregated number of cached audio input tokens used.