openai 0.81.0 → 0.83.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97ce6ca6902b7dc85c97989c0555036a7fe45783129a2139186d0cee87f36cb0
-  data.tar.gz: 15132d79dd284edb8fa80e3f6d0a72a7b0345285770182b93e6d3e376218c9ae
+  metadata.gz: 06b53caabbe2b1546ef4ec0eb7f677b8de5cb6d193a65e6a7e37b937459e84b1
+  data.tar.gz: af8a795be6bc7ee391b58b35a48e7a6eb49562c67a98d548437fad6f85871a48
 SHA512:
-  metadata.gz: 21a457fa9fcbf0a59f7ed109acee5a0d55b47a757d9d1a0dfbc12fee70a07cf3766d0369c512a923d117f6a1f6c2179810d8f81c5edf48ba7e7de18c611c083f
-  data.tar.gz: 1d0bc3c3de8bd6180b293e14ae6b4b15cead9feb6a8fe6ae49bf65fc140c3d7f6a473fa75d7f85a1436be47ab3ec7fdaaf38b9164746a7b293c19a861482d107
+  metadata.gz: 0a4a975d009308c39829498c31a41cd7ff1e4d6d34302251a2ad1a96858892a6ca52dfb7bb2791dfae729cc000c9c191ced27ae413f96b4a15b1f93f3d729c80
+  data.tar.gz: af0e5f84ca22955f73cecafe5a06bd9180c414c410cd1d8a88f36ae4566bfcdf43cdbba3300f24648e5cfbea993bd9093f0edc57304b183af6328a0826ad026e

data/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## [0.83.0](https://github.com/openai/openai-ruby/compare/v0.82.0...v0.83.0) (2026-08-27)
+
+
+### Features
+
+* **api:** add compute_units to Responses and Chat Completions usage ([#543](https://github.com/openai/openai-ruby/issues/543)) ([b128f89](https://github.com/openai/openai-ruby/commit/b128f89672416a083addeb0e2bbc337f8ddb7f9f))
+* expose opt-in raw response bodies on response metadata ([#544](https://github.com/openai/openai-ruby/issues/544)) ([1529e96](https://github.com/openai/openai-ruby/commit/1529e96781c217828915ed3f69faa61bf6605129))
+
+
+### Bug Fixes
+
+* **realtime:** clean up interrupted WebRTC call allocations ([#534](https://github.com/openai/openai-ruby/issues/534)) ([2057039](https://github.com/openai/openai-ruby/commit/205703935bafe5e78b90b5424cc43d3b7b978772))
+
+
+### Chores
+
+* **deps:** bump the codeql group with 2 updates ([#541](https://github.com/openai/openai-ruby/issues/541)) ([b15451c](https://github.com/openai/openai-ruby/commit/b15451c0df8ba890f136c86dc7f5299876bb9b5d))
+
+## [0.82.0](https://github.com/openai/openai-ruby/compare/v0.81.0...v0.82.0) (2026-08-27)
+
+
+### Features
+
+* add optional Sorbet structured-output models ([#537](https://github.com/openai/openai-ruby/issues/537)) ([53ccf39](https://github.com/openai/openai-ruby/commit/53ccf39b464d8b2052456fa78aaea4dcdee8158c))
+* **api:** make function call output call IDs optional ([#539](https://github.com/openai/openai-ruby/issues/539)) ([81d385b](https://github.com/openai/openai-ruby/commit/81d385be58ece0c5db798ed79d01c0fd4c458f60))
+
+
+### Bug Fixes
+
+* **streaming:** preserve unknown Responses stream events ([#538](https://github.com/openai/openai-ruby/issues/538)) ([1d728f7](https://github.com/openai/openai-ruby/commit/1d728f74649c039ad29ca55986f9f5f48436d9f0))
+
 ## [0.81.0](https://github.com/openai/openai-ruby/compare/v0.80.0...v0.81.0) (2026-08-26)
 
 

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.81.0"
+gem "openai", "~> 0.83.0"
 ```
 
 <!-- x-release-please-end -->
@@ -764,6 +764,58 @@ response = client.responses.create(
 
 </details>
 
+#### Sorbet structured-output models
+
+Applications that use Sorbet can provide their own `T::Struct` models instead of
+subclassing `OpenAI::BaseModel`. Add `sorbet-runtime` to your application's
+dependencies and explicitly load the optional integration:
+
+```ruby
+require "openai"
+require "openai/helpers/sorbet"
+
+class Participant < T::Struct
+  const :name, String
+  const :email, T.nilable(String)
+end
+
+class CalendarEvent < T::Struct
+  const :title, String
+  const :participants, T::Array[Participant]
+end
+
+schema = OpenAI::StructuredOutput.from_sorbet(CalendarEvent)
+client = OpenAI::Client.new
+
+response = client.responses.create(
+  model: "gpt-5.2",
+  input: "Extract the event information.",
+  text: schema
+)
+
+message = response.output.grep(OpenAI::Responses::ResponseOutputMessage).fetch(0)
+output_text = message.content.grep(OpenAI::Responses::ResponseOutputText).fetch(0)
+event = T.cast(output_text.parsed, CalendarEvent)
+event.participants.fetch(0).name
+
+completion = client.chat.completions.create(
+  model: "gpt-5.2",
+  messages: [{role: :user, content: "Extract the event information."}],
+  response_format: schema
+)
+
+T.cast(completion.choices.fetch(0).message.parsed, CalendarEvent)
+```
+
+The integration supports nested structs, arrays, nullable values, boolean and
+numeric fields, application-defined `T::Enum` values, and Sorbet's `name:` field
+aliases. All structured-output fields are required, including nullable fields.
+Unsupported unions, hashes, recursive models, and enum values that do not
+serialize to strings are rejected. `sorbet-runtime` remains optional and is not
+loaded by ordinary SDK usage. This integration supports non-streaming
+`responses.create` and `chat.completions.create` requests only; streaming
+structured outputs and function-tool schemas are not supported.
+
 ### Handling errors
 
 When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of `OpenAI::Errors::APIError` will be thrown:

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

@@ -5,6 +5,113 @@ module OpenAI
     module Realtime
       # Realtime request integration kept outside the generated client implementation.
       module ClientExtension
+        MAX_CALL_CLEANUP_SECONDS = 5.0
+        private_constant :MAX_CALL_CLEANUP_SECONDS
+
+        # A generated WebRTC allocation belongs to the SDK until its complete raw
+        # response can be returned. Keep this lifecycle outside generated resources.
+        def request(req)
+          unless req.is_a?(Hash) &&
+              req[:method] == :post &&
+              req[:path] == "realtime/calls" &&
+              req[:model] == OpenAI::HTTPClient::Response
+            return super
+          end
+
+          delivered = false
+          allocated_response = nil
+          call_id = nil
+          begin
+            url, response, log_context = perform_request(req) do |received_response, request_url, response_url|
+              if received_response.status == 201
+                allocated_response = received_response
+                if response_url.path == request_url.path &&
+                    realtime_call_origin(response_url).casecmp?(realtime_call_origin(request_url))
+                  call_id = realtime_call_id_from_location(
+                    received_response.headers["location"],
+                    request_url: request_url
+                  )
+                end
+              end
+            end
+
+            result = finish_request(log_context, response) do
+              parse_response(req, url: url, response: response)
+            end
+
+            delivered = true
+            result
+          ensure
+            unless delivered
+              begin
+                OpenAI::Internal::Util.close_fused!(allocated_response.body) if allocated_response
+              rescue StandardError, *(defined?(::Async::Stop) ? [::Async::Stop] : [])
+                nil
+              ensure
+                cleanup_created_realtime_call(call_id, options: req[:options]) if call_id
+              end
+            end
+          end
+        end
+
+        private def realtime_call_id_from_location(location, request_url:)
+          return if location.nil? || location.empty?
+
+          call_url = URI.join(request_url.to_s, location)
+          unless call_url.is_a?(URI::HTTP) &&
+              !call_url.host.to_s.empty? &&
+              call_url.userinfo.nil? &&
+              call_url.fragment.nil?
+            return
+          end
+
+          return unless realtime_call_origin(request_url).casecmp?(realtime_call_origin(call_url))
+
+          prefix = "#{request_url.path}/"
+          return unless call_url.path.start_with?(prefix)
+
+          call_id = call_url.path.delete_prefix(prefix)
+          call_id if /\A[A-Za-z0-9_-]+\z/.match?(call_id)
+        rescue URI::InvalidURIError, ArgumentError
+          nil
+        end
+
+        private def realtime_call_origin(url)
+          origin = OpenAI::Internal::Util.uri_origin(url)
+          if url.host.start_with?("[") && !url.hostname.start_with?("v", "V")
+            origin = origin.sub(url.host, "[#{IPAddr.new(url.hostname)}]")
+          end
+
+          origin
+        end
+
+        private def cleanup_created_realtime_call(call_id, options:)
+          cleanup_options = options.to_h.slice(:extra_headers, :extra_query, :timeout)
+          timeout = cleanup_options.fetch(:timeout, @timeout)
+          timeout = MAX_CALL_CLEANUP_SECONDS unless timeout&.positive?
+          cleanup_options[:timeout] = [timeout, MAX_CALL_CLEANUP_SECONDS].min
+          cleanup_options[:max_retries] = 0
+          task = ::Async::Task.current? if defined?(::Async::Task)
+          cleanup = lambda do
+            Timeout.timeout(cleanup_options.fetch(:timeout)) do
+              realtime.calls.hangup(call_id, request_options: cleanup_options)
+            end
+          end
+
+          if task
+            if task.respond_to?(:defer_cancel)
+              task.defer_cancel(&cleanup)
+            else
+              task.defer_stop(&cleanup)
+            end
+          else
+            cleanup.call
+          end
+
+        rescue StandardError, *(defined?(::Async::Stop) ? [::Async::Stop] : [])
+          nil
+        end
+
         # Build a fully authenticated Realtime WebSocket handshake request. Realtime
         # transports use this boundary so provider authentication and request options stay
         # consistent with ordinary SDK requests.

data/lib/openai/helpers/sorbet.rb

@@ -0,0 +1,324 @@
+# frozen_string_literal: true
+
+begin
+  require "sorbet-runtime"
+
+rescue LoadError => e
+  raise unless e.path == "sorbet-runtime"
+
+  raise LoadError, "Sorbet structured outputs require the optional sorbet-runtime gem"
+end
+
+require "openai"
+
+module OpenAI
+  module Helpers
+    module StructuredOutput
+      # Adapts application-owned Sorbet models to structured output requests.
+      #
+      # Load explicitly with `require "openai/helpers/sorbet"`.
+      class SorbetAdapter
+        include OpenAI::Internal::Type::Converter
+        include OpenAI::Helpers::StructuredOutput::JsonSchemaConverter
+
+        class HydrationError < TypeError
+        end
+
+        Field = Data.define(:name, :wire_name, :node)
+        Node = Data.define(:kind, :value, :nullable)
+        private_constant :Field, :Node
+
+        # @return [String]
+        attr_reader :name
+
+        # @param model [Class<T::Struct>]
+        def initialize(model)
+          unless model.is_a?(Class) && model < T::Struct && !model.name.to_s.empty?
+            raise ArgumentError, "#{model} must be a named T::Struct subclass"
+          end
+
+          @name = model.name
+          @compiled_structs = {}
+          @node = compile_struct(model, path: @name, ancestors: [])
+        end
+
+        # @return [Hash{Symbol=>Object}]
+        def to_json_schema = OpenAI::Helpers::StructuredOutput::JsonSchemaConverter.to_json_schema(self)
+
+        # @api private
+        def to_json_schema_inner(state:) = schema_for(@node, state: state)
+
+        # @api private
+        def coerce(value, state:)
+          return value if value.nil? || value.is_a?(JSON::ParserError)
+
+          hydrated = hydrate(@node, value, path: @name.split("::").last)
+          state.fetch(:exactness)[:yes] += 1
+          hydrated
+        end
+
+        private def compile_struct(model, path:, ancestors:)
+          if ancestors.include?(model)
+            raise ArgumentError, "#{path}: recursive Sorbet models are not supported"
+          end
+
+          return @compiled_structs.fetch(model) if @compiled_structs.key?(model)
+
+          fields = model.props.map do |field_name, rules|
+            wire_name = rules.fetch(:serialized_form)
+            type = rules.fetch(:type_object)
+            child = compile_type(type, path: "#{path}.#{field_name}", ancestors: [*ancestors, model])
+
+            Field.new(name: field_name, wire_name: wire_name, node: child)
+          end
+
+          if (duplicate = fields.map(&:wire_name).tally.find { _2 > 1 })
+            raise ArgumentError, "#{path}: duplicate serialized field name #{duplicate.first.inspect}"
+          end
+
+          @compiled_structs.store(model, Node.new(kind: :object, value: [model, fields], nullable: false))
+        end
+
+        private def compile_type(type, path:, ancestors:)
+          case type
+          in T::Types::TypedArray
+            item = compile_type(type.type, path: "#{path}[]", ancestors: ancestors)
+            Node.new(kind: :array, value: item, nullable: false)
+          in T::Types::Union
+            compile_union(type, path: path, ancestors: ancestors)
+          in T::Types::Simple
+            compile_class(type.raw_type, path: path, ancestors: ancestors)
+          else
+            raise ArgumentError, "#{path}: unsupported Sorbet type #{type}"
+          end
+        end
+
+        private def compile_union(type, path:, ancestors:)
+          members = type.types
+          nullable, remaining = members.partition do |member|
+            member.is_a?(T::Types::Simple) && member.raw_type == NilClass
+          end
+
+          node = if boolean_members?(remaining)
+            Node.new(kind: :boolean, value: nil, nullable: false)
+          elsif remaining.length == 1 && nullable.length == 1
+            compile_type(remaining.first, path: path, ancestors: ancestors)
+          else
+            raise ArgumentError, "#{path}: unsupported Sorbet union #{type}"
+          end
+
+          node.with(nullable: !nullable.empty?)
+        end
+
+        private def boolean_members?(members)
+          members.length == 2 &&
+            members.all? { _1.is_a?(T::Types::Simple) } &&
+            members.map(&:raw_type).to_set == [TrueClass, FalseClass].to_set
+        end
+
+        private def compile_class(type, path:, ancestors:)
+          if [String, Integer, Float].include?(type)
+            Node.new(kind: :scalar, value: type, nullable: false)
+          elsif type < T::Enum
+            unless type.values.all? { _1.serialize.is_a?(String) }
+              raise ArgumentError, "#{path}: Sorbet enum values must serialize to strings"
+            end
+
+            Node.new(kind: :enum, value: type, nullable: false)
+          elsif type < T::Struct
+            compile_struct(type, path: path, ancestors: ancestors)
+          else
+            raise ArgumentError, "#{path}: unsupported Sorbet class #{type}"
+          end
+        end
+
+        private def schema_for(node, state:)
+          schema = case node.kind
+          in :object
+            model, fields = node.value
+            OpenAI::Helpers::StructuredOutput::JsonSchemaConverter.cache_def!(state, type: model) do
+              properties = fields.to_h do |field|
+                child_state = {**state, path: [*state.fetch(:path), ".#{field.wire_name}"]}
+
+                [field.wire_name.to_sym, schema_for(field.node, state: child_state)]
+              end
+
+              {
+                type: "object",
+                properties: properties,
+                required: fields.map(&:wire_name),
+                additionalProperties: false
+              }
+            end
+
+          in :array
+            {type: "array", items: schema_for(node.value, state: state)}
+          in :boolean
+            {type: "boolean"}
+          in :enum
+            {type: "string", enum: node.value.values.map(&:serialize)}
+          in :scalar
+            {type: {String => "string", Integer => "integer", Float => "number"}.fetch(node.value)}
+          end
+
+          if node.nullable
+            if [:object, :enum].include?(node.kind)
+              {anyOf: [schema, {type: "null"}]}
+            else
+              OpenAI::Helpers::StructuredOutput::JsonSchemaConverter.to_nilable(schema)
+            end
+          else
+            schema
+          end
+        end
+
+        private def hydrate(node, value, path:)
+          return nil if value.nil? && node.nullable
+
+          case node.kind
+          in :object
+            hydrate_struct(node.value, value, path: path)
+          in :array
+            unless value.is_a?(Array)
+              fail_hydration(path, expected: "Array", actual: value)
+            end
+
+            value.map.with_index { |item, index| hydrate(node.value, item, path: "#{path}[#{index}]") }
+          in :enum
+            unless value.is_a?(String)
+              fail_hydration(path, expected: node.value.name, actual: value)
+            end
+
+            begin
+              node.value.deserialize(value)
+            rescue StandardError
+              fail_hydration(path, expected: node.value.name, actual: value)
+            end
+
+          in :boolean
+            unless value.equal?(true) || value.equal?(false)
+              fail_hydration(path, expected: "Boolean", actual: value)
+            end
+
+            value
+          in :scalar
+            value = value.to_f if node.value == Float && value.is_a?(Integer)
+
+            unless value.is_a?(node.value) && (node.value != Float || value.finite?)
+              fail_hydration(path, expected: node.value.name, actual: value)
+            end
+
+            value
+          end
+        end
+
+        private def hydrate_struct(shape, value, path:)
+          model, fields = shape
+          unless value.is_a?(Hash)
+            fail_hydration(path, expected: model.name, actual: value)
+          end
+
+          expected_names = fields.map(&:wire_name).to_set
+          unless value.keys.all? { (_1.is_a?(Symbol) || _1.is_a?(String)) && expected_names.include?(_1.to_s) }
+            raise HydrationError, "#{path}: unexpected structured-output field", cause: nil
+          end
+
+          attributes = fields.to_h do |field|
+            keys = [field.wire_name.to_sym, field.wire_name].select { value.key?(_1) }
+            field_path = "#{path}.#{field.name}"
+            unless keys.one?
+              reason = keys.empty? ? "missing required field" : "duplicate field"
+              raise HydrationError, "#{field_path}: #{reason}", cause: nil
+            end
+
+            [field.name, hydrate(field.node, value.fetch(keys.first), path: field_path)]
+          end
+
+          begin
+            model.new(**attributes)
+          rescue StandardError
+            raise HydrationError, "#{path}: invalid #{model.name} structured output", cause: nil
+          end
+        end
+
+        private def fail_hydration(path, expected:, actual:)
+          raise HydrationError, "#{path}: expected #{expected}, got #{actual.class}", cause: nil
+        end
+      end
+
+      # @param model [Class<T::Struct>]
+      # @return [OpenAI::Helpers::StructuredOutput::SorbetAdapter]
+      def self.from_sorbet(model) = OpenAI::Helpers::StructuredOutput::SorbetAdapter.new(model)
+
+      # Reject unsupported Sorbet request shapes before generated resources dispatch requests.
+      #
+      # @api private
+      module SorbetRequestGuard
+        def create(...)
+          reject_sorbet_function_tools!(...)
+          super
+        end
+
+        def stream(params)
+          reject_sorbet_streaming_formats!(params)
+          super
+        end
+
+        def stream_raw(...)
+          reject_sorbet_streaming_formats!(...)
+          super
+        end
+
+        private def reject_sorbet_streaming_formats!(params = {})
+          formats = [params[:text], params[:response_format], *Array(params[:tools])]
+          if params.is_a?(Hash)
+            formats.concat([params["text"], params["response_format"], *Array(params["tools"])])
+          end
+
+          if formats.any? { sorbet_adapter?(_1) }
+            raise ArgumentError, "Sorbet structured-output models are not supported for streaming"
+          end
+        end
+
+        private def reject_sorbet_function_tools!(params = {})
+          tools = Array(params[:tools])
+          tools.concat(Array(params["tools"])) if params.is_a?(Hash)
+
+          if tools.any? { sorbet_adapter?(_1) }
+            raise ArgumentError, "Sorbet structured-output function tools are not supported"
+          end
+        end
+
+        private def sorbet_adapter?(format)
+          return true if format.is_a?(SorbetAdapter)
+          format = format.to_h if format.is_a?(OpenAI::Internal::Type::BaseModel)
+          return false unless format.is_a?(Hash)
+
+          keys = [
+            :format,
+            "format",
+            :format_,
+            "format_",
+            :json_schema,
+            "json_schema",
+            :schema,
+            "schema",
+            :parameters,
+            "parameters",
+            :function,
+            "function"
+          ]
+          format.values_at(*keys).any? do |nested|
+            nested = nested.to_h if nested.is_a?(OpenAI::Internal::Type::BaseModel)
+            nested.is_a?(SorbetAdapter) ||
+              (nested.is_a?(Hash) && nested.values_at(:schema, "schema", :parameters, "parameters").any?(SorbetAdapter))
+          end
+        end
+      end
+
+      private_constant :SorbetRequestGuard
+      OpenAI::Resources::Responses.prepend(SorbetRequestGuard)
+      OpenAI::Resources::Chat::Completions.prepend(SorbetRequestGuard)
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "unknown_stream_event"
+
+module OpenAI
+  module Helpers
+    module Streaming
+      # @api private
+      class ResponseEventDecoder
+        def initialize(model:)
+          @model = model
+          return unless response_stream_model?
+
+          @known_types = model.variants.to_h do |variant|
+            type = variant.known_fields.fetch(:type).fetch(:const)
+            [type.to_s, true]
+          end
+        end
+
+        def decode(data)
+          if unknown_response_event?(data)
+            UnknownStreamEvent.new(data: data)
+          else
+            OpenAI::Internal::Type::Converter.coerce(@model, data)
+          end
+        end
+
+        private
+
+        def response_stream_model?
+          @model.equal?(OpenAI::Models::Responses::ResponseStreamEvent) ||
+            @model.equal?(OpenAI::Models::Beta::BetaResponseStreamEvent)
+        end
+
+        def unknown_response_event?(data)
+          return false unless @known_types && data.is_a?(Hash)
+
+          type = data[:type]
+          (type.is_a?(String) || type.is_a?(Symbol)) && !@known_types.key?(type.to_s)
+        end
+      end
+    end
+  end
+end

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

@@ -63,13 +63,18 @@ module OpenAI
             @raw_stream.each do |raw_event|
               events_to_yield = @state.handle_event(raw_event)
               events_to_yield.each do |event|
-                if @starting_after.nil? || event.sequence_number > @starting_after
-                  y << event
-                end
+                y << event if after_starting_event?(event)
               end
             end
           end
         end
+
+        def after_starting_event?(event)
+          return true if @starting_after.nil?
+          return true if event.is_a?(UnknownStreamEvent) && event.sequence_number.nil?
+
+          event.sequence_number > @starting_after
+        end
       end
 
       class ResponseStreamState
@@ -82,6 +87,8 @@ module OpenAI
         end
 
         def handle_event(event)
+          return [event] if event.is_a?(UnknownStreamEvent)
+
           @current_snapshot = accumulate_event(
             event: event,
             current_snapshot: @current_snapshot

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Helpers
+    module Streaming
+      # A Responses event whose discriminator is newer than this SDK version.
+      class UnknownStreamEvent
+        # @return [Symbol]
+        attr_reader :type
+
+        # @return [Integer, nil]
+        attr_reader :sequence_number
+
+        # @return [Hash{Symbol=>Object}]
+        attr_reader :data
+
+        # @api private
+        def initialize(data:)
+          value = data.fetch(:type)
+          unless value.is_a?(String) || value.is_a?(Symbol)
+            raise ArgumentError, "Responses stream event type must be a string or symbol"
+          end
+
+          @type = value.to_sym
+          sequence_number = data[:sequence_number]
+          @sequence_number = sequence_number if sequence_number.is_a?(Integer)
+          @data = freeze_json(data)
+          freeze
+        end
+
+        # @return [Hash{Symbol=>Object}]
+        def to_h = @data
+
+        private def freeze_json(value)
+          case value
+          when Hash
+            value.each do |key, item|
+              freeze_json(key)
+              freeze_json(item)
+            end
+
+          when Array
+            value.each { |item| freeze_json(item) }
+          end
+
+          value.freeze
+        end
+      end
+    end
+  end
+end