openai 0.85.0 → 0.86.0

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

@@ -22,17 +22,18 @@ module OpenAI
       #
       # Emitted as the assistant's text response is being generated. Each event
       # contains the new text fragment (delta) and the complete accumulated
-      # text so far (snapshot).
+      # text so far (snapshot). Use these string values while content is
+      # streaming; when using structured outputs, typed parsed content is
+      # available from the done event or final completion.
       #
       # @example
       #   event.delta    # => "Hello"        (new fragment)
       #   event.snapshot # => "Hello world"  (accumulated text)
-      #   event.parsed   # => {name: "John"} (if using structured outputs)
       class ChatContentDeltaEvent < OpenAI::Internal::Type::BaseModel
         required :type, const: :"content.delta"
         required :delta, String
         required :snapshot, String
-        # Partially parsed structured output
+        # Parsed content for structured outputs is available from done/final results.
         optional :parsed, Object
       end
 
@@ -81,14 +82,15 @@ module OpenAI
       # Incremental function tool call arguments update.
       #
       # Emitted as function arguments are being streamed. Provides both the
-      # raw JSON fragments and incrementally parsed arguments for strict tools.
+      # raw JSON fragments and, for strict tools, parsed arguments once the
+      # accumulated arguments are complete, valid JSON.
       #
       # @example
       #   event.name            # => "get_weather"
       #   event.index           # => 0 (tool call index in array)
-      #   event.arguments_delta # => '{"location": "San'  (new fragment)
-      #   event.arguments       # => '{"location": "San Francisco"'  (accumulated JSON)
-      #   event.parsed # => {location: "San Francisco"}  (if strict: true)
+      #   event.arguments_delta # => ' Francisco"}'  (new fragment)
+      #   event.arguments       # => '{"location": "San Francisco"}'  (accumulated JSON)
+      #   event.parsed # => {location: "San Francisco"}  (for a strict tool)
       class ChatFunctionToolCallArgumentsDeltaEvent < OpenAI::Internal::Type::BaseModel
         required :type, const: :"tool_calls.function.arguments.delta"
         required :name, String

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

@@ -19,18 +19,26 @@ module OpenAI
         end
 
         def until_done
-          each { |_event| next }
+          text.each { |_delta| nil }
           self
         end
 
         def text
           OpenAI::Internal::Util.chain_fused(@iterator) do |yielder|
+            @text_only = true
             @iterator.each do |event|
+              # Restore normal event snapshots while caller code is running.
+              @text_only = false
               case event
               when OpenAI::Models::Responses::ResponseTextDeltaEvent
                 yielder << event.delta
               end
+
+              @text_only = true
             end
+
+          ensure
+            @text_only = false
           end
         end
 
@@ -46,10 +54,11 @@ module OpenAI
           text_parts = []
 
           response.output.each do |output|
-            next unless output.type == :message
+            next unless output.is_a?(OpenAI::Models::Responses::ResponseOutputMessage)
 
             output.content.each do |content|
-              next unless content.type == :output_text
+              next unless content.is_a?(OpenAI::Models::Responses::ResponseOutputText)
+
               text_parts << content.text
             end
           end
@@ -62,7 +71,7 @@ module OpenAI
         def iterator
           @iterator ||= OpenAI::Internal::Util.chain_fused(@raw_stream) do |y|
             @raw_stream.each do |raw_event|
-              events_to_yield = @state.handle_event(raw_event)
+              events_to_yield = @state.handle_event(raw_event, text_only: @text_only == true)
               events_to_yield.each do |event|
                 y << event if after_starting_event?(event)
               end
@@ -86,9 +95,10 @@ module OpenAI
           @completed_response = nil
           @text_format = text_format
           @resumed = !starting_after.nil?
+          @unexposed_buffers = {}.compare_by_identity
         end
 
-        def handle_event(event)
+        def handle_event(event, text_only: false)
           return [event] if event.is_a?(UnknownStreamEvent)
 
           @current_snapshot = accumulate_event(
@@ -100,38 +110,31 @@ module OpenAI
 
           case event
           when OpenAI::Models::Responses::ResponseTextDeltaEvent
+            return [event] if text_only
+
+            snapshot = nil
             if @current_snapshot
               output = @current_snapshot.output[event.output_index]
-              assert_type(output, :message)
-
-              content = output.content[event.content_index]
-              assert_type(content, :output_text)
-              events_to_yield <<
-                OpenAI::Streaming::ResponseTextDeltaEvent.new(
-                  content_index: event.content_index,
-                  delta: event.delta,
-                  item_id: event.item_id,
-                  output_index: event.output_index,
-                  sequence_number: event.sequence_number,
-                  type: event.type,
-                  snapshot: content.text
-                )
-            else
-              # A server-directed resumed stream may begin after response.created.
-              # Without the omitted prefix, a snapshot would be incomplete and
-              # materializing every partial prefix would make streaming quadratic.
-              events_to_yield <<
-                OpenAI::Streaming::ResponseTextDeltaEvent.new(event.to_h.merge(snapshot: nil))
+              if output.is_a?(OpenAI::Models::Responses::ResponseOutputMessage)
+                content = output.content[event.content_index]
+                snapshot = content.text if content.is_a?(OpenAI::Models::Responses::ResponseOutputText)
+              end
             end
 
+            @unexposed_buffers.delete(snapshot)
+
+            # A server-directed resumed stream or an unknown future snapshot value
+            # has no complete prefix from which to build a truthful snapshot.
+            events_to_yield <<
+              OpenAI::Streaming::ResponseTextDeltaEvent.new(event.to_h.merge(snapshot: snapshot))
+
           when OpenAI::Models::Responses::ResponseTextDoneEvent
             text = if @current_snapshot
               output = @current_snapshot.output[event.output_index]
-              assert_type(output, :message)
-
-              content = output.content[event.content_index]
-              assert_type(content, :output_text)
-              content.text
+              if output.is_a?(OpenAI::Models::Responses::ResponseOutputMessage)
+                content = output.content[event.content_index]
+                content.text if content.is_a?(OpenAI::Models::Responses::ResponseOutputText)
+              end
             else
               event.text
             end
@@ -146,31 +149,30 @@ module OpenAI
                 sequence_number: event.sequence_number,
                 text: event.text,
                 type: event.type,
+                **event.to_h.slice(:logprobs),
                 parsed: parsed
               )
 
           when OpenAI::Models::Responses::ResponseFunctionCallArgumentsDeltaEvent
+            return [event] if text_only
+
+            snapshot = nil
             if @current_snapshot
               output = @current_snapshot.output[event.output_index]
-              assert_type(output, :function_call)
-              events_to_yield <<
-                OpenAI::Streaming::ResponseFunctionCallArgumentsDeltaEvent.new(
-                  delta: event.delta,
-                  item_id: event.item_id,
-                  output_index: event.output_index,
-                  sequence_number: event.sequence_number,
-                  type: event.type,
-                  snapshot: output.arguments
-                )
-            else
-              # See the text-delta branch above: a partial server resume has no
-              # complete argument prefix from which to build a truthful snapshot.
-              events_to_yield <<
-                OpenAI::Streaming::ResponseFunctionCallArgumentsDeltaEvent.new(
-                  event.to_h.merge(snapshot: nil)
-                )
+              if output.is_a?(OpenAI::Models::Responses::ResponseFunctionToolCall)
+                snapshot = output.arguments
+              end
             end
 
+            @unexposed_buffers.delete(snapshot)
+
+            # See the text-delta branch above: a partial server resume or an
+            # unknown future output item has no truthful accumulated prefix.
+            events_to_yield <<
+              OpenAI::Streaming::ResponseFunctionCallArgumentsDeltaEvent.new(
+                event.to_h.merge(snapshot: snapshot)
+              )
+
           when OpenAI::Models::Responses::ResponseCompletedEvent
             events_to_yield <<
               OpenAI::Streaming::ResponseCompletedEvent.new(
@@ -211,17 +213,17 @@ module OpenAI
 
           when OpenAI::Models::Responses::ResponseContentPartAddedEvent
             output = current_snapshot.output[event.output_index]
-            if output && output.type == :message
+            if output.is_a?(OpenAI::Models::Responses::ResponseOutputMessage)
               output.content.push(isolated_value(event.part))
               current_snapshot.output[event.output_index] = output
             end
 
           when OpenAI::Models::Responses::ResponseTextDeltaEvent
             output = current_snapshot.output[event.output_index]
-            if output && output.type == :message
+            if output.is_a?(OpenAI::Models::Responses::ResponseOutputMessage)
               content = output.content[event.content_index]
-              if content && content.type == :output_text
-                content.text += event.delta
+              if content.is_a?(OpenAI::Models::Responses::ResponseOutputText)
+                content.text = append_delta(content.text, event.delta)
                 output.content[event.content_index] = content
                 current_snapshot.output[event.output_index] = output
               end
@@ -229,8 +231,8 @@ module OpenAI
 
           when OpenAI::Models::Responses::ResponseFunctionCallArgumentsDeltaEvent
             output = current_snapshot.output[event.output_index]
-            if output && output.type == :function_call
-              output.arguments = (output.arguments || "") + event.delta
+            if output.is_a?(OpenAI::Models::Responses::ResponseFunctionToolCall)
+              output.arguments = append_delta(output.arguments || "", event.delta)
               current_snapshot.output[event.output_index] = output
             end
 
@@ -243,6 +245,16 @@ module OpenAI
 
         private
 
+        # Reuse a buffer only until it becomes a caller-visible snapshot. The
+        # first append also isolates strings belonging to incoming wire events.
+        def append_delta(value, delta)
+          return value << delta if @unexposed_buffers.key?(value)
+
+          buffer = value + delta
+          @unexposed_buffers[buffer] = true
+          buffer
+        end
+
         # Materialize fresh containers before snapshot accumulation mutates them.
         # Coercing an already-typed model returns it unchanged, so first use the
         # model's recursive raw representation. Unknown union fallbacks stay raw.
@@ -253,22 +265,16 @@ module OpenAI
           OpenAI::Internal::Type::Converter.coerce(value.class, raw)
         end
 
-        def assert_type(object, expected_type)
-          return if object && object.type == expected_type
-          actual_type = object ? object.type : "nil"
-          raise "Invalid state: expected #{expected_type} but got #{actual_type}"
-        end
-
         def parse_structured_text(text)
           return nil unless @text_format && text
 
           begin
             parsed = JSON.parse(text, symbolize_names: true)
             OpenAI::Internal::Type::Converter.coerce(@text_format, parsed)
-          rescue JSON::ParserError => e
+          rescue JSON::ParserError
             raise(
-              "Failed to parse structured text as JSON for #{@text_format}: #{e.message}. " \
-                "Raw text: #{text.inspect}"
+              "Failed to parse structured text as JSON for #{@text_format}",
+              cause: nil
             )
           end
         end

data/lib/openai/helpers/structured_output/json_schema_converter.rb

@@ -109,7 +109,7 @@ module OpenAI
                 stored[OpenAI::Helpers::StructuredOutput::JsonSchemaConverter::RECURSIVE] = true
               end
 
-              pointers.first.except(OpenAI::Helpers::StructuredOutput::JsonSchemaConverter::NO_REF).tap do
+              pointers.first.slice(:$ref).tap do
                 pointers << _1
               end
             else

data/lib/openai/helpers/structured_output/response_parser.rb

@@ -85,7 +85,7 @@ module OpenAI
           in {
               text: {
                   format: {
-                      type: :json_schema,
+                      type: :json_schema | "json_schema",
                       schema: OpenAI::StructuredOutput::JsonSchemaConverter => model
                     }
                 }
@@ -108,7 +108,7 @@ module OpenAI
                   name: name,
                   parameters: tool.to_json_schema
                 }
-              in {type: :function, parameters: OpenAI::StructuredOutput::JsonSchemaConverter => params}
+              in {type: :function | "function", parameters: OpenAI::StructuredOutput::JsonSchemaConverter => params}
                 func = tool.fetch(:function, tool)
                 name = func[:name] ||= params.name.split("::").last
                 tool_models.store(name, params)
@@ -139,6 +139,129 @@ module OpenAI
 
           [model, tool_models]
         end
+
+        # Extracts retrieval-local structured-output hints without mutating caller-owned values.
+        #
+        # @api private
+        #
+        # @param parsed [Hash] Dumped retrieval parameters containing local text/tool hints
+        # @return [Array<(JsonSchemaConverter|nil, Hash)>] Text model and named tool models
+        def self.get_retrieval_models(parsed)
+          get_models(duplicate_retrieval_params(parsed.slice(:text, :tools)))
+        end
+
+        # Parses retrieval output only when status and payload shape indicate it is complete.
+        #
+        # @api private
+        #
+        # @param raw [Hash] The raw retrieved response hash that will be mutated with parsed data
+        # @param model [JsonSchemaConverter, nil] The converter for structured text output
+        # @param tool_models [Hash<String, JsonSchemaConverter>] Tool names and their converters
+        # @return [Hash] The same response with typed values in its :parsed fields when ready
+        def self.parse_retrieved!(raw, model, tool_models)
+          staged = {}.compare_by_identity
+          return raw unless retrieval_complete?(raw, model, tool_models, staged)
+
+          parse!(raw.merge(output: parsable_output(raw, staged)), model, tool_models)
+          staged.each_value do |target, converter, parsed|
+            target.store(:parsed, OpenAI::Internal::Type::Converter.coerce(converter, parsed))
+          end
+
+          raw
+        end
+
+        def self.retrieval_complete?(raw, model, tool_models, staged)
+          return false unless [nil, "completed"].include?(raw[:status])
+
+          raw[:output].to_a.none? do |output|
+            case output[:type]
+            when "message"
+              model && unfinished_message?(output, model, staged, response_status: raw[:status])
+            when "function_call"
+              unfinished_function_call?(output, tool_models, staged, response_status: raw[:status])
+            else
+              false
+            end
+          end
+        end
+
+        def self.unfinished_message?(output, model, staged, response_status:)
+          return true if pending_status?(output[:status])
+          return false unless response_status.nil? && output[:status].nil?
+
+          output[:content].to_a.any? do |content|
+            next false unless content[:type] == "output_text"
+            next true unless content.key?(:text)
+
+            ready, parsed = prepare_value(content[:text])
+            staged.store(content, [content, model, parsed]) if ready
+            !ready
+          end
+        end
+
+        def self.unfinished_function_call?(output, tool_models, staged, response_status:)
+          return false if tool_models.empty?
+          return false unless output.key?(:name)
+          return false unless tool_models.key?(output[:name])
+          return true if pending_status?(output[:status])
+          return false unless response_status.nil? && output[:status].nil?
+          return true unless output.key?(:arguments)
+
+          model = tool_models.fetch(output[:name])
+          ready, parsed = prepare_value(output[:arguments])
+          staged.store(output, [output, model, parsed]) if ready
+          !ready
+        end
+
+        def self.pending_status?(status)
+          ["queued", "in_progress", "incomplete"].include?(status)
+        end
+
+        def self.prepare_value(value)
+          [true, JSON.parse(value, symbolize_names: true)]
+        rescue JSON::ParserError, TypeError
+          [false, nil]
+        end
+
+        def self.parsable_output(raw, staged)
+          raw[:output].to_a.filter_map do |output|
+            next if output[:type] == "function_call" && (!output.key?(:name) || staged.key?(output))
+            next output unless output[:type] == "message"
+
+            content = output[:content].to_a.reject { |item| staged.key?(item) }
+            output.merge(content: content)
+          end
+        end
+
+        def self.duplicate_retrieval_params(value)
+          case value
+          when Array
+            value.map { |item| duplicate_retrieval_params(item) }
+          when Hash
+            value.to_h do |key, item|
+              normalized_key = key.is_a?(String) ? key.to_sym : key
+              normalized_key = :format if normalized_key == :format_
+              normalized_item = duplicate_retrieval_params(item)
+              if normalized_key == :type && ["function", "json_schema"].include?(normalized_item)
+                normalized_item = normalized_item.to_sym
+              end
+
+              [normalized_key, normalized_item]
+            end
+          else
+            value
+          end
+        end
+
+        private_class_method(
+          :duplicate_retrieval_params,
+          :parsable_output,
+          :pending_status?,
+          :prepare_value,
+          :retrieval_complete?,
+          :unfinished_function_call?,
+          :unfinished_message?
+        )
       end
     end
   end