openai 0.106.0 → 0.108.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c24e00e4168b6f3661b2eb29d8de97727d4bcd6a80e40f68512ab21c3c025b46
-  data.tar.gz: 16f33bff54375b5f3fb5174af63026f95e79ab2ca1cdfe6dd07cedfacac31568
+  metadata.gz: bbaffc5b480678a26851b73b6b49f9f63419801d8bbec633d6ed4f3765fe4717
+  data.tar.gz: 127b19570f47781df5644f2217d9405e1ea0e82279b319a7683c59b567cbbd72
 SHA512:
-  metadata.gz: 0fe9484b436e02d3b50981251596b57195cef1a604207b7b496049a2214b44eb3953447568b3dcfb3e1e0827279785587e66dfc1d2427c1fa858b7bcb87c54c1
-  data.tar.gz: 2cabbb26e7382803fbc4aa5ddcc47e3be1bad88c2d05510fb0a44f537653761a0c888157d407764ebeaab8de174cf5f8a44338ae868b16c016914b31cdd1978c
+  metadata.gz: ffe2a7748064e0cb03c1eb2482670a4f581323b02a0275fd9654e1f97ecaf85f9128e064f22b5075af7d615d0e9d4fee73144d57f07ceaa9dcde25a419f7b066
+  data.tar.gz: c531be809fb0b7dd69d4cb089eea59680a01dbcc258265e47ef6b16052ffd78eeba8f2ccf094ffaa694cdd2dca602b9ebceffa65e362de1427f51e04219a6192

data/CHANGELOG.md

@@ -1,5 +1,79 @@
 # Changelog
 
+## [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)
+
+
+### Features
+
+* **api:** add 30-minute cache-write usage counts ([#915](https://github.com/openai/openai-ruby/issues/915)) ([ea2dd66](https://github.com/openai/openai-ruby/commit/ea2dd66ed0c16e544490332fc2ea8ec4f5abd1bb))
+* **api:** add compaction trigger IDs ([#934](https://github.com/openai/openai-ruby/issues/934)) ([224e04a](https://github.com/openai/openai-ruby/commit/224e04ac2f610c793d772efafe7244d6c88039fc))
+
+
+### Bug Fixes
+
+* **api:** correct authentication security key types ([#938](https://github.com/openai/openai-ruby/issues/938)) ([4a5cc74](https://github.com/openai/openai-ruby/commit/4a5cc744b38dc39042d98ae2ff5a32fdd0247bc9))
+* decode base64 embedding vectors ([#942](https://github.com/openai/openai-ruby/issues/942)) ([d684df4](https://github.com/openai/openai-ruby/commit/d684df4dc2a633e34836a346bbbe1e7cbb3d2707))
+* drain audio diagnostics while waiting on input ([#920](https://github.com/openai/openai-ruby/issues/920)) ([8a0b876](https://github.com/openai/openai-ruby/commit/8a0b87606e55f26e86e289577cdfd2533c329ad6))
+* drain ready audio diagnostics without delay ([#918](https://github.com/openai/openai-ruby/issues/918)) ([3e87ce3](https://github.com/openai/openai-ruby/commit/3e87ce380fafe08bb4348b9b867d4006bb939e49))
+* keep Realtime diagnostic rendering payload-free ([#924](https://github.com/openai/openai-ruby/issues/924)) ([3a29026](https://github.com/openai/openai-ruby/commit/3a29026ab177704dbe30d688fddd085e737dfc6d))
+* preserve deep JSON in WebSocket event codecs ([#928](https://github.com/openai/openai-ruby/issues/928)) ([57462c9](https://github.com/openai/openai-ruby/commit/57462c938e3b7602c456b0816e8873bd67fad241))
+* preserve typed Realtime event identity ([#931](https://github.com/openai/openai-ruby/issues/931)) ([9bb5618](https://github.com/openai/openai-ruby/commit/9bb56187c7eb0d72f992c76fed68369d34972d81))
+* **realtime:** abort connections after failed or canceled WebSocket writes so buffered application data cannot be flushed later. On a poisoned connection, `close(code:, reason:)` aborts without a close handshake; the supplied code and reason are not sent. ([#914](https://github.com/openai/openai-ruby/issues/914)) ([d219f3d](https://github.com/openai/openai-ruby/commit/d219f3d0461dd96911429f1b89369eadd382f234))
+* report terminal Realtime failures before transport cleanup ([#923](https://github.com/openai/openai-ruby/issues/923)) ([0d21d75](https://github.com/openai/openai-ruby/commit/0d21d751cd89621c6a32c0048c45ef6e5b7c1af4))
+* retain Translation completion across callback exits ([#921](https://github.com/openai/openai-ruby/issues/921)) ([e6fb44e](https://github.com/openai/openai-ruby/commit/e6fb44e57d233e657d982eee4cf27c6a5d7977c7))
+* share strict WebSocket model validation ([#929](https://github.com/openai/openai-ruby/issues/929)) ([51c6f0b](https://github.com/openai/openai-ruby/commit/51c6f0b73081f0f02f981d2beb4a8b129b2ec1ba))
+* validate nested WebSocket wire field names ([#922](https://github.com/openai/openai-ruby/issues/922)) ([ae551ef](https://github.com/openai/openai-ruby/commit/ae551ef48d52d2c2f415f63c39e0c643fcfb1d75))
+* validate typed WebSocket event constants before conversion ([#925](https://github.com/openai/openai-ruby/issues/925)) ([3ae0cd3](https://github.com/openai/openai-ruby/commit/3ae0cd3070b4fcf046f8823f4cca1b7b8829effe))
+
+
+### Chores
+
+* **api:** clarify project API key update requirements ([#936](https://github.com/openai/openai-ruby/issues/936)) ([34606cc](https://github.com/openai/openai-ruby/commit/34606cc46087dae5a643256e9cae93966a106182))
+* **api:** Keep SDK maintenance checks aligned ([#917](https://github.com/openai/openai-ruby/issues/917)) ([ebe5bf4](https://github.com/openai/openai-ruby/commit/ebe5bf4dd74d87acf86e30f5c7a78350ce3f8e8d))
+* **api:** preserve audio transcription response compatibility ([#911](https://github.com/openai/openai-ruby/issues/911)) ([c93fb88](https://github.com/openai/openai-ruby/commit/c93fb88b350c80d724912351cf02d7ff51e3073a))
+* **api:** preserve JSON Schema adapter types ([#930](https://github.com/openai/openai-ruby/issues/930)) ([f1430b8](https://github.com/openai/openai-ruby/commit/f1430b8038c7f01123fbf9f2703f6eb5b7fa8c14))
+* **api:** preserve legacy Threads stream behavior ([#910](https://github.com/openai/openai-ruby/issues/910)) ([436887f](https://github.com/openai/openai-ruby/commit/436887fbe6bc3d0874cb75dca501ba1da0a9d9b4))
+* **api:** preserve optional Decisions usage filters ([#909](https://github.com/openai/openai-ruby/issues/909)) ([34f61df](https://github.com/openai/openai-ruby/commit/34f61dfc23bd1ade311e09a036ef6696af37c138))
+* **api:** preserve optional image edit safety identifiers ([#913](https://github.com/openai/openai-ruby/issues/913)) ([6bbfad1](https://github.com/openai/openai-ruby/commit/6bbfad1a6305b5efc71dbb41dce8560d2865bda2))
+* **api:** preserve standard library loading ([#935](https://github.com/openai/openai-ruby/issues/935)) ([a742640](https://github.com/openai/openai-ruby/commit/a7426400cf499f0d88c9e88e694d86369f8d9cb5))
+* **deps-dev:** bump the development-dependencies group with 3 updates ([#912](https://github.com/openai/openai-ruby/issues/912)) ([1227860](https://github.com/openai/openai-ruby/commit/1227860daec638117ce1f14dcd570cffc92c9647))
+* **deps:** bump ruby/setup-ruby from 1.329.0 to 1.331.0 ([#937](https://github.com/openai/openai-ruby/issues/937)) ([8b3ab95](https://github.com/openai/openai-ruby/commit/8b3ab95e7332a7c5325b4718d4e01246c5a54054))
+* prepare generic WebSocket binding signatures ([#941](https://github.com/openai/openai-ruby/issues/941)) ([9206c8c](https://github.com/openai/openai-ruby/commit/9206c8ceb99cc18df859d06c251fa5336c59ecdf))
+
+
+### Documentation
+
+* clarify Realtime guide scope and Translation support ([#905](https://github.com/openai/openai-ruby/issues/905)) ([efb4004](https://github.com/openai/openai-ruby/commit/efb4004aa49a8a4374833f4b07fbd373fdebb685))
+
+
+### Refactors
+
+* share Live codecs and use generated sideband commands ([#933](https://github.com/openai/openai-ruby/issues/933)) ([02861d0](https://github.com/openai/openai-ruby/commit/02861d0780eb18f493f881cfa9ed7cdf9a68abe3))
+* share Translation and binding event codecs ([#932](https://github.com/openai/openai-ruby/issues/932)) ([7dc0088](https://github.com/openai/openai-ruby/commit/7dc00884ba30a54a965fc41e8b19e1840e9faec9))
+
 ## [0.106.0](https://github.com/openai/openai-ruby/compare/v0.105.0...v0.106.0) (2026-10-17)
 
 

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.106.0"
+gem "openai", "~> 0.108.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:

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/live/websocket.rb

@@ -26,6 +26,8 @@ module OpenAI
     # A future server event retains its raw data, but routine diagnostics do not
     # render potentially sensitive audio, transcript, or session fields.
     class UnknownServerEvent
+      include OpenAI::WebSocket::Protocol
+
       attr_reader :type, :data
 
       def initialize(data:)
@@ -38,160 +40,33 @@ module OpenAI
       def inspect = "#<#{self.class} type=#{@type.inspect}>"
       alias to_s inspect
 
-      private def freeze_json(value)
-        pending = [value]
-        visited = {}.compare_by_identity
-        until pending.empty?
-          item = pending.pop
-          next if visited.key?(item)
-          visited[item] = true
-          case item
-          when Hash
-            item.each { |key, val| pending.push(key, val) }
-          when Array
-            pending.concat(item)
-          end
-
-          item.freeze
-        end
-
-        value
-      end
     end
 
     # A transport-open primary connection. Startup is owned by the caller:
     # send session.start and observe session.started before further commands.
-    class Connection < OpenAI::WebSocket::Connection
-      include OpenAI::WebSocket::Protocol
-      include OpenAI::WebSocket::GuardedConnection
-
+    class Connection < OpenAI::WebSocket::TypedConnection
       # @api private
       def initialize(socket:, url:)
-        super
+        super(socket: socket, url: url, client_event: client_event_type, server_event: server_event_type)
         @poisoned = false
         @closed = false
-        @server_event_names = discriminator_values(server_event_type)
-        @client_event_names = discriminator_values(client_event_type)
-      end
-
-      def send_event(event)
-        send_raw(encode_client_event(event))
       end
 
-      private def encode_client_event(event)
-        validate_event_tree!(event)
-        payload = OpenAI::Internal::Type::Converter.dump(client_event_type, event)
-        type = payload[:type] || payload["type"] if payload.is_a?(Hash)
-        raise ArgumentError unless (type.is_a?(String) || type.is_a?(Symbol)) && @client_event_names.key?(type.to_s)
-
-        coerced = coerce_event(client_event_type, payload, outbound: true)
-        serialized = OpenAI::Internal::Type::Converter.dump(client_event_type, coerced)
-        validate_event_tree!(serialized, json_only: true)
-        JSON.generate(serialized, max_nesting: false)
-      rescue StandardError, SystemStackError
-        raise ArgumentError, "Invalid Live client event.", cause: nil
-      end
+      private :parse_event
 
-      private def parse_event(data)
-        parsed = JSON.parse(data, symbolize_names: true, max_nesting: false)
-        type = event_type(parsed, message: "Live server event must be an object with a string type")
-        unless @server_event_names.key?(type.to_s)
-          return OpenAI::Live::UnknownServerEvent.new(data: parsed)
-        end
+      private def coerce_client_event(payload) = coerce_event(@client_event, payload, outbound: true)
 
-        event = coerce_event(server_event_type, parsed)
+      private def coerce(type, payload)
+        event = coerce_event(type, payload)
         validate_event_tree!(event)
         event
-      rescue StandardError, SystemStackError
-        raise OpenAI::Errors::LiveProtocolError.new, cause: nil
       end
 
-      private def coerce_event(union, payload, outbound: false)
-        state = OpenAI::Internal::Type::Converter.new_coerce_state(request_only: outbound)
-        event = OpenAI::Internal::Type::Converter.coerce(union, payload, state: state)
-        raise ArgumentError if state[:error] || !state.fetch(:exactness).fetch(:no).zero?
-        pending = [event]
-        until pending.empty?
-          value = pending.pop
-          case value
-          when OpenAI::Internal::Type::BaseModel
-            value.class.fields.each do |name, field|
-              if field.fetch(:required) &&
-                  field.fetch(:mode) != (outbound ? :coerce : :dump) &&
-                  (!outbound || field.fetch(:const) == OpenAI::Internal::OMIT) &&
-                  !value.to_h.key?(name)
-                raise ArgumentError
-              end
-            end
-
-            pending.concat(value.to_h.values)
-          when Hash
-            pending.concat(value.values)
-          when Array
-            pending.concat(value)
-          end
-        end
-
-        event
-      end
+      private def client_event_error_message = "Invalid Live client event."
 
-      private def validate_event_tree!(event, json_only: false)
-        ancestors = {}.compare_by_identity
-        pending = [[event, false]]
-        until pending.empty?
-          value, exiting = pending.pop
-          if exiting
-            ancestors.delete(value)
-            next
-          end
+      private def unknown_server_event(payload) = OpenAI::Live::UnknownServerEvent.new(data: payload)
 
-          children = case value
-          when OpenAI::Internal::Type::BaseModel
-            raise ArgumentError if json_only
-            data = value.to_h
-            keys = {}
-            data.each do |key, val|
-              name = key.is_a?(String) ? key.to_sym : key
-              field = value.class.known_fields[name]
-              serialized_name = field ? field.fetch(:api_name).to_s : name.to_s
-              raise ArgumentError if keys.key?(serialized_name)
-              keys[serialized_name] = true
-              next unless field
-              const = field.fetch(:const)
-              next if const == OpenAI::Internal::OMIT
-              if const.is_a?(Symbol)
-                raise ArgumentError unless (val.is_a?(String) || val.is_a?(Symbol)) && val.to_s == const.to_s
-              elsif val != const
-                raise ArgumentError
-              end
-            end
-
-            [data]
-          when Hash
-            keys = {}
-            value.each_key do |key|
-              raise ArgumentError unless key.is_a?(String) || key.is_a?(Symbol)
-              name = key.to_s
-              raise ArgumentError if keys.key?(name)
-              keys[name] = true
-            end
-
-            value.values
-          when Array
-            value
-          when NilClass, TrueClass, FalseClass, String, Integer, Float, Symbol
-            next
-          else
-            raise ArgumentError if json_only
-            next
-          end
-
-          raise ArgumentError if ancestors.key?(value)
-          ancestors[value] = true
-          pending << [value, true]
-          children.each { |child| pending << [child, false] }
-        end
-      end
+      private def protocol_error = OpenAI::Errors::LiveProtocolError.new
 
       private def transport_error = OpenAI::Errors::LiveConnectionError.new(url: @url)
       private def failed_read_message = "Cannot read from a failed Live WebSocket."
@@ -206,11 +81,7 @@ module OpenAI
 
     # Attached to an existing session; no new session.start handshake is sent.
     class SidebandConnection < Connection
-      # @api private
-      def initialize(socket:, url:)
-        super
-        @client_event_names = @client_event_names.except("session.start", "session.input_audio.append")
-      end
+      private def client_event_type = OpenAI::Live::SidebandClientEvent
     end
 
     # Caller-driven startup using overrides for an eligible stored session.