prompt_builder 0.3.0 → 0.5.0

data/lib/prompt_builder/serializers/converse.rb

@@ -7,6 +7,7 @@ module PromptBuilder
     class Converse < Base
       autoload :Request, File.expand_path("converse/request", __dir__)
       autoload :Response, File.expand_path("converse/response", __dir__)
+      autoload :StreamAccumulator, File.expand_path("converse/stream_accumulator", __dir__)
 
       class << self
         # Export a session to Converse request payload.
@@ -16,14 +17,6 @@ module PromptBuilder
         def request_payload(session)
           Request.request_payload(session)
         end
-
-        # Parse a Converse response into a PromptBuilder::Response.
-        #
-        # @param hash [Hash] the response hash in Converse format
-        # @return [PromptBuilder::Response] the parsed response
-        def parse_response(hash)
-          Response.parse_response(hash)
-        end
       end
     end
   end

data/lib/prompt_builder/serializers/gemini/request.rb

@@ -23,6 +23,9 @@ module PromptBuilder
       # - +parallel_tool_calls+ — parallel tool call control is not supported
       # - +prompt_cache_key+ / +prompt_cache_retention+ — explicit prompt cache keys are not supported
       # - +safety_identifier+ — no equivalent user-safety field on the generate endpoint
+      # - +stream+ — streaming is selected by endpoint (+streamGenerateContent+),
+      #   not a request body field; Gemini::StreamAccumulator (or
+      #   Response.parse_stream) reassembles the streamed response
       # - +stream_options+ — stream event options are not supported
       # - +truncation+ — server-side context truncation is not supported
       #
@@ -52,8 +55,13 @@ module PromptBuilder
       #
       # The following Gemini parameters cannot be set through the Open Responses
       # canonical format:
-      # - +thinkingConfig.thinkingBudget+ — use +reasoning.budget_tokens+ instead
+      # - +thinkingConfig.thinkingBudget+ — use +reasoning.budget_tokens+ instead;
+      #   +reasoning.type: "disabled"+ (Session#think(false)) is sent as
+      #   +thinkingBudget: 0+ in place of any budget or effort, and models
+      #   that cannot turn thinking off reject it
       # - +thinkingConfig.thinkingLevel+ — use +reasoning.effort+ instead
+      #   (levels are upcased and forwarded as is; combining it with
+      #   +reasoning.budget_tokens+ raises, since the API rejects both together)
       # - +thinkingConfig.includeThoughts+ — use +reasoning.summary = "auto"+ instead
       # - +topK+ — top-K sampling parameter
       # - +seed+ — for reproducible outputs (model-dependent)
@@ -77,7 +85,6 @@ module PromptBuilder
       # - +cachedContent+ — referencing a CachedContent resource by name
       # - Top-level +labels+ (Vertex flavor only)
       class Request < Base
-        SUPPORTED_REASONING_EFFORTS = %w[minimal low medium high].freeze
         SUPPORTED_REASONING_SUMMARIES = %w[auto].freeze
         SUPPORTED_SERVICE_TIERS = %w[unspecified standard flex priority].freeze
 
@@ -493,14 +500,25 @@ module PromptBuilder
               # Unsupported reasoning.* keys are silently omitted.
               thinking_config = {}
 
-              if session.reasoning["budget_tokens"]
-                thinking_config["thinkingBudget"] = session.reasoning["budget_tokens"]
+              if reasoning_disabled?(session.reasoning)
+                # A zero budget turns thinking off. It replaces any budget or
+                # effort set alongside it, since the API rejects a budget
+                # together with a level. Models that cannot turn thinking off
+                # reject it.
+                thinking_config["thinkingBudget"] = 0
+              else
+                if session.reasoning["budget_tokens"]
+                  thinking_config["thinkingBudget"] = session.reasoning["budget_tokens"]
+                end
+
+                effort = session.reasoning["effort"]
+                # Effort levels are forwarded as is; the levels a model accepts vary.
+                thinking_config["thinkingLevel"] = effort.to_s.upcase if effort
               end
 
-              effort = session.reasoning["effort"]
-              # Unsupported effort levels are silently omitted.
-              if effort && SUPPORTED_REASONING_EFFORTS.include?(effort)
-                thinking_config["thinkingLevel"] = effort.upcase
+              if thinking_config.key?("thinkingBudget") && thinking_config.key?("thinkingLevel")
+                raise UnsupportedFormatError,
+                  "Gemini format does not support reasoning.budget_tokens together with reasoning.effort"
               end
 
               summary = session.reasoning["summary"]

data/lib/prompt_builder/serializers/gemini/stream_accumulator.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  module Serializers
+    class Gemini < Base
+      # Reassembles a Gemini +streamGenerateContent+ stream into the
+      # +GenerateContentResponse+ the non-streaming +generateContent+ endpoint
+      # would have returned.
+      #
+      # With +alt=sse+ each event is a complete +GenerateContentResponse+
+      # chunk. Candidates are merged by +index+: their parts are concatenated
+      # in order, and a text part that starts a chunk continues the text part
+      # that ended the previous chunk when both are the same kind (thought or
+      # not), keeping the +thoughtSignature+; two parts that both carry a
+      # signature stay separate. Parts within one chunk are distinct parts and
+      # are never merged with each other. A part with only a
+      # +thoughtSignature+ and no text is the signature for the text before it,
+      # so it is attached to that text part. +functionCall+ and other parts
+      # arrive whole. +citationMetadata.citationSources+ and the
+      # +logprobsResult+ token lists are concatenated (with +logProbabilitySum+
+      # recomputed from the chosen tokens), and every other field
+      # (+finishReason+, +usageMetadata+, +modelVersion+, +responseId+, ...) is
+      # taken from the last chunk that has it.
+      #
+      # Without +alt=sse+ the endpoint returns a JSON array of the same chunks;
+      # it is buffered whole and merged the same way.
+      #
+      # Gemini sends no terminal event, so a stream whose candidates have no
+      # +finishReason+ (and that was not blocked by +promptFeedback.blockReason+)
+      # is incomplete. A chunk with an +error+ raises an ErrorResponseError.
+      class StreamAccumulator < Streaming::Accumulator
+        TEXT_PART_KEYS = %w[text thought thoughtSignature].freeze
+        private_constant :TEXT_PART_KEYS
+
+        LOGPROBS_TOKEN_LISTS = %w[topCandidates chosenCandidates].freeze
+        private_constant :LOGPROBS_TOKEN_LISTS
+
+        def initialize
+          super
+          @response = {}
+          @candidates = {}
+        end
+
+        private
+
+        def handle_event(event)
+          merge_chunk(parse_json(event.data))
+        end
+
+        def collapse_json(value)
+          return value unless value.is_a?(Array)
+
+          value.each { |chunk| merge_chunk(chunk) }
+          build_result
+        end
+
+        def merge_chunk(chunk)
+          return unless chunk.is_a?(Hash)
+
+          if chunk["error"].is_a?(Hash)
+            error = chunk["error"]
+            raise_error_event!([error["status"] || error["code"], error["message"]].compact.join(": "))
+          end
+
+          chunk.each do |key, value|
+            next if value.nil?
+
+            if key == "candidates"
+              value.each_with_index { |candidate, position| merge_candidate(candidate, position) if candidate.is_a?(Hash) }
+            else
+              @response[key] = value
+            end
+          end
+        end
+
+        def merge_candidate(candidate, position)
+          merged = @candidates[candidate["index"] || position] ||= {}
+          candidate.each do |key, value|
+            next if value.nil?
+
+            case key
+            when "content"
+              merge_content(merged, value) if value.is_a?(Hash)
+            when "citationMetadata"
+              merge_citation_metadata(merged, value) if value.is_a?(Hash)
+            when "logprobsResult"
+              merge_logprobs_result(merged, value) if value.is_a?(Hash)
+            else
+              merged[key] = value
+            end
+          end
+        end
+
+        def merge_content(merged, content)
+          target = merged["content"] ||= {"parts" => []}
+          content.each { |key, value| target[key] = value unless key == "parts" || value.nil? }
+          parts = (content["parts"] || []).select { |part| part.is_a?(Hash) }
+          parts.each_with_index { |part, position| append_part(target["parts"], part, continuation: position.zero?) }
+        end
+
+        # Only the first part of a chunk can continue text from the previous
+        # chunk; later parts in the same chunk are separate parts in the
+        # response, so they keep their own boundaries and signatures.
+        def append_part(parts, part, continuation:)
+          last = parts.last
+          if signature_only?(part) && text_part?(last) && !last["thoughtSignature"]
+            last["thoughtSignature"] = part["thoughtSignature"]
+          elsif continuation && mergeable_text?(last, part)
+            last["text"] << part["text"]
+            last["thoughtSignature"] = part["thoughtSignature"] if part["thoughtSignature"]
+          elsif text_part?(part)
+            parts << part.merge("text" => +part["text"])
+          else
+            parts << part
+          end
+        end
+
+        def mergeable_text?(last, part)
+          return false unless text_part?(last) && text_part?(part)
+          return false unless !!last["thought"] == !!part["thought"]
+
+          !(last["thoughtSignature"] && part["thoughtSignature"])
+        end
+
+        def text_part?(part)
+          part.is_a?(Hash) && part["text"].is_a?(String) && (part.keys - TEXT_PART_KEYS).empty?
+        end
+
+        def signature_only?(part)
+          part["thoughtSignature"].is_a?(String) && !part.key?("text") && (part.keys - TEXT_PART_KEYS).empty?
+        end
+
+        def merge_citation_metadata(merged, metadata)
+          target = merged["citationMetadata"] ||= {}
+          metadata.each do |key, value|
+            if key == "citationSources" && value.is_a?(Array)
+              (target[key] ||= []).concat(value)
+            elsif !value.nil?
+              target[key] = value
+            end
+          end
+        end
+
+        # Each chunk reports log probabilities for its own tokens, so the
+        # token lists are concatenated in order. The sum is recomputed for the
+        # whole candidate once the stream ends (see #recompute_logprobs_sum).
+        def merge_logprobs_result(merged, result)
+          target = merged["logprobsResult"] ||= {}
+          result.each do |key, value|
+            if LOGPROBS_TOKEN_LISTS.include?(key) && value.is_a?(Array)
+              (target[key] ||= []).concat(value)
+            elsif !value.nil?
+              target[key] = value
+            end
+          end
+        end
+
+        def recompute_logprobs_sum(candidate)
+          result = candidate["logprobsResult"]
+          return unless result&.key?("logProbabilitySum")
+
+          chosen = result["chosenCandidates"]
+          return unless chosen
+
+          result["logProbabilitySum"] = chosen.sum { |token| token.is_a?(Hash) ? token["logProbability"].to_f : 0.0 }
+        end
+
+        def build_result
+          candidates = @candidates.sort_by { |index, _| index.to_i }.map { |_, candidate| candidate }
+          blocked = @response.dig("promptFeedback", "blockReason")
+          finished = !candidates.empty? && candidates.all? { |candidate| finished_candidate?(candidate) }
+          incomplete!("Gemini stream ended without a finishReason") unless blocked || finished
+
+          candidates.each { |candidate| recompute_logprobs_sum(candidate) }
+          @response.merge("candidates" => candidates)
+        end
+
+        # FINISH_REASON_UNSPECIFIED is the API's default value, which the
+        # response parser treats as no finish reason, so it does not mark a
+        # candidate as finished either.
+        def finished_candidate?(candidate)
+          reason = candidate["finishReason"]
+          !reason.nil? && reason != "FINISH_REASON_UNSPECIFIED"
+        end
+      end
+    end
+  end
+end

data/lib/prompt_builder/serializers/gemini.rb

@@ -7,6 +7,7 @@ module PromptBuilder
     class Gemini < Base
       autoload :Request, File.expand_path("gemini/request", __dir__)
       autoload :Response, File.expand_path("gemini/response", __dir__)
+      autoload :StreamAccumulator, File.expand_path("gemini/stream_accumulator", __dir__)
 
       class << self
         # Export a session to Gemini request payload.
@@ -16,14 +17,6 @@ module PromptBuilder
         def request_payload(session)
           Request.request_payload(session)
         end
-
-        # Parse a Gemini response into a PromptBuilder::Response.
-        #
-        # @param hash [Hash] the response hash in Gemini format
-        # @return [PromptBuilder::Response] the parsed response
-        def parse_response(hash)
-          Response.parse_response(hash)
-        end
       end
     end
   end

data/lib/prompt_builder/serializers/messages/request.rb

@@ -30,10 +30,20 @@ module PromptBuilder
       #   also mapped into +metadata.user_id+ automatically
       # - +service_tier+ — only +auto+ and +standard_only+ are accepted
       # - +text+ — +format.type=json_schema+ is mapped to +output_config.format+
-      # - +reasoning+ — +budget_tokens+, +display+, +effort+, and +type+ are forwarded;
-      #   +temperature+ must be unset, +top_p+ must be >= 0.95, and
-      #   +max_output_tokens+ must be greater than +budget_tokens+ when reasoning
-      #   is enabled
+      # - +reasoning+ — +type+, +budget_tokens+, and +display+ are forwarded to
+      #   +thinking+ and +effort+ to +output_config.effort+. A configuration
+      #   that asks for thinking emits a +thinking+ parameter, since omitting
+      #   it leaves the thinking mode to the model instead of turning thinking
+      #   on: +thinking.type+ defaults to +enabled+ when +budget_tokens+ is set
+      #   and to +adaptive+ for +display+, an empty configuration (bare
+      #   Session#think), or an +effort+ level. Adaptive thinking is not
+      #   inferred from +effort+ alongside +temperature+, a +top_p+ below 0.95,
+      #   or a forced +tool_choice+; the effort is sent on its own. Effort
+      #   levels are forwarded as is. +type: "disabled"+ (Session#think(false))
+      #   is sent as +thinking.type: "disabled"+, alongside any effort, and
+      #   does not count as thinking. When thinking is on, +temperature+ must
+      #   be unset, +top_p+ must be >= 0.95, and +max_output_tokens+ must be
+      #   greater than +budget_tokens+
       #
       # Input content restrictions:
       # - System and developer messages are hoisted out of conversational order
@@ -60,6 +70,23 @@ module PromptBuilder
       # - +FunctionCallOutput.status+ values +incomplete+, +failed+, and +error+
       #   are mapped to +tool_result.is_error: true+
       #
+      # === Model-dependent parameters
+      #
+      # Which values the API accepts for these depends on the model, and the
+      # serialized payload carries no model capability information, so beyond
+      # the thinking constraints above they are forwarded without validation:
+      # - +temperature+ and +top_p+ — rejected outright by some models and
+      #   accepted only at their default values by others
+      # - +reasoning.type+ — +adaptive+ is accepted wherever adaptive thinking
+      #   exists and +enabled+ (with a budget) only by models predating it;
+      #   +disabled+ is rejected by some models and restricted to the lower
+      #   effort levels by others; +between_tools+ is only offered by some
+      #   models as their lowest thinking setting
+      # - +reasoning.effort+ — the levels a model accepts, alone or combined
+      #   with a +reasoning.type+, vary by model
+      # - Forced +tool_choice+ (+any+/+tool+ type) — rejected by some models
+      #   regardless of the thinking configuration
+      #
       # === Features in the Messages API not available through Open Responses
       #
       # The following Messages API parameters cannot be set through the Open Responses
@@ -84,8 +111,6 @@ module PromptBuilder
       #   request — set headers in your HTTP client)
       class Request < Base
         SUPPORTED_METADATA_KEYS = ["user_id"].freeze
-        EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"].freeze
-        SUPPORTED_THINKING_TYPES = ["adaptive", "disabled", "enabled"].freeze
         SUPPORTED_TOOL_CHOICE_TYPES = ["any", "auto", "none", "tool"].freeze
 
         # Citation types accepted by the Messages API on text blocks. Annotations
@@ -127,7 +152,9 @@ module PromptBuilder
             output_config = build_output_config(session)
             h["output_config"] = output_config unless output_config.empty?
 
-            thinking = serialize_thinking(session.reasoning)
+            tools = build_tools(session)
+
+            thinking = serialize_thinking(session, tools)
             validate_thinking_compatibility!(session, thinking) if thinking_active?(thinking)
             h["thinking"] = thinking if thinking
 
@@ -145,14 +172,13 @@ module PromptBuilder
             end
             h["messages"] = messages
 
-            tools = build_tools(session)
             h["tools"] = tools unless tools.empty?
 
             tool_choice = serialize_tool_choice(
               session.tool_choice,
               tools: tools,
               parallel_tool_calls: session.parallel_tool_calls,
-              thinking_enabled: thinking_active?(thinking)
+              thinking_active: thinking_active?(thinking)
             )
             h["tool_choice"] = tool_choice if tool_choice
 
@@ -194,37 +220,77 @@ module PromptBuilder
             service_tier if ["auto", "standard_only"].include?(service_tier)
           end
 
-          def serialize_thinking(reasoning)
+          # A reasoning configuration that asks for thinking emits a +thinking+
+          # parameter, since omitting it leaves the mode to the model rather
+          # than turning thinking on. An explicit +type+ is forwarded as is;
+          # otherwise the type is inferred: +enabled+ for a +budget_tokens+
+          # budget (the only mode with a fixed budget), and +adaptive+ for
+          # +display+, for the empty configuration stored by a bare
+          # Session#think, or for an +effort+ level.
+          #
+          # Effort is also a valid control without thinking, so adaptive
+          # thinking is only inferred from effort when the payload can accept
+          # it; alongside sampling parameters or a forced tool_choice the effort
+          # is sent on its own. Configurations without any of these keys (e.g.
+          # one holding only another provider's +summary+ key) emit nothing.
+          def serialize_thinking(session, tools)
+            reasoning = session.reasoning
             return nil unless reasoning
 
-            thinking = {}
-            thinking["budget_tokens"] = reasoning["budget_tokens"] if reasoning.key?("budget_tokens")
+            type = reasoning["type"]
+            type ||= "enabled" unless reasoning["budget_tokens"].nil?
+            type ||= "adaptive" if reasoning.empty? || reasoning["display"]
+            if type.nil? && reasoning["effort"] && !thinking_conflicts?(session, tools)
+              type = "adaptive"
+            end
+            return nil unless type
+
+            thinking = {"type" => type}
+            thinking["budget_tokens"] = reasoning["budget_tokens"] unless reasoning["budget_tokens"].nil?
             thinking["display"] = reasoning["display"] if reasoning["display"]
-            return nil if thinking.empty? && !reasoning["type"]
 
-            thinking["type"] = reasoning["type"] || "enabled"
+            validate_thinking!(thinking)
 
-            # Unsupported reasoning.type values are silently omitted.
-            return nil unless SUPPORTED_THINKING_TYPES.include?(thinking["type"])
+            thinking
+          end
 
-            if thinking["type"] == "enabled" && !thinking.key?("budget_tokens")
+          # Whether the payload sets anything thinking is incompatible with.
+          def thinking_conflicts?(session, tools)
+            return true if session.temperature
+            return true if session.top_p && session.top_p < 0.95
+            return false if tools.empty?
+
+            forced_tool_choice?(normalize_tool_choice(session.tool_choice))
+          end
+
+          def forced_tool_choice?(choice)
+            ["any", "tool"].include?(choice&.dig("type"))
+          end
+
+          # Validate the parts of the thinking contract that follow from the
+          # payload alone. Which types and effort levels a model accepts is
+          # model-dependent and is not validated here.
+          def validate_thinking!(thinking)
+            type = thinking["type"]
+
+            if type == "enabled" && !thinking.key?("budget_tokens")
               raise UnsupportedFormatError,
-                "Messages format requires reasoning.budget_tokens when thinking is enabled"
+                "Messages format requires reasoning.budget_tokens when reasoning.type is enabled"
             end
 
-            if thinking["type"] != "enabled" && thinking.key?("budget_tokens")
+            if type != "enabled" && thinking.key?("budget_tokens")
               raise UnsupportedFormatError,
                 "Messages format only supports reasoning.budget_tokens when reasoning.type is enabled"
             end
 
-            if thinking["type"] == "disabled" && thinking.key?("display")
-              raise UnsupportedFormatError,
-                "Messages format does not support reasoning.display when reasoning.type is disabled"
-            end
+            return unless ["between_tools", "disabled"].include?(type) && thinking.key?("display")
 
-            thinking
+            raise UnsupportedFormatError,
+              "Messages format does not support reasoning.display when reasoning.type is #{type}"
           end
 
+          # Whether the request turns thinking on, which constrains sampling
+          # parameters and forced tool choice.
           def thinking_active?(thinking)
             thinking && thinking["type"] != "disabled"
           end
@@ -232,11 +298,9 @@ module PromptBuilder
           def build_output_config(session)
             output_config = {}
 
-            if session.reasoning && session.reasoning["effort"]
-              effort = session.reasoning["effort"]
-              # Unsupported effort levels are silently omitted.
-              output_config["effort"] = effort if EFFORT_LEVELS.include?(effort)
-            end
+            # Effort levels are forwarded as is; the levels a model accepts vary.
+            effort = session.reasoning["effort"] if session.reasoning
+            output_config["effort"] = effort if effort
 
             if session.text
               # Unsupported text.* keys are silently omitted; only format is mapped.
@@ -264,8 +328,6 @@ module PromptBuilder
           end
 
           def validate_thinking_compatibility!(session, thinking)
-            return unless thinking
-
             budget = thinking["budget_tokens"]
             if budget && session.max_output_tokens && session.max_output_tokens <= budget
               raise UnsupportedFormatError,
@@ -569,7 +631,7 @@ module PromptBuilder
             end
           end
 
-          def serialize_tool_choice(choice, tools:, parallel_tool_calls:, thinking_enabled:)
+          def serialize_tool_choice(choice, tools:, parallel_tool_calls:, thinking_active:)
             if choice.nil?
               return nil if parallel_tool_calls.nil?
 
@@ -591,7 +653,7 @@ module PromptBuilder
             # tool_choice cannot be expressed without tools; omit it.
             return nil if tools.empty? && normalized_choice["type"] != "none"
 
-            if thinking_enabled && ["any", "tool"].include?(normalized_choice["type"])
+            if thinking_active && forced_tool_choice?(normalized_choice)
               raise UnsupportedFormatError,
                 "Messages format does not support forced tool_choice when thinking is enabled"
             end

data/lib/prompt_builder/serializers/messages/stream_accumulator.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  module Serializers
+    class Messages < Base
+      # Reassembles an Anthropic Messages SSE stream into the message object
+      # the non-streaming endpoint would have returned.
+      #
+      # +message_start+ provides the base message. Content blocks are tracked
+      # by index: +text_delta+ and +citations_delta+ build text blocks,
+      # +thinking_delta+ and +signature_delta+ build thinking blocks, and
+      # +input_json_delta+ fragments are joined and parsed as the block's
+      # +input+ when it stops. Blocks that arrive whole in
+      # +content_block_start+ (e.g. +redacted_thinking+ and server tool
+      # results) are kept as is. +message_delta+ provides the stop reason and
+      # cumulative usage, which is merged into the +message_start+ usage.
+      #
+      # The stream must end with +message_stop+; an +error+ event raises an
+      # ErrorResponseError. +ping+ and unknown events are ignored.
+      class StreamAccumulator < Streaming::Accumulator
+        def initialize
+          super
+          @message = {}
+          @started = false
+          @blocks = {}
+          @input_json = {}
+          @stopped = false
+        end
+
+        private
+
+        def handle_event(event)
+          data = parse_json(event.data)
+          return unless data.is_a?(Hash)
+
+          case data["type"] || event.event
+          when "message_start"
+            @message = data["message"] || {}
+            @started = true
+          when "content_block_start"
+            @blocks[data["index"]] = data["content_block"] || {}
+          when "content_block_delta"
+            apply_delta(data["index"], data["delta"] || {})
+          when "content_block_stop"
+            finish_block(data["index"])
+          when "message_delta"
+            apply_message_delta(data)
+          when "message_stop"
+            @stopped = true
+          when "error"
+            error = data["error"].is_a?(Hash) ? data["error"] : {}
+            raise_error_event!([error["type"], error["message"]].compact.join(": "))
+          end
+        end
+
+        def apply_delta(index, delta)
+          case delta["type"]
+          when "text_delta"
+            block = @blocks[index] ||= {"type" => "text"}
+            append(block, "text", delta["text"])
+          when "citations_delta"
+            block = @blocks[index] ||= {"type" => "text"}
+            (block["citations"] ||= []) << delta["citation"]
+          when "thinking_delta"
+            block = @blocks[index] ||= {"type" => "thinking"}
+            append(block, "thinking", delta["thinking"])
+          when "signature_delta"
+            block = @blocks[index] ||= {"type" => "thinking"}
+            append(block, "signature", delta["signature"])
+          when "input_json_delta"
+            (@input_json[index] ||= +"") << delta["partial_json"].to_s
+          end
+        end
+
+        def append(block, key, value)
+          block[key] = block[key] ? +block[key] : +""
+          block[key] << value.to_s
+        end
+
+        def finish_block(index)
+          json = @input_json.delete(index)
+          return unless json
+
+          block = @blocks[index] ||= {}
+          block["input"] = json.empty? ? {} : parse_json(json)
+        end
+
+        def apply_message_delta(data)
+          (data["delta"] || {}).each { |key, value| @message[key] = value }
+
+          usage = data["usage"]
+          return unless usage.is_a?(Hash)
+
+          merged = (@message["usage"] || {}).dup
+          usage.each { |key, value| merged[key] = value unless value.nil? }
+          @message["usage"] = merged
+        end
+
+        def build_result
+          incomplete!("Messages stream ended without a message_stop event") unless @stopped
+          incomplete!("Messages stream ended without a message_start event") unless @started
+
+          @input_json.keys.each { |index| finish_block(index) }
+          content = @blocks.sort_by { |index, _| index.to_i }.map { |_, block| block }
+          @message.merge("content" => content)
+        end
+      end
+    end
+  end
+end

data/lib/prompt_builder/serializers/messages.rb

@@ -7,6 +7,7 @@ module PromptBuilder
     class Messages < Base
       autoload :Request, File.expand_path("messages/request", __dir__)
       autoload :Response, File.expand_path("messages/response", __dir__)
+      autoload :StreamAccumulator, File.expand_path("messages/stream_accumulator", __dir__)
 
       class << self
         # Export a session to Messages request payload.
@@ -16,14 +17,6 @@ module PromptBuilder
         def request_payload(session)
           Request.request_payload(session)
         end
-
-        # Parse a Messages response into an PromptBuilder::Response.
-        #
-        # @param hash [Hash] the response hash in Messages format
-        # @return [PromptBuilder::Response] the parsed response
-        def parse_response(hash)
-          Response.parse_response(hash)
-        end
       end
     end
   end