openai 0.106.0 → 0.108.0

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/responses_websocket/unknown_server_event.rb

@@ -4,6 +4,8 @@ module OpenAI
   module Responses
     # A valid JSON event whose discriminator is newer than this SDK version.
     class UnknownServerEvent
+      include OpenAI::WebSocket::Protocol
+
       # @return [Symbol]
       attr_reader :type
 
@@ -35,20 +37,6 @@ module OpenAI
 
       alias to_s inspect
 
-      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

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

@@ -171,7 +171,9 @@ module OpenAI
           @connection.read
         rescue StandardError => e
           error = @error_factory.call(url: @url, cause: e)
-          raise error, cause: error.cause
+          # The factory retains explicit diagnostics; do not render them as a
+          # native exception chain, which can include payloads or credentials.
+          raise error, cause: nil
         end
 
         def write(message)
@@ -179,14 +181,14 @@ module OpenAI
           @connection.flush
         rescue StandardError => e
           error = @error_factory.call(url: @url, cause: e)
-          raise error, cause: error.cause
+          raise error, cause: nil
         end
 
         def close(code: 1000, reason: "")
           @connection.close(code, reason)
         rescue StandardError => e
           error = @error_factory.call(url: @url, cause: e)
-          raise error, cause: error.cause
+          raise error, cause: nil
         end
 
         # @api private
@@ -197,7 +199,7 @@ module OpenAI
           @aborted = true
         rescue StandardError => e
           error = @error_factory.call(url: @url, cause: e)
-          raise error, cause: error.cause
+          raise error, cause: nil
         end
 
         # @api private
@@ -302,7 +304,7 @@ module OpenAI
         raise if e.equal?(block_error)
 
         error = @error_factory.call(url: url, cause: e, http_status: handshake_status(e))
-        raise error, cause: error.cause
+        raise error, cause: nil
       end
 
       private def negotiation_options(_endpoint_options) = {}
@@ -373,7 +375,7 @@ module OpenAI
           "#{@product_name} WebSockets require the `async-websocket` gem. " \
             "Add `gem \"async-websocket\"` to your Gemfile."
         error = @error_factory.call(url: url, message: message, cause: e)
-        raise error, cause: error.cause
+        raise error, cause: nil
       end
 
       private def authority(url, include_default_port: false)

data/lib/openai/helpers/websocket/client_request.rb

@@ -140,7 +140,7 @@ module OpenAI
         [request, deadline]
       rescue Timeout::Error => e
         error = timeout_error.call(error_url, e)
-        raise error, cause: error.cause
+        raise error, cause: nil
       end
 
       private def with_shared_websocket_base_url(request, path:, base_url:)

data/lib/openai/helpers/websocket/connection.rb

@@ -28,20 +28,13 @@ module OpenAI
       end
 
       private def write_text(text)
-        complete = false
         super
-        complete = true
-        nil
       rescue StandardError
         raise transport_error, cause: nil
-      ensure
-        # Also retire a possibly buffered write when cancellation bypasses
-        # StandardError, before another sender or normal cleanup can flush it.
-        @poisoned = true unless complete
       end
 
       private def read_raw_message
-        raise connection_error(failed_read_message) if @poisoned
+        raise connection_error(failed_read_message), cause: nil if @poisoned
         return nil if @closed
         text = super
         @closed = text.nil?
@@ -73,6 +66,7 @@ module OpenAI
       def initialize(socket:, url:)
         @socket = socket
         @url = url
+        @poisoned = false
       end
 
       # Yield server events until the remote peer closes the connection.
@@ -100,6 +94,8 @@ module OpenAI
       def receive_raw = read_raw_message
 
       private def read_raw_message
+        raise connection_error("Cannot read from a failed WebSocket."), cause: nil if @poisoned
+
         message = @socket.read
         message&.to_str
       end
@@ -108,7 +104,7 @@ module OpenAI
       #
       # @api private
       def send_raw(data)
-        raise connection_error(closed_send_message) if closed?
+        raise connection_error(closed_send_message), cause: nil if closed?
 
         text = data.dup
         text.force_encoding(Encoding::UTF_8) if text.encoding == Encoding::BINARY
@@ -120,6 +116,7 @@ module OpenAI
 
       # Close the connection.
       def close(code: 1000, reason: "")
+        return abort if @poisoned
         return if socket_closed?
 
         @socket.close(code: code, reason: reason)
@@ -137,7 +134,7 @@ module OpenAI
       end
 
       # @return [Boolean]
-      def closed? = socket_closed?
+      def closed? = @poisoned || socket_closed?
 
       private def parse_event(_data)
         raise NotImplementedError
@@ -154,8 +151,22 @@ module OpenAI
       private def socket_closed? = @socket.closed?
 
       private def write_text(text)
+        complete = false
         @socket.write(text)
+        complete = true
         nil
+      ensure
+        unless complete
+          # Retire the physical socket immediately: an already-running reader
+          # can otherwise flush buffered application bytes while replying to close.
+          @poisoned = true
+          begin
+            @socket.abort
+          rescue StandardError
+            # Preserve the original write failure or cancellation.
+            nil
+          end
+        end
       end
     end
   end

data/lib/openai/helpers/websocket/connection_manager.rb

@@ -73,7 +73,8 @@ module OpenAI
 
         rescue StandardError => error
           raise if @transport_error_factory.nil?
-          raise block_error, cause: block_error.cause if block_error
+          # Preserve the native chain, not an SDK accessor's explicit diagnostics.
+          raise block_error, cause: Exception.instance_method(:cause).bind_call(block_error) if block_error
           raise @transport_error_factory.call(url: request.fetch(:url), error: error), cause: nil
         end
       end

data/lib/openai/helpers/websocket/protocol.rb

@@ -6,6 +6,166 @@ module OpenAI
     #
     # @api private
     module Protocol
+      # JSON schemas and extension data do not have a transport-specific depth limit.
+      private def parse_json(data) = JSON.parse(data, symbolize_names: true, max_nesting: false)
+
+      private def generate_json(value) = JSON.generate(value, max_nesting: false)
+
+      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
+
+      # Unknown wire keys must not replace a selected model's renamed Ruby fields.
+      private def validate_wire_field_names!(event, payload)
+        pending = [[event, payload]]
+        until pending.empty?
+          value, raw = pending.pop
+          case value
+          when OpenAI::Internal::Type::BaseModel
+            value.class.fields.each do |name, field|
+              raise ArgumentError if name != field.fetch(:api_name) && raw.is_a?(Hash) && raw.key?(name)
+            end
+
+            value.to_h.each do |name, child|
+              field = value.class.fields[name]
+              key = field ? field.fetch(:api_name) : name
+              pending << [child, raw.is_a?(Hash) ? raw[key] : nil]
+            end
+
+          when Hash
+            value.each { |name, child| pending << [child, raw.is_a?(Hash) ? raw[name] : nil] }
+          when Array
+            value.each_with_index { |child, index| pending << [child, raw.is_a?(Array) ? raw[index] : nil] }
+          end
+        end
+
+        event
+      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?
+        ancestors = {}.compare_by_identity
+        pending = [[event, false]]
+        until pending.empty?
+          value, exiting = pending.pop
+          if exiting
+            ancestors.delete(value)
+            next
+          end
+
+          children = case value
+          when OpenAI::Internal::Type::BaseModel
+            data = value.to_h
+            validate_model_fields!(value)
+            value.class.fields.each do |name, field|
+              const = field.fetch(:const)
+              if field.fetch(:required) &&
+                  field.fetch(:mode) != (outbound ? :coerce : :dump) &&
+                  (!outbound || const == OpenAI::Internal::OMIT) &&
+                  !data.key?(name)
+                raise ArgumentError
+              end
+            end
+
+            data.values
+          when Hash
+            value.values
+          when Array
+            value
+          else
+            next
+          end
+
+          raise ArgumentError if ancestors.key?(value)
+          ancestors[value] = true
+          pending << [value, true]
+          children.each { |child| pending << [child, false] }
+        end
+
+        event
+      end
+
+      private def validate_event_tree!(event, json_only: false, strict_keys: true)
+        ancestors = {}.compare_by_identity
+        pending = [[event, false]]
+        until pending.empty?
+          value, exiting = pending.pop
+          if exiting
+            ancestors.delete(value)
+            next
+          end
+
+          children = case value
+          when OpenAI::Internal::Type::BaseModel
+            raise ArgumentError if json_only
+            data = value.to_h
+            validate_model_fields!(value)
+            [data]
+          when Hash
+            if strict_keys
+              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
+            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 validate_model_fields!(model)
+        names = {}
+        model.to_h.each do |name, actual|
+          key = name.is_a?(String) ? name.to_sym : name
+          field = model.class.known_fields[key]
+          serialized_name = field ? field.fetch(:api_name).to_s : key.to_s
+          raise ArgumentError if names.key?(serialized_name)
+          names[serialized_name] = true
+          next unless field
+          const = field.fetch(:const)
+          next if const == OpenAI::Internal::OMIT
+          if const.is_a?(Symbol)
+            raise ArgumentError unless (actual.is_a?(String) || actual.is_a?(Symbol)) && actual.to_s == const.to_s
+          elsif actual != const
+            raise ArgumentError
+          end
+        end
+      end
+
       private def discriminator_values(union)
         union.variants.to_h do |variant|
           value = variant.fields.fetch(:type).fetch(:const)

data/lib/openai/helpers/websocket/typed_connection.rb

@@ -2,7 +2,7 @@
 
 module OpenAI
   module WebSocket
-    # Generic event codec for APIs with generated bindings and no specialized helper.
+    # Shared event codec for generated bindings and specialized product facades.
     #
     # @api private
     class TypedConnection < Connection
@@ -30,36 +30,36 @@ module OpenAI
       end
 
       private def encode_client_event(event)
-        event_type(event, message: "Invalid WebSocket client event.") if event.is_a?(Hash)
+        validate_event_tree!(event)
+        event_type(event, message: client_event_error_message) if event.is_a?(Hash)
         payload = @client_event ? OpenAI::Internal::Type::Converter.dump(@client_event, event) : event
-        type = event_type(payload, message: "Invalid WebSocket client event.")
+        type = event_type(payload, message: client_event_error_message)
         if @client_event && !@client_event_types.any? { _1.nil? || _1 === type.to_sym || _1 === type.to_s }
-          raise ArgumentError, "Invalid WebSocket client event."
+          raise ArgumentError, client_event_error_message
         end
 
-        payload = coerce(@client_event, payload) if @client_event
+        payload = coerce_client_event(payload) if @client_event
         payload = OpenAI::Internal::Type::Converter.dump(@client_event, payload) if @client_event
-        JSON.generate(payload, max_nesting: false)
+        validate_event_tree!(payload, json_only: true)
+        generate_json(payload)
       rescue StandardError, SystemStackError
-        raise ArgumentError, "Invalid WebSocket client event.", cause: nil
+        raise ArgumentError, client_event_error_message, cause: nil
       end
 
       def parse_event(data)
-        parsed = JSON.parse(data, symbolize_names: true, max_nesting: false)
+        parsed = parse_json(data)
         type = event_type(parsed, message: "WebSocket server event must be an object with a string type")
         _, model = @server_event_types.find { |event_type,| event_type === type.to_sym }
-        return parsed unless model
+        return unknown_server_event(parsed) unless model
 
-        # Unknown wire fields must not overwrite a known field's Ruby name.
-        model.fields.each do |name, field|
-          raise ArgumentError if name != field.fetch(:api_name) && parsed.key?(name)
-        end
-
-        coerce(@server_event, parsed)
+        event = coerce(@server_event, parsed)
+        validate_wire_field_names!(event, parsed)
       rescue StandardError, SystemStackError
-        raise OpenAI::Errors::WebSocketProtocolError, "Invalid WebSocket server event.", cause: nil
+        raise protocol_error, cause: nil
       end
 
+      private def coerce_client_event(payload) = coerce(@client_event, payload)
+
       private def coerce(type, value)
         state = OpenAI::Internal::Type::Converter.new_coerce_state
         result = OpenAI::Internal::Type::Converter.coerce(type, value, state: state)
@@ -70,6 +70,12 @@ module OpenAI
         result
       end
 
+      private def client_event_error_message = "Invalid WebSocket client event."
+
+      private def unknown_server_event(payload) = payload
+
+      private def protocol_error = OpenAI::Errors::WebSocketProtocolError.new("Invalid WebSocket server event.")
+
       private def connection_error(message) = BindingConnectionError.new(url: @url, message: message)
 
       private def transport_error = connection_error("WebSocket transport failed.")

data/lib/openai/helpers/websocket/typed_resource.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module OpenAI
+  module WebSocket
+    # Supplies the generic signature contract for generated event bindings.
+    # Connection lifecycle and event handling are implemented by Resource.
+    #
+    # @api private
+    module TypedResource
+      include Resource
+    end
+  end
+end

data/lib/openai/internal/transport/base_client.rb

@@ -1012,7 +1012,7 @@ module OpenAI
                 T::Class[OpenAI::Internal::Type::BaseStream[T.anything, OpenAI::Internal::Type::BaseModel]]
               ),
               model: T.nilable(OpenAI::Internal::Type::Converter::Input),
-              security: T.nilable({bearer_auth?: T::Boolean, admin_api_key_auth?: T::Boolean}),
+              security: T.nilable(T::Hash[Symbol, T::Boolean]),
               options: T.nilable(OpenAI::RequestOptions::OrHash)
             }
           end

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

@@ -235,9 +235,16 @@ module OpenAI
                 #   @return [Integer, nil]
                 optional :input_cache_write_12h_tokens, Integer
 
-                # @!attribute input_cache_write_tokens
+                # @!attribute input_cache_write_30m_tokens
                 #   The aggregated number of input tokens written to the cache with a 30-minute
-                #   retention period.
+                #   retention period. May be absent or null for older responses.
+                #
+                #   @return [Integer, nil]
+                optional :input_cache_write_30m_tokens, Integer, nil?: true
+
+                # @!attribute input_cache_write_tokens
+                #   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
@@ -333,7 +340,7 @@ module OpenAI
                 #   @return [String, nil]
                 optional :user_id, String, nil?: true
 
-                # @!method initialize(input_tokens:, num_model_requests:, output_tokens:, api_key_id: nil, api_source: nil, batch: nil, input_audio_tokens: nil, input_cache_write_12h_tokens: nil, input_cache_write_tokens: nil, input_cached_audio_tokens: nil, input_cached_image_tokens: nil, input_cached_text_tokens: nil, input_cached_tokens: nil, input_image_tokens: nil, input_text_tokens: nil, input_uncached_tokens: nil, model: nil, output_audio_tokens: nil, output_image_tokens: nil, output_text_tokens: nil, project_id: nil, service_tier: nil, user_id: nil, object: :"organization.usage.completions.result")
+                # @!method initialize(input_tokens:, num_model_requests:, output_tokens:, api_key_id: nil, api_source: nil, batch: nil, input_audio_tokens: nil, input_cache_write_12h_tokens: nil, input_cache_write_30m_tokens: nil, input_cache_write_tokens: nil, input_cached_audio_tokens: nil, input_cached_image_tokens: nil, input_cached_text_tokens: nil, input_cached_tokens: nil, input_image_tokens: nil, input_text_tokens: nil, input_uncached_tokens: nil, model: nil, output_audio_tokens: nil, output_image_tokens: nil, output_text_tokens: nil, project_id: nil, service_tier: nil, user_id: nil, object: :"organization.usage.completions.result")
                 #   The aggregated completions usage details of the specific time bucket.
                 #
                 #   @param input_tokens [Integer]
@@ -370,9 +377,13 @@ module OpenAI
                 #     The aggregated number of input tokens written to the cache with a 12-hour
                 #     retention period.
                 #
-                #   @param input_cache_write_tokens [Integer]
+                #   @param input_cache_write_30m_tokens [Integer, nil]
                 #     The aggregated number of input tokens written to the cache with a 30-minute
-                #     retention period.
+                #     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 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

@@ -237,9 +237,16 @@ module OpenAI
                 #   @return [Integer, nil]
                 optional :input_cache_write_12h_tokens, Integer
 
-                # @!attribute input_cache_write_tokens
+                # @!attribute input_cache_write_30m_tokens
                 #   The aggregated number of input tokens written to the cache with a 30-minute
-                #   retention period.
+                #   retention period. May be absent or null for older responses.
+                #
+                #   @return [Integer, nil]
+                optional :input_cache_write_30m_tokens, Integer, nil?: true
+
+                # @!attribute input_cache_write_tokens
+                #   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
@@ -335,7 +342,7 @@ module OpenAI
                 #   @return [String, nil]
                 optional :user_id, String, nil?: true
 
-                # @!method initialize(input_tokens:, num_model_requests:, output_tokens:, api_key_id: nil, api_source: nil, batch: nil, input_audio_tokens: nil, input_cache_write_12h_tokens: nil, input_cache_write_tokens: nil, input_cached_audio_tokens: nil, input_cached_image_tokens: nil, input_cached_text_tokens: nil, input_cached_tokens: nil, input_image_tokens: nil, input_text_tokens: nil, input_uncached_tokens: nil, model: nil, output_audio_tokens: nil, output_image_tokens: nil, output_text_tokens: nil, project_id: nil, service_tier: nil, user_id: nil, object: :"organization.usage.completions.result")
+                # @!method initialize(input_tokens:, num_model_requests:, output_tokens:, api_key_id: nil, api_source: nil, batch: nil, input_audio_tokens: nil, input_cache_write_12h_tokens: nil, input_cache_write_30m_tokens: nil, input_cache_write_tokens: nil, input_cached_audio_tokens: nil, input_cached_image_tokens: nil, input_cached_text_tokens: nil, input_cached_tokens: nil, input_image_tokens: nil, input_text_tokens: nil, input_uncached_tokens: nil, model: nil, output_audio_tokens: nil, output_image_tokens: nil, output_text_tokens: nil, project_id: nil, service_tier: nil, user_id: nil, object: :"organization.usage.completions.result")
                 #   The aggregated completions usage details of the specific time bucket.
                 #
                 #   @param input_tokens [Integer]
@@ -372,9 +379,13 @@ module OpenAI
                 #     The aggregated number of input tokens written to the cache with a 12-hour
                 #     retention period.
                 #
-                #   @param input_cache_write_tokens [Integer]
+                #   @param input_cache_write_30m_tokens [Integer, nil]
                 #     The aggregated number of input tokens written to the cache with a 30-minute
-                #     retention period.
+                #     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 across 30-minute and
+                #     12-hour retention periods.
                 #
                 #   @param input_cached_audio_tokens [Integer]
                 #     The aggregated number of cached audio input tokens used.