openai 0.97.0 → 0.98.0

data/lib/openai/helpers/beta/agents/model_adapter.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Helpers
+    module Beta
+      module Agents
+        # Shared native model checks; JSON and wire-schema policies stay with each caller.
+        # @api private
+        module ModelAdapter
+          def self.validate!(model, parameter:)
+            unless model.is_a?(Class) && model < OpenAI::BaseModel
+              raise ArgumentError, "#{parameter} must be an OpenAI::BaseModel subclass"
+            end
+          end
+
+          def self.coerce(model, value, memoize: false)
+            state = OpenAI::Internal::Type::Converter.new_coerce_state(memoize: memoize)
+            parsed = OpenAI::Internal::Type::Converter.coerce(model, value, state: state)
+            parsed if parsed.is_a?(model) && state[:exactness][:no].zero?
+          end
+        end
+
+        private_constant :ModelAdapter
+      end
+    end
+  end
+end

data/lib/openai/helpers/beta/agents/result.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Helpers
+    module Beta
+      module Agents
+        # The final output of one completed root turn (beta).
+        # Messages contain final assistant answers, not the session transcript.
+        class TurnResult
+          attr_reader :turn, :messages
+
+          # @api private
+          def initialize(turn:, messages:)
+            @turn = turn
+            @messages = messages.freeze
+          end
+
+          def session_id = turn.session_id
+          def turn_id = turn.id
+
+          # Joins text without adding separators or making requests.
+          def output_text = messages.map(&:output_text).join
+
+          # A raw result has no parser attached.
+          def output_parsed = nil
+
+          # Parse this completed answer without changing the hosted session.
+          def parse(output_type:)
+            OutputParser.new(output_type).parse(self)
+          end
+        end
+
+        # Collection failed, or the observed turn did not complete successfully.
+        # A transport failure describes observation, not failure of hosted work.
+        class ResultError < OpenAI::Errors::Error
+          attr_reader :reason, :session_id, :turn, :messages, :required_actions
+
+          # @api private
+          def initialize(reason:, session_id:, turn:, messages:, required_actions: [])
+            @reason = reason
+            @session_id = session_id
+            @turn = turn
+            @messages = messages.freeze
+            @required_actions = required_actions.freeze
+            super("Unable to collect the agent turn result: #{reason}")
+          end
+
+          def turn_id = turn&.id
+        end
+
+        # @api private
+        class ResultCollector
+          def initialize(session_id: nil, handler_names: [])
+            @session_id = session_id
+            @handler_names = handler_names
+            @messages = {}
+            @required_actions = []
+          end
+
+          def enable
+            return if @enabled
+            if @started
+              raise ArgumentError, "Call with_result_collection before consuming events to collect a final result"
+            end
+
+            @enabled = true
+          end
+
+          def observe(event)
+            @started = true
+            return unless @enabled
+            return if @finished || !event.is_a?(OpenAI::Internal::Type::BaseModel)
+
+            case event.type
+            when :"agent.session.created"
+              @session_id ||= event.session.id.dup
+            when :"agent.session.turn.created"
+              if @turn.nil? && event.turn.subagent_id.nil? && (@session_id.nil? || event.session_id == @session_id)
+                @turn = copy(event.turn)
+                @session_id = @turn.session_id
+              end
+
+            when :"agent.session.turn.completed", :"agent.session.turn.failed", :"agent.session.turn.cancelled"
+              if @turn && event.turn_id == @turn.id
+                @turn = copy(event.turn)
+                @terminal = true
+                @required_actions = []
+              end
+
+            when :"agent.session.turn.item.done"
+              item = event.item
+              if @turn &&
+                  item.is_a?(OpenAI::Models::Beta::AgentSessionAssistantMessage) &&
+                  item.turn_id == @turn.id &&
+                  item.role == :assistant &&
+                  item.status == :completed &&
+                  item.phase != :commentary
+                @messages[item.id] = [event.output_index, copy(item, OpenAI::Models::Beta::AgentSessionMessage)]
+              end
+
+            when :"agent.session.requires_action"
+              @required_actions = event.session.required_actions.filter_map do |action|
+                if action.is_a?(OpenAI::Models::Beta::AgentSession::RequiredAction::FunctionCall) &&
+                    @handler_names.include?(action.name)
+                  next
+                end
+
+                copy(action)
+              end
+
+            when :"agent.session.in_progress"
+              @required_actions = [] if event.session.id == @session_id
+            when :"agent.session.idle"
+              @finished = true if @terminal && event.session.id == @session_id
+            when :"agent.session.failed"
+              @session_id ||= event.session.id.dup
+              @failure = :failed
+              @finished = true
+            end
+          end
+
+          def stopped?
+            @finished || !@required_actions.empty? || (@terminal && @turn.status != :completed)
+          end
+
+          def observe_error(error)
+            @cause ||= error if @enabled && !@finished
+          end
+
+          def result
+            return @result if @result
+            raise @result_error if @result_error
+            raise error(:observation_error), cause: @cause if @cause
+            raise error(@failure) if @failure
+            raise error(@turn.status) if @terminal && @turn.status != :completed
+            raise error(:requires_action) unless @required_actions.empty?
+            raise error(:incomplete) unless @finished && @turn&.status == :completed
+
+            @result = TurnResult.new(turn: @turn, messages: take_messages)
+          end
+
+          private
+
+          def take_messages
+            messages = @messages.values.sort_by(&:first).map(&:last)
+            @messages.clear
+            messages
+          end
+
+          def error(reason)
+            @result_error = ResultError.new(
+              reason: reason,
+              session_id: @session_id,
+              turn: @turn,
+              messages: take_messages,
+              required_actions: @required_actions
+            )
+          end
+
+          def copy(value, model = value.class)
+            raw = JSON.parse(JSON.generate(value), symbolize_names: true)
+            OpenAI::Internal::Type::Converter.coerce(model, raw)
+          end
+        end
+      end
+    end
+  end
+end
+
+require_relative "typed_output"

data/lib/openai/helpers/beta/agents/typed_output.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require_relative "model_adapter"
+
+module OpenAI
+  module Helpers
+    module Beta
+      module Agents
+        # A completed turn with output hydrated into the requested Ruby model (beta).
+        class ParsedTurnResult < TurnResult
+          attr_reader :raw_result, :output_parsed
+
+          # @api private
+          def initialize(raw_result:, output_parsed:)
+            @raw_result = raw_result
+            @output_parsed = output_parsed
+            super(turn: raw_result.turn, messages: raw_result.messages)
+          end
+        end
+
+        # Hosted work completed, but its answer did not match the requested model.
+        class OutputParseError < OpenAI::Errors::Error
+          attr_reader :raw_result
+
+          # @api private
+          def initialize(raw_result:)
+            @raw_result = raw_result
+            super("The completed agent output does not match output_type")
+          end
+        end
+
+        # @api private
+        class OutputParser
+          def initialize(model)
+            ModelAdapter.validate!(model, parameter: "output_type")
+
+            @model = model
+          end
+
+          def prepare_request(params)
+            agent = params.fetch(:agent, nil).to_h.transform_keys { _1.is_a?(String) ? _1.to_sym : _1 }
+            text = agent.fetch(:text, nil).to_h.transform_keys { _1.is_a?(String) ? _1.to_sym : _1 }
+            if text.key?(:format) || text.key?(:format_)
+              raise ArgumentError, "output_type cannot be combined with agent.text.format"
+            end
+
+            @schema = JSON.parse(JSON.generate(@model.to_json_schema, max_nesting: false), max_nesting: false)
+            normalize_references
+            params[:agent] = agent.merge(text: text.merge(format: {type: :json_schema, schema: @schema}))
+          end
+
+          def parse(result)
+            return @result if @result && @result.raw_result.equal?(result)
+            raise @error if @error && @error.raw_result.equal?(result)
+
+            first = nil
+            result.messages.each do |message|
+              message.content.each do |part|
+                next unless (part[:type] || (part["type"] if part.is_a?(Hash))).to_s == "output_text"
+                text = part[:text] || (part["text"] if part.is_a?(Hash))
+                value = JSON.parse(text, symbolize_names: true, max_nesting: false)
+                parsed = ModelAdapter.coerce(@model, value, memoize: true)
+                raise TypeError, "Output cannot be parsed into output_type" unless parsed
+                first ||= parsed
+              end
+            end
+
+            raise TypeError, "Output does not contain structured text" unless first
+
+            @result = ParsedTurnResult.new(raw_result: result, output_parsed: first)
+          rescue StandardError, SystemStackError => error
+            raise if error.equal?(@error)
+            @error = OutputParseError.new(raw_result: result)
+            raise @error, cause: nil
+          end
+
+          private
+
+          def resolve(ref)
+            return unless ref.is_a?(String) && ref.start_with?("#/")
+
+            URI::RFC2396_PARSER
+              .unescape(ref.delete_prefix("#/"))
+              .split("/", -1)
+              .reduce(@schema) { |node, token| node[token.gsub("~1", "/").gsub("~0", "~")] if node.is_a?(Hash) }
+          end
+
+          def normalize_references
+            return unless @schema.is_a?(Hash) && @schema["$defs"].is_a?(Hash)
+            return if @schema.key?("$ref") && !(@schema.keys - %w[$defs $ref]).empty?
+            definitions = @schema.fetch("$defs")
+            return if definitions.empty? || !definitions.values.all? { _1.is_a?(Hash) }
+
+            names = {}.compare_by_identity
+            definitions.each_value.with_index { |definition, index| names[definition] = "model_#{index}" }
+            nodes = schema_nodes
+            return unless references_covered?(nodes)
+            references = nodes.select { _1.key?("$ref") }
+            return if references.empty?
+            targets = references.map { resolve(_1["$ref"]) }
+            # Native Ruby pointers encode definition names; Agents looks up raw suffixes.
+            # Unfamiliar references keep their schema and definition names intact.
+            return unless targets.all? { names.key?(_1) }
+            root = resolve(@schema["$ref"])
+            expand_root = root.is_a?(Hash) && !root.key?("$defs") && (@schema.keys - %w[$defs $ref]).empty?
+
+            references.zip(targets).each do |node, target|
+              node["$ref"] = "#/$defs/#{names.fetch(target)}"
+              if (node.key?("description") || node.key?("title")) && !node.key?("anyOf")
+                node["anyOf"] = [{"$ref" => node.delete("$ref")}]
+              end
+            end
+
+            @schema["$defs"] = definitions.to_h { |_name, definition| [names.fetch(definition), definition] }
+            @schema = @schema.except("$ref").merge(root) if expand_root
+          end
+
+          def references_covered?(nodes)
+            known = nodes.each_with_object({}.compare_by_identity) { |node, seen| seen[node] = true }
+            pending = [@schema]
+            until pending.empty?
+              value = pending.pop
+              case value
+              when Hash
+                if known[value]
+                  unless (value.keys &
+                      %w[$id id $anchor $dynamicAnchor $dynamicRef $recursiveAnchor $recursiveRef discriminator])
+                      .empty?
+                    return false
+                  end
+
+                  pending.concat(
+                    value.except("$ref", "title", "description", "default", "const", "enum", "examples").values
+                  )
+                else
+                  return false if %w[$ref $dynamicRef $recursiveRef].any? { value[_1].is_a?(String) }
+                  pending.concat(value.values)
+                end
+
+              when Array
+                pending.concat(value)
+              when String
+                return false if value.start_with?("#/")
+              end
+            end
+
+            true
+          end
+
+          def schema_nodes
+            nodes = []
+            pending = [@schema]
+            until pending.empty?
+              node = pending.pop
+              next unless node.is_a?(Hash)
+              nodes << node
+              # Visit schema positions only: defaults, examples and enum values are data.
+              %w[properties patternProperties $defs definitions dependentSchemas dependencies].each do |key|
+                pending.concat(node[key].values.grep(Hash)) if node[key].is_a?(Hash)
+              end
+
+              %w[anyOf allOf oneOf prefixItems].each do |key|
+                pending.concat(node[key]) if node[key].is_a?(Array)
+              end
+
+              %w[
+                items
+                additionalProperties
+                additionalItems
+                contains
+                not
+                if
+                then
+                else
+                propertyNames
+                unevaluatedProperties
+                unevaluatedItems
+              ]
+                .each do |key|
+                  pending.concat(node[key].is_a?(Array) ? node[key] : [node[key]]) if node.key?(key)
+                end
+            end
+
+            nodes
+          end
+
+        end
+      end
+    end
+  end
+end

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

@@ -99,10 +99,16 @@ module OpenAI
       end
 
       private def write_text(text)
+        complete = false
         super
+        complete = true
+        nil
       rescue StandardError
-        @poisoned = true
         raise OpenAI::Errors::LiveConnectionError.new(url: @url), 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

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

@@ -7,7 +7,7 @@ module OpenAI
     # exceptions local to Realtime instead of weakening SDK-wide union behavior.
     module ConversationItem
       class << self
-        private def resolve_variant(value)
+        private def resolve_variant(value, state: nil)
           return super unless value.is_a?(Hash)
 
           type = value.fetch(:type) { value.fetch("type", OpenAI::Internal::OMIT) }

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

@@ -177,10 +177,16 @@ module OpenAI
       end
 
       private def write_text(text)
+        complete = false
         super
+        complete = true
+        nil
       rescue StandardError
-        @poisoned = true
         raise OpenAI::Errors::ResponsesSendError.new(url: @url), cause: nil
+      ensure
+        # Cancellation can bypass StandardError. Poison before another lane
+        # can send, so normal cleanup cannot flush an uncertain write.
+        @poisoned = true unless complete
       end
 
       private def with_read_lease

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

@@ -495,8 +495,12 @@ module OpenAI
         raise
       rescue OpenAI::Errors::ResponsesSendError => error
         @error = error
-        stop_reader
         raise
+      ensure
+        if @connection.poisoned?
+          @error ||= OpenAI::Errors::ResponsesSendError.new(url: @connection.url)
+          stop_reader
+        end
       end
 
       # @api private

data/lib/openai/helpers/responses_websocket/transports/async_websocket.rb

@@ -117,7 +117,10 @@ module OpenAI
             decoded = +"".b
             begin
               inflater.inflate(buffer + ::Protocol::WebSocket::Extension::Compression::Inflate::TRAILER) do |chunk|
-                if inflater.total_out - start_out > @responses_decoded_limit
+                if inflater.total_out -
+                    start_out > @responses_decoded_limit ||
+                    decoded.bytesize +
+                    chunk.bytesize > @responses_decoded_limit
                   raise ::Protocol::WebSocket::ProtocolError, "Responses WebSocket message exceeds configured limit."
                 end
 
@@ -129,7 +132,14 @@ module OpenAI
                 raise ::Protocol::WebSocket::ProtocolError, "Responses WebSocket message exceeds configured limit."
               end
 
-              decoded << inflater.flush_next_out
+              # Finished streams can put unused input in this buffer without
+              # increasing total_out. Count every byte before collecting it.
+              tail = inflater.flush_next_out
+              if decoded.bytesize + tail.bytesize > @responses_decoded_limit
+                raise ::Protocol::WebSocket::ProtocolError, "Responses WebSocket message exceeds configured limit."
+              end
+
+              decoded << tail
             rescue ::Protocol::WebSocket::ProtocolError
               @responses_bounded_framer.abort
               inflater.close

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

@@ -823,6 +823,24 @@ module OpenAI
           end
         end
 
+        # @api private
+        # Consume binary response chunks without buffering a complete body.
+        def request_streaming_body(req, on_response = nil)
+          if req[:options].to_h[:include_raw_body]
+            raise ArgumentError, "include_raw_body is not supported for streaming downloads"
+          end
+
+          _url, response, log_context = perform_request(req)
+          finish_request(log_context, response) do
+            on_response&.call
+            response.body.each { |chunk| yield chunk }
+            nil
+          end
+
+        ensure
+          OpenAI::Internal::Util.close_fused!(response.body) if response
+        end
+
         # @api private
         #
         # @param req [Hash{Symbol=>Object}]

data/lib/openai/internal/type/array_of.rb

@@ -94,7 +94,7 @@ module OpenAI
             return value
           end
 
-          target = item_type
+          target = OpenAI::Internal::Type::Converter.resolve_type(@item_type_fn, state: state)
           exactness[:yes] += 1
           previous_error = state.fetch(:error)
           last_error = nil

data/lib/openai/internal/type/base_model.rb

@@ -28,9 +28,12 @@ module OpenAI
           # @api private
           #
           # @return [Hash{Symbol=>Hash{Symbol=>Object}}]
-          def fields
+          def fields(state: nil)
             known_fields.transform_values do |field|
-              {**field.except(:type_fn), type: field.fetch(:type_fn).call}
+              {
+                **field.except(:type_fn),
+                type: OpenAI::Internal::Type::Converter.resolve_type(field.fetch(:type_fn), state: state)
+              }
             end
           end
 
@@ -297,7 +300,7 @@ module OpenAI
             data = instance.to_h
             viability = instance.instance_variable_get(:@coerced)
 
-            fields.each do |name, field|
+            fields(state: state).each do |name, field|
               mode, required, target = field.fetch_values(:mode, :required, :type)
               api_name, nilable, const = field.fetch_values(:api_name, :nilable, :const)
               src_name = state.fetch(:translate_names) ? api_name : name

data/lib/openai/internal/type/converter.rb

@@ -135,17 +135,26 @@ module OpenAI
           # @param request_only [Boolean] Exclude fields omitted by the request serializer.
           #
           # @return [Hash{Symbol=>Object}]
-          def new_coerce_state(translate_names: true, request_only: false)
+          def new_coerce_state(translate_names: true, request_only: false, memoize: false)
             {
               translate_names: translate_names,
               request_only: request_only,
               strictness: true,
               exactness: {yes: 0, no: 0, maybe: 0},
               error: nil,
-              branched: 0
+              branched: 0,
+              memo: memoize ? {}.compare_by_identity : nil
             }
           end
 
+          # @api private
+          # Resolve lazy schema types once within an opted-in parse.
+          def resolve_type(type_fn, state: nil)
+            return type_fn.call unless state && state[:memo]
+            cache = state[:memo][:resolved_types] ||= {}.compare_by_identity
+            cache.fetch(type_fn) { cache[type_fn] = type_fn.call }
+          end
+
           # @api private
           #
           # Based on `target`, transform `value` into `target`, to the extent possible:
@@ -191,6 +200,12 @@ module OpenAI
           #
           # @return [Object]
           def coerce(target, value, state: OpenAI::Internal::Type::Converter.new_coerce_state)
+            if state[:memo] &&
+                target.is_a?(OpenAI::Internal::Type::Converter) &&
+                (value.is_a?(Hash) || value.is_a?(Array))
+              return coerce_cached(target, value, state: state)
+            end
+
             exactness = state.fetch(:exactness)
 
             case target
@@ -248,6 +263,12 @@ module OpenAI
                   state[:error] = TypeError.new("#{value.class} can't be coerced into #{String}")
                 end
 
+              in -> { _1 <= Symbol }
+                if value.is_a?(String)
+                  exactness[:yes] += 1
+                  return value.to_sym
+                end
+
               in -> { _1 <= Date || _1 <= Time }
                 Kernel.then do
                   return target.parse(value).tap { exactness[:yes] += 1 }
@@ -282,6 +303,31 @@ module OpenAI
             value
           end
 
+          # @api private
+          # Reuse converter/value pairs within one parse, including recursive collections.
+          # Identity keys avoid recursively hashing model and converter definitions.
+          def coerce_cached(target, value, state:)
+            converters = state.fetch(:memo)
+            values = converters[target] ||= {}.compare_by_identity
+            outcomes = values[value] ||= {}
+            key = state.values_at(:translate_names, :request_only, :strictness, :error)
+            exactness = state.fetch(:exactness)
+            if (cached = outcomes[key])
+              parsed, delta, error, branched = cached
+              delta.each { exactness[_1] += _2 }
+              state[:error] = error
+              state[:branched] += branched
+              return parsed
+            end
+
+            before = exactness.dup
+            branched = state.fetch(:branched)
+            parsed = target.coerce(value, state: state)
+            delta = exactness.to_h { |name, count| [name, count - before.fetch(name)] }
+            outcomes[key] = [parsed, delta, state[:error], state[:branched] - branched]
+            parsed
+          end
+
           # @api private
           #
           # Coerces a value while isolating its error from sibling coercions.
@@ -350,7 +396,8 @@ module OpenAI
               strictness: T::Boolean,
               exactness: {yes: Integer, no: Integer, maybe: Integer},
               error: T.nilable(StandardError),
-              branched: Integer
+              branched: Integer,
+              memo: T.nilable(T::Hash[T.untyped, T.untyped])
             }
           end
         end

data/lib/openai/internal/type/hash_of.rb

@@ -97,7 +97,7 @@ module OpenAI
             return value
           end
 
-          target = item_type
+          target = OpenAI::Internal::Type::Converter.resolve_type(@item_type_fn, state: state)
           exactness[:yes] += 1
           previous_error = state.fetch(:error)
           last_error = nil