llm.rb 4.14.0 → 4.15.0

data/lib/llm/providers/openai/responses/stream_parser.rb

@@ -4,6 +4,8 @@ class LLM::OpenAI
   ##
   # @private
   class Responses::StreamParser
+    EMPTY_HASH = {}.freeze
+
     ##
     # Returns the fully constructed response body
     # @return [Hash]
@@ -16,7 +18,15 @@ class LLM::OpenAI
     def initialize(stream)
       @body = {"output" => []}
       @stream = stream
-      @emits = {tools: []}
+      @emits = {tools: {}}
+      @can_emit_content = stream.respond_to?(:on_content)
+      @can_emit_reasoning_content = stream.respond_to?(:on_reasoning_content)
+      @can_emit_tool_call = stream.respond_to?(:on_tool_call)
+      @can_push_content = stream.respond_to?(:<<)
+      @cached_output_index = nil
+      @cached_output_item = nil
+      @cached_content_index = nil
+      @cached_content_part = nil
     end
 
     ##
@@ -31,126 +41,238 @@ class LLM::OpenAI
     # @return [void]
     def free
       @emits.clear
+      clear_cache!
     end
 
     private
 
+    ##
+    # @group Dispatchers
+
     def handle_event(chunk)
-      case chunk["type"]
-      when "response.created"
-        chunk.each do |k, v|
-          next if k == "type"
-          @body[k] = v
-        end
-        @body["output"] ||= []
-      when "response.in_progress", "response.completed"
-        response = chunk["response"] || {}
-        response.each do |k, v|
-          next if k == "output" && @body["output"].is_a?(Array) && @body["output"].any?
-          @body[k] = v
+      output = @body["output"]
+      type = chunk["type"]
+      if type == "response.output_text.delta"
+        merge_output_text_delta!(output, chunk)
+      elsif type == "response.content_part.added"
+        merge_content_part!(output, chunk)
+      elsif type == "response.output_item.added"
+        merge_output_item!(output, chunk)
+      elsif type == "response.function_call_arguments.delta"
+        merge_function_call_arguments_delta!(output, chunk)
+      elsif type == "response.function_call_arguments.done"
+        merge_function_call_arguments_done!(output, chunk)
+      elsif type == "response.output_item.done"
+        merge_output_item!(output, chunk)
+      elsif type == "response.content_part.done"
+        merge_content_part!(output, chunk, part_key: "part")
+      else
+        case type
+        when "response.created"
+          merge_response_created!(chunk)
+        when "response.in_progress", "response.completed"
+          merge_response_state!(output, chunk)
+        when "response.reasoning_summary_text.delta"
+          merge_reasoning_summary_text_delta!(output, chunk)
+        when "response.reasoning_summary_text.done"
+          merge_reasoning_summary_text_done!(output, chunk)
         end
-        @body["output"] ||= response["output"] || []
-      when "response.output_item.added"
-        output_index = chunk["output_index"]
-        item = chunk["item"]
-        @body["output"][output_index] = item
-        @body["output"][output_index]["content"] ||= []
-        @body["output"][output_index]["summary"] ||= [] if item["type"] == "reasoning"
-      when "response.content_part.added"
-        output_index = chunk["output_index"]
-        content_index = chunk["content_index"]
-        part = chunk["part"]
-        @body["output"][output_index] ||= {"content" => []}
-        @body["output"][output_index]["content"] ||= []
-        @body["output"][output_index]["content"][content_index] = part
-      when "response.reasoning_summary_text.delta"
-        output_item = @body["output"][chunk["output_index"]]
-        if output_item && output_item["type"] == "reasoning"
-          summary_index = chunk["summary_index"] || 0
-          output_item["summary"] ||= []
-          output_item["summary"][summary_index] ||= {"type" => "summary_text", "text" => +""}
-          output_item["summary"][summary_index]["text"] << chunk["delta"]
-          emit_reasoning_content(chunk["delta"])
-        end
-      when "response.reasoning_summary_text.done"
-        output_item = @body["output"][chunk["output_index"]]
-        if output_item && output_item["type"] == "reasoning"
-          summary_index = chunk["summary_index"] || 0
-          output_item["summary"] ||= []
-          output_item["summary"][summary_index] = {
-            "type" => "summary_text",
-            "text" => chunk["text"]
-          }
-        end
-      when "response.output_text.delta"
-        output_index = chunk["output_index"]
-        content_index = chunk["content_index"]
+      end
+    end
+
+    ##
+    # @endgroup
+
+    ##
+    # @group Mergers
+
+    def merge_response_created!(chunk)
+      clear_cache!
+      chunk.each do |k, v|
+        next if k == "type"
+        @body[k] = v
+      end
+      @body["output"] ||= []
+    end
+
+    def merge_response_state!(output, chunk)
+      clear_cache!
+      response = chunk["response"] || EMPTY_HASH
+      response.each do |k, v|
+        next if k == "output" && Array === output && output.any?
+        @body[k] = v
+      end
+      @body["output"] ||= response["output"] || []
+    end
+
+    def merge_output_item!(output, chunk)
+      output_index = chunk["output_index"]
+      item = chunk["item"]
+      output[output_index] = item
+      item["content"] ||= [] if item["type"] == "message" || item.key?("content")
+      item["summary"] ||= [] if item["type"] == "reasoning"
+      cache_output_item!(output_index, item)
+    end
+
+    def merge_content_part!(output, chunk, part_key: "part")
+      output_index = chunk["output_index"]
+      content_index = chunk["content_index"]
+      part = chunk[part_key]
+      output_item = output_item_at(output, output_index)
+      unless output_item
+        output_item = {"content" => []}
+        output[output_index] = output_item
+        cache_output_item!(output_index, output_item)
+      end
+      content = output_item["content"] ||= []
+      content[content_index] = part
+      cache_content_part!(content_index, part)
+    end
+
+    def merge_output_text_delta!(output, chunk)
+      content_part = content_part_at(output, chunk["output_index"], chunk["content_index"])
+      if content_part && content_part["type"] == "output_text"
         delta_text = chunk["delta"]
-        output_item = @body["output"][output_index]
-        if output_item && output_item["content"]
-          content_part = output_item["content"][content_index]
-          if content_part && content_part["type"] == "output_text"
-            content_part["text"] ||= ""
-            content_part["text"] << delta_text
-            emit_content(delta_text)
-          end
+        if text = content_part["text"]
+          text << delta_text
+        else
+          content_part["text"] = delta_text
         end
-      when "response.function_call_arguments.delta"
-        output_item = @body["output"][chunk["output_index"]]
-        if output_item && output_item["type"] == "function_call"
-          output_item["arguments"] ||= +""
-          output_item["arguments"] << chunk["delta"]
+        emit_content(delta_text)
+      end
+    end
+
+    def merge_reasoning_summary_text_delta!(output, chunk)
+      output_item = output_item_at(output, chunk["output_index"])
+      if output_item && output_item["type"] == "reasoning"
+        summary_index = chunk["summary_index"] || 0
+        delta = chunk["delta"]
+        summary = output_item["summary"] ||= []
+        if summary_item = summary[summary_index]
+          summary_item["text"] << delta
+        else
+          summary[summary_index] = {"type" => "summary_text", "text" => delta}
         end
-      when "response.function_call_arguments.done"
-        output_item = @body["output"][chunk["output_index"]]
-        if output_item && output_item["type"] == "function_call"
-          output_item["arguments"] = chunk["arguments"]
-          emit_tool(chunk["output_index"], output_item)
+        emit_reasoning_content(delta)
+      end
+    end
+
+    def merge_reasoning_summary_text_done!(output, chunk)
+      output_item = output_item_at(output, chunk["output_index"])
+      if output_item && output_item["type"] == "reasoning"
+        summary_index = chunk["summary_index"] || 0
+        output_item["summary"] ||= []
+        output_item["summary"][summary_index] = {
+          "type" => "summary_text",
+          "text" => chunk["text"]
+        }
+      end
+    end
+
+    def merge_function_call_arguments_delta!(output, chunk)
+      output_item = output_item_at(output, chunk["output_index"])
+      if output_item && output_item["type"] == "function_call"
+        if arguments = output_item["arguments"]
+          arguments << chunk["delta"]
+        else
+          output_item["arguments"] = chunk["delta"]
         end
-      when "response.output_item.done"
-        output_index = chunk["output_index"]
-        item = chunk["item"]
-        @body["output"][output_index] = item
-      when "response.content_part.done"
-        output_index = chunk["output_index"]
-        content_index = chunk["content_index"]
-        part = chunk["part"]
-        @body["output"][output_index] ||= {"content" => []}
-        @body["output"][output_index]["content"] ||= []
-        @body["output"][output_index]["content"][content_index] = part
       end
     end
 
+    def merge_function_call_arguments_done!(output, chunk)
+      output_item = output_item_at(output, chunk["output_index"])
+      if output_item && output_item["type"] == "function_call"
+        output_item["arguments"] = chunk["arguments"]
+        emit_tool(chunk["output_index"], output_item)
+      end
+    end
+
+    ##
+    # @endgroup
+
+    ##
+    # @group Cache
+
+    def output_item_at(output, output_index)
+      if @cached_output_index == output_index
+        @cached_output_item
+      else
+        cache_output_item!(output_index, output[output_index])
+      end
+    end
+
+    def content_part_at(output, output_index, content_index)
+      if @cached_output_index == output_index && @cached_content_index == content_index
+        @cached_content_part
+      else
+        output_item = output_item_at(output, output_index)
+        content = output_item && output_item["content"]
+        cache_content_part!(content_index, content && content[content_index])
+      end
+    end
+
+    def cache_output_item!(output_index, output_item)
+      @cached_output_index = output_index
+      @cached_output_item = output_item
+      @cached_content_index = nil
+      @cached_content_part = nil
+      output_item
+    end
+
+    def cache_content_part!(content_index, content_part)
+      @cached_content_index = content_index
+      @cached_content_part = content_part
+      content_part
+    end
+
+    def clear_cache!
+      @cached_output_index = nil
+      @cached_output_item = nil
+      @cached_content_index = nil
+      @cached_content_part = nil
+    end
+
+    ##
+    # @endgroup
+
+    ##
+    # @group Emitters
+
     def emit_content(value)
-      if @stream.respond_to?(:on_content)
+      if @can_emit_content
         @stream.on_content(value)
-      elsif @stream.respond_to?(:<<)
+      elsif @can_push_content
         @stream << value
       end
     end
 
     def emit_reasoning_content(value)
-      @stream.on_reasoning_content(value) if @stream.respond_to?(:on_reasoning_content)
+      @stream.on_reasoning_content(value) if @can_emit_reasoning_content
     end
 
     def emit_tool(index, tool)
-      return unless @stream.respond_to?(:on_tool_call)
-      return unless complete_tool?(tool)
-      return if @emits[:tools].include?(index)
-      function, error = resolve_tool(tool)
-      @emits[:tools] << index
+      return unless @can_emit_tool_call
+      return if @emits[:tools][index]
+      return unless tool["call_id"] && tool["name"]
+      arguments = parse_arguments(tool["arguments"])
+      return unless arguments
+      function, error = resolve_tool(tool, arguments)
+      @emits[:tools][index] = true
       @stream.on_tool_call(function, error)
     end
 
-    def complete_tool?(tool)
-      tool["call_id"] && tool["name"] && parse_arguments(tool["arguments"])
-    end
+    ##
+    # @endgroup
 
-    def resolve_tool(tool)
+    ##
+    # @group Resolvers
+
+    def resolve_tool(tool, arguments)
       registered = LLM::Function.find_by_name(tool["name"])
       fn = (registered || LLM::Function.new(tool["name"])).dup.tap do |fn|
         fn.id = tool["call_id"]
-        fn.arguments = parse_arguments(tool["arguments"])
+        fn.arguments = arguments
       end
       [fn, (registered ? nil : @stream.tool_not_found(fn))]
     end
@@ -162,5 +284,8 @@ class LLM::OpenAI
     rescue *LLM.json.parser_error
       nil
     end
+
+    ##
+    # @endgroup
   end
 end

data/lib/llm/providers/openai/stream_parser.rb

@@ -4,6 +4,8 @@ class LLM::OpenAI
   ##
   # @private
   class StreamParser
+    EMPTY_HASH = {}.freeze
+
     ##
     # Returns the fully constructed response body
     # @return [Hash]
@@ -14,7 +16,11 @@ class LLM::OpenAI
     def initialize(stream)
       @body = {}
       @stream = stream
-      @emits = {tools: []}
+      @emits = {tools: {}}
+      @can_emit_content = stream.respond_to?(:on_content)
+      @can_emit_reasoning_content = stream.respond_to?(:on_reasoning_content)
+      @can_emit_tool_call = stream.respond_to?(:on_tool_call)
+      @can_push_content = stream.respond_to?(:<<)
     end
 
     ##
@@ -45,45 +51,68 @@ class LLM::OpenAI
     end
 
     def merge_choices!(choices)
+      body_choices = @body["choices"]
       choices.each do |choice|
         index = choice["index"]
-        if @body["choices"][index]
-          target_message = @body["choices"][index]["message"]
-          delta = choice["delta"] || {}
-          delta.each do |key, value|
-            next if value.nil?
-            if key == "content"
-              target_message[key] ||= +""
-              target_message[key] << value
-              emit_content(value)
-            elsif key == "reasoning_content"
-              target_message[key] ||= +""
-              target_message[key] << value
-              emit_reasoning_content(value)
-            elsif key == "tool_calls"
-              merge_tools!(target_message, value)
-            else
-              target_message[key] = value
-            end
-          end
+        delta = choice["delta"] || EMPTY_HASH
+        target_message = if body_choice = body_choices[index]
+          body_choice["message"]
+        else
+          body_choices[index] = {"message" => {"role" => "assistant"}}
+          body_choices[index]["message"]
+        end
+        merge_delta!(target_message, delta)
+      end
+    end
+
+    def merge_delta!(target_message, delta)
+      if delta.length == 1
+        merge_single_delta!(target_message, delta)
+      elsif content = delta["content"]
+        if target_content = target_message["content"]
+          target_content << content
+        else
+          target_message["content"] = content
+        end
+        emit_content(content)
+      elsif reasoning = delta["reasoning_content"]
+        if target_reasoning = target_message["reasoning_content"]
+          target_reasoning << reasoning
+        else
+          target_message["reasoning_content"] = reasoning
+        end
+        emit_reasoning_content(reasoning)
+      elsif tool_calls = delta["tool_calls"]
+        merge_tools!(target_message, tool_calls)
+      end
+      return if delta.length <= 1
+      delta.each do |key, value|
+        next if value.nil? || key == "content" || key == "reasoning_content" || key == "tool_calls"
+        target_message[key] = value
+      end
+    end
+
+    def merge_single_delta!(target_message, delta)
+      if content = delta["content"]
+        if target_content = target_message["content"]
+          target_content << content
+        else
+          target_message["content"] = content
+        end
+        emit_content(content)
+        return
+      end
+      if reasoning = delta["reasoning_content"]
+        if target_reasoning = target_message["reasoning_content"]
+          target_reasoning << reasoning
         else
-          message_hash = {"role" => "assistant"}
-          @body["choices"][index] = {"message" => message_hash}
-          (choice["delta"] || {}).each do |key, value|
-            next if value.nil?
-            if key == "content"
-              emit_content(value)
-              message_hash[key] = value
-            elsif key == "reasoning_content"
-              emit_reasoning_content(value)
-              message_hash[key] = value
-            elsif key == "tool_calls"
-              merge_tools!(message_hash, value)
-            else
-              message_hash[key] = value
-            end
-          end
+          target_message["reasoning_content"] = reasoning
         end
+        emit_reasoning_content(reasoning)
+        return
+      end
+      if tool_calls = delta["tool_calls"]
+        merge_tools!(target_message, tool_calls)
       end
     end
 
@@ -93,12 +122,11 @@ class LLM::OpenAI
         tindex = toola["index"]
         tindex = index unless Integer === tindex && tindex >= 0
         toolb = target["tool_calls"][tindex]
-        if toolb && toola["function"] && toolb["function"]
+        functiona = toola["function"]
+        functionb = toolb && toolb["function"]
+        if functiona && functionb
           # Append to existing function arguments
-          toola["function"].each do |func_key, func_value|
-            toolb["function"][func_key] ||= +""
-            toolb["function"][func_key] << func_value
-          end
+          merge_function!(functionb, functiona)
         else
           target["tool_calls"][tindex] = toola
         end
@@ -106,40 +134,61 @@ class LLM::OpenAI
       end
     end
 
+    def merge_function!(target, source)
+      if arguments = source["arguments"]
+        if target_arguments = target["arguments"]
+          target_arguments << arguments
+        else
+          target["arguments"] = arguments
+        end
+      end
+      if name = source["name"]
+        if target_name = target["name"]
+          target_name << name
+        else
+          target["name"] = name
+        end
+      end
+      return if source.length <= 2
+      source.each do |func_key, func_value|
+        next if func_key == "arguments" || func_key == "name"
+        target[func_key] ||= +""
+        target[func_key] << func_value
+      end
+    end
+
     def emit_content(value)
-      if @stream.respond_to?(:on_content)
+      if @can_emit_content
         @stream.on_content(value)
-      elsif @stream.respond_to?(:<<)
+      elsif @can_push_content
         @stream << value
       end
     end
 
     def emit_reasoning_content(value)
-      if @stream.respond_to?(:on_reasoning_content)
+      if @can_emit_reasoning_content
         @stream.on_reasoning_content(value)
       end
     end
 
     def emit_tool(tool, tindex)
-      return unless @stream.respond_to?(:on_tool_call)
-      return unless complete_tool?(tool)
-      return if @emits[:tools].include?(tindex)
-      function, error = resolve_tool(tool)
-      @emits[:tools] << tindex
-      @stream.on_tool_call(function, error)
-    end
-
-    def complete_tool?(tool)
+      return unless @can_emit_tool_call
+      return if @emits[:tools][tindex]
       function = tool["function"]
-      function && tool["id"] && function["name"] && parse_arguments(function["arguments"])
+      return unless function && tool["id"] && function["name"]
+      return unless arguments_complete?(function["arguments"])
+      arguments = parse_arguments(function["arguments"])
+      return unless arguments
+      function, error = resolve_tool(tool, function, arguments)
+      @emits[:tools][tindex] = true
+      @stream.on_tool_call(function, error)
     end
 
-    def resolve_tool(tool)
-      function = tool["function"]
+    def resolve_tool(tool, function, arguments)
       registered = LLM::Function.find_by_name(function["name"])
       fn = (registered || LLM::Function.new(function["name"])).dup.tap do |fn|
         fn.id = tool["id"]
-        fn.arguments = parse_arguments(function["arguments"])
+        fn.arguments = arguments
       end
       [fn, (registered ? nil : @stream.tool_not_found(fn))]
     end
@@ -151,5 +200,10 @@ class LLM::OpenAI
     rescue *LLM.json.parser_error
       nil
     end
+
+    def arguments_complete?(arguments)
+      value = arguments.to_s.rstrip
+      !value.empty? && value.end_with?("}")
+    end
   end
 end

data/lib/llm/response.rb

@@ -2,10 +2,18 @@
 
 module LLM
   ##
-  # {LLM::Response LLM::Response} encapsulates a response
-  # from an LLM provider. It is returned by all methods
-  # that make requests to a provider, and sometimes extended
-  # with provider-specific functionality.
+  # {LLM::Response LLM::Response} is the normalized base shape for
+  # provider and endpoint responses in llm.rb.
+  #
+  # Provider calls return an instance of this class, then extend it
+  # with provider-, endpoint-, or context-specific modules so response
+  # handling can share one common surface without flattening away
+  # specialized behavior.
+  #
+  # The normalized response still keeps the original
+  # {Net::HTTPResponse Net::HTTPResponse} available through {#res}
+  # when callers need direct access to raw HTTP details such as
+  # headers, status codes, or unadapted bodies.
   class Response
     require "json"