samagotchi 0.2.0

data/lib/samagotchi/llm/native_tool_normalizer.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../tools/execute"
+require_relative "../tools/read"
+require_relative "../tools/write"
+require_relative "../tools/memory"
+require_relative "../tools/edit"
+require_relative "../tools/task_create"
+require_relative "../tools/task_get"
+require_relative "../tools/task_list"
+require_relative "../tools/task_stop"
+require_relative "../tools/task_wait"
+require_relative "../tools/web_fetch"
+require_relative "../tools/register_reminder"
+require_relative "../tools/cancel_reminder"
+require_relative "../tools/list_reminders"
+require_relative "../tools/list_sessions"
+require_relative "../tools/send_note"
+require_relative "../tools/delegate"
+require_relative "../tools/delegate_result"
+require_relative "../tools/ask_user_question"
+
+module Samagotchi
+  module LLM
+    # Bridges a native tool call (an LLM::ToolCall from the chat adapter; any
+    # object with #name and #arguments) into samagotchi's internal tool-call shape that
+    # `KernelLoop#dispatch` consumes:
+    #
+    #   { name:, content:, path:, scope:, start_line:, end_line:, cwd:, env:, description: }
+    #
+    # The adapter hands you a *structured* `arguments` Hash (`.arguments` is a parsed
+    # Hash), while the internal `content` is a per-tool serialized text blob
+    # (e.g. `Edit` wants "<old>…</old><new>…</new>"; `Read` wants a `path`;
+    # `Execute` wants the command). Rather than re-architect every tool to accept
+    # structured args (huge blast radius), we rebuild the exact blob per tool so
+    # `dispatch` and every tool stay unchanged.
+    #
+    # Unknown tool names pass through untouched so `dispatch` renders its standard
+    # "unknown tool … available: …" error — the loop feeds that back like any tool
+    # result.
+    #
+    # This is the Phase-3 crux from Spike #4: the native→internal mapping is
+    # independent of how tools were driven in the request body.
+    class NativeToolNormalizer
+      # Map each known tool NAME to a proc(args => internal-call-hash).
+      # Each proc receives the tool call's arguments (`.arguments` is a Hash of string→value)
+      # and returns the internal dispatch shape with every expected key present
+      # (missing values are nil).
+      #
+      # Args come back as strings from the wire (e.g. "start_line" => "1"); tools
+      # that read them do `.to_s.strip`, so we leave them as-is here and let the
+      # dispatch site coerce.
+      MAP = {
+        Tools::Execute::NAME => lambda { |args|
+          {
+            name: Tools::Execute::NAME,
+            content: args["command"].to_s,
+            path: nil, scope: nil,
+            start_line: nil, end_line: nil,
+            cwd: args["cwd"], env: args["env"]
+          }
+        },
+        Tools::Read::NAME => lambda { |args|
+          {
+            name: Tools::Read::NAME,
+            content: args["path"].to_s,
+            path: nil, scope: nil,
+            start_line: args["start_line"], end_line: args["end_line"],
+            cwd: nil, env: nil, description: nil,
+            args: args.is_a?(Hash) ? args : {}
+          }
+        },
+        Tools::Write::NAME => lambda { |args|
+          {
+            name: Tools::Write::NAME,
+            content: args["content"] || args["text"],
+            path: args["path"], scope: nil,
+            start_line: nil, end_line: nil,
+            cwd: nil, env: nil, description: nil
+          }
+        },
+        Tools::MemoryRead::NAME => lambda { |args|
+          {
+            name: Tools::MemoryRead::NAME,
+            content: args["name"].to_s,
+            path: nil, scope: args["scope"],
+            start_line: nil, end_line: nil,
+            cwd: nil, env: nil, description: nil
+          }
+        },
+        Tools::MemoryWrite::NAME => lambda { |args|
+          {
+            name: Tools::MemoryWrite::NAME,
+            content: args["content"] || args["text"] || args["body"],
+            path: args["name"], scope: args["scope"],
+            description: args["description"],
+            current_model_only: args["current_model_only"],
+            start_line: nil, end_line: nil,
+            cwd: nil, env: nil
+          }
+        },
+        Tools::Edit::NAME => lambda { |args|
+          old_text = args["old_text"] || args["old"]
+          new_text = args["new_text"] || args["new"]
+          {
+            name: Tools::Edit::NAME,
+            content: "<old>#{old_text}</old><new>#{new_text}</new>",
+            path: args["path"],
+            start_line: args["start_line"], end_line: args["end_line"],
+            scope: nil, cwd: nil, env: nil, description: nil
+          }
+        },
+        Tools::TaskCreate::NAME => lambda { |args|
+          {
+            name: Tools::TaskCreate::NAME,
+            content: args["command"].to_s,
+            path: nil, scope: nil,
+            start_line: nil, end_line: nil,
+            cwd: args["cwd"], env: args["env"], description: nil
+          }
+        },
+        Tools::TaskGet::NAME => lambda { |args|
+          {
+            name: Tools::TaskGet::NAME,
+            content: (args["id"] || args["task_id"]).to_s,
+            path: nil, scope: nil,
+            start_line: nil, end_line: nil,
+            cwd: nil, env: nil, description: nil
+          }
+        },
+        Tools::TaskStop::NAME => lambda { |args|
+          {
+            name: Tools::TaskStop::NAME,
+            content: (args["id"] || args["task_id"]).to_s,
+            path: nil, scope: nil,
+            start_line: nil, end_line: nil,
+            cwd: nil, env: nil, description: nil
+          }
+        },
+        Tools::TaskWait::NAME => lambda { |args|
+          {
+            name: Tools::TaskWait::NAME,
+            content: (args["id"] || args["task_id"]).to_s,
+            path: nil, scope: nil,
+            start_line: nil, end_line: nil,
+            cwd: nil, env: nil,
+            timeout: args["timeout"], tail_lines: args["tail_lines"], done_pattern: args["done_pattern"],
+            description: nil
+          }
+        },
+        Tools::TaskList::NAME => lambda { |_args|
+          {
+            name: Tools::TaskList::NAME,
+            content: "", path: nil, scope: nil,
+            start_line: nil, end_line: nil,
+            cwd: nil, env: nil, description: nil
+          }
+        },
+        Tools::WebFetch::NAME => lambda { |args|
+          {
+            name: Tools::WebFetch::NAME,
+            content: args["url"].to_s,
+            path: nil, scope: nil,
+            start_line: nil, end_line: nil,
+            cwd: nil, env: nil, description: nil
+          }
+        },
+        Tools::RegisterReminder::NAME => lambda { |args|
+          {
+            name: Tools::RegisterReminder::NAME,
+            content: args["name"].to_s,
+            path: nil, scope: nil,
+            description: args["description"],
+            interval_minutes: args["interval_minutes"]
+          }
+        },
+        Tools::CancelReminder::NAME => lambda { |args|
+          { name: Tools::CancelReminder::NAME, content: args["name"].to_s, path: nil, scope: nil }
+        },
+        Tools::ListReminders::NAME => lambda { |_args|
+          { name: Tools::ListReminders::NAME, content: "", path: nil, scope: nil }
+        },
+        Tools::ListSessions::NAME => lambda { |args|
+          { name: Tools::ListSessions::NAME, content: "", path: nil, scope: nil, cwd: args["cwd"] }
+        },
+        Tools::SendNote::NAME => lambda { |args|
+          { name: Tools::SendNote::NAME, content: args["text"].to_s, path: nil, scope: nil, session: args["session"].to_s }
+        },
+        Tools::Delegate::NAME => lambda { |args|
+          { name: Tools::Delegate::NAME, content: args["task"].to_s, path: nil, scope: nil,
+            model: args["model"], session: args["session"], wait: args["wait"], timeout: args["timeout"] }
+        },
+        Tools::DelegateResult::NAME => lambda { |args|
+          { name: Tools::DelegateResult::NAME, content: "", path: nil, scope: nil,
+            session: args["session"], timeout: args["timeout"] }
+        },
+        Tools::AskUserQuestion::NAME => lambda { |args|
+          raw_opts = args["options"]
+          norm_opts = Samagotchi::Tools::AskUserQuestion.normalize_options_lenient(raw_opts)
+          norm_opts = raw_opts if norm_opts.empty? && raw_opts.is_a?(Array)
+          {
+            name: Tools::AskUserQuestion::NAME,
+            content: args["question"].to_s,
+            path: nil, scope: nil,
+            question: args["question"].to_s,
+            options: norm_opts.empty? ? raw_opts : norm_opts,
+            header: args["header"],
+            multi_select: args["multi_select"],
+            allow_freeform: args["allow_freeform"]
+          }
+        }
+      }.freeze
+
+      class << self
+        # Map a single native tool call (LLM::ToolCall) to the internal call hash.
+        #
+        # `call.arguments` is a parsed Hash (string keys). If it is nil or a bare
+        # string we defensively coerce (string → JSON.parse when possible) so the
+        # mapping never explodes on an odd wire shape.
+        def normalize(call)
+          return nil if call.nil?
+
+          name = call.name.to_s
+          args = args_for(call)
+          proc = MAP[name]
+          return passthrough(name, args) unless proc
+
+          proc.call(args).merge(name: name)
+        end
+
+        # Map an Array of tool calls to internal call hashes (nils dropped).
+        def normalize_all(calls)
+          Array(calls).map { |call| normalize(call) }.compact
+        end
+
+        private
+
+        # args_for: arguments is normally a Hash. Defensively handle nil /
+        # JSON-string / other shapes without raising.
+        def args_for(call)
+          raw = call.respond_to?(:arguments) ? call.arguments : nil
+          case raw
+          when Hash then raw
+          when String
+            raw.strip.empty? ? {} : safe_json_parse(raw)
+          when nil
+            {}
+          else
+            { "__raw__" => raw.to_s }
+          end
+        end
+
+        def safe_json_parse(str)
+          JSON.parse(str)
+        rescue JSON::ParserError
+          { "__raw__" => str }
+        end
+
+        # A registry (plugin) tool, or an unknown one: the arguments as args:
+        # (typed by the schema at dispatch), plus enough for `dispatch` to
+        # render the standard "unknown tool" error. `content` is the joined
+        # argument values (harmless; the unknown-tool branch ignores it).
+        def passthrough(name, args)
+          {
+            name: name,
+            content: args.is_a?(Hash) ? args.values.join(" ") : name,
+            path: nil, scope: nil,
+            start_line: nil, end_line: nil,
+            cwd: nil, env: nil, description: nil,
+            args: args.is_a?(Hash) ? args : {}
+          }
+        end
+      end
+    end
+  end
+end

data/lib/samagotchi/llm/openai_chat.rb

@@ -0,0 +1,403 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+require_relative "../config"
+require_relative "errors"
+require_relative "http"
+require_relative "usage"
+
+module Samagotchi
+  module LLM
+    # A model a host lists. Unknown fields are nil.
+    ModelInfo = Data.define(:id, :context_window, :supports_tools, :raw) do
+      # true when the list says the model takes images (OpenRouter's
+      # architecture.input_modalities, llama.cpp's "multimodal" capability),
+      # false when it lists input modalities without "image", else nil.
+      def image_input
+        return nil unless raw.is_a?(Hash)
+
+        modalities = raw.dig("architecture", "input_modalities")
+        return modalities.include?("image") if modalities.is_a?(Array)
+        return true if Array(raw["capabilities"]).include?("multimodal")
+
+        nil
+      end
+    end
+
+    # A tool call the model made. arguments: the parsed Hash, or the raw
+    # String when it isn't valid JSON (the tool then reports the error).
+    ToolCall = Data.define(:id, :name, :arguments)
+
+    # One chat completion: text and reasoning ("" when none), tool calls
+    # ([] when none), usage (never nil) and the finish reason.
+    # +model+ is the model the server says answered (the body's `model`),
+    # which can differ from the one asked for; nil when it says nothing.
+    ChatResponse = Data.define(:text, :reasoning, :tool_calls, :usage, :finish_reason, :model) do
+      def initialize(model: nil, **fields) = super
+    end
+
+    # The OpenAI Chat Completions API (llama.cpp's /v1, and any compatible
+    # provider) on our own HTTP layer: one request per #chat, streamed by
+    # default, with errors mapped to ProviderError. It speaks the wire format
+    # only; the chat loop owns the conversation and the tools.
+    class OpenAIChat
+      MAX_MODEL_PAGES = 20
+      DEFAULT_MODELS_TTL = 60
+
+      attr_reader :base_url, :host_name, :api_key_env, :models_ttl, :first_token_timeout
+
+      # @param entry [HostRegistry::HostEntry]
+      def self.for(entry, **options)
+        new(base_url: entry.openai_base_url, host_name: entry.name, api_key_env: entry.api_key_env,
+            remote: entry.respond_to?(:remote?) && entry.remote?, **options)
+      end
+
+      # Tool arguments as a Hash; "" is {}, invalid JSON stays a String.
+      def self.parse_arguments(raw)
+        return raw if raw.is_a?(Hash)
+
+        text = raw.to_s
+        return {} if text.strip.empty?
+
+        parsed = JSON.parse(text)
+        parsed.is_a?(Hash) ? parsed : text
+      rescue JSON::ParserError
+        text
+      end
+
+      # @param base_url [String] the API base, e.g. http://host:8081/v1
+      # @param host_name [String] names the host in errors
+      # @param api_key_env [String, nil] the variable holding the API key;
+      #   nil sends no Authorization header (a local server)
+      # @param stream [Boolean] stream the reply (false: one JSON body)
+      # @param retries [Boolean] false: one attempt
+      # @param timeout [Numeric, nil] read timeout in seconds (default
+      #   server.read_timeout); the connect timeout is capped by it
+      # @param models_ttl [Numeric] how long #context_window reuses the list
+      # @param remote [Boolean] a provider on the network, not a local server
+      # @param first_token_timeout [Numeric, nil] seconds a streamed answer
+      #   may take to show something (LLM::HTTP); nil: no limit
+      def initialize(base_url:, host_name:, api_key_env: nil, stream: true, retries: true, timeout: nil,
+                     env: ENV, sleeper: nil, retry_policy: nil, models_ttl: DEFAULT_MODELS_TTL, remote: false,
+                     first_token_timeout: nil, purpose: "chat")
+        @remote = remote
+        # What its requests are for, in the log (LLM::HTTP::LOGGED_PURPOSES).
+        @purpose = purpose
+        @first_token_timeout = first_token_timeout
+        @base_url = base_url.to_s.chomp("/")
+        @host_name = host_name.to_s
+        @api_key_env = api_key_env
+        @stream = stream
+        @env = env
+        @models_ttl = models_ttl
+        @models_mutex = Mutex.new
+        open_timeout, read_timeout = timeouts(timeout)
+        policy = retry_policy || (retries ? nil : HTTP::RetryPolicy.none)
+        @http = HTTP.new(label: @host_name, open_timeout: open_timeout, read_timeout: read_timeout,
+                         retry_policy: policy, sleeper: sleeper, first_token_timeout: first_token_timeout)
+      end
+
+      # @param messages [Array<Hash>] wire messages (role, content, tool_calls,
+      #   tool_call_id); content is a String or an Array of parts
+      # @param tools [Array<Hash>] function definitions ({type:, function:})
+      # @param options [Hash] extra request fields (max_tokens, ...)
+      # @param on_delta [Proc, nil] called per streamed chunk with content:,
+      #   reasoning: and payload: (the parsed chunk)
+      # @param on_retry [Proc, nil] see LLM::HTTP#stream_lines
+      # @param session_id [String, nil] sent as a Session-Id header so a
+      #   gateway that spreads requests over providers keeps one
+      #   conversation on one of them (prompt caches, one served model)
+      # @return [ChatResponse]
+      def chat(messages:, model:, tools: [], cancel_controller: nil, on_delta: nil, on_retry: nil, options: {},
+               session_id: nil)
+        request = post_request("#{@base_url}/chat/completions", request_body(messages, tools, model, options),
+                               session_id: session_id)
+        log_fields = { model: model, purpose: @purpose }
+        return chat_once(request, cancel_controller, log_fields) unless @stream
+
+        assembly = Assembly.new
+        events = 0
+        other = +""
+        # A retry streams the answer from the start again.
+        restart = lambda do |**event|
+          assembly = Assembly.new
+          on_retry&.call(**event)
+        end
+        @http.stream_lines(URI(request.uri.to_s), request, cancel_controller: cancel_controller, on_retry: restart,
+                                                           log_fields: log_fields) do |line, shown|
+          events += 1 if line.start_with?("data:")
+          other << line[0, 200] if !line.start_with?("data:") && other.length < 200
+          payload = parse_line(line)
+          next unless payload
+
+          content, reasoning = assembly.add(payload)
+          shown.call if !content.empty? || !reasoning.empty? || Assembly.tool_call_delta?(payload)
+          on_delta&.call(content: content, reasoning: reasoning, payload: payload)
+        end
+        # A server that ignores stream: true, or answers with something else
+        # entirely, would otherwise end the turn with no answer and no error.
+        raise ProtocolError.new("#{@host_name}: the response had no stream events: #{other}", host: @host_name) if events.zero?
+
+        assembly.response
+      end
+
+      # A provider on the network: no llama.cpp /props to ask for the window.
+      def remote? = @remote
+
+      # @return [Array<ModelInfo>] the host's models (every page)
+      def list_models
+        models = []
+        after = nil
+        MAX_MODEL_PAGES.times do
+          uri = URI("#{@base_url}/models#{after ? "?after=#{URI.encode_www_form_component(after)}" : ""}")
+          body = parse_json(@http.fetch(uri, get_request(uri), log_fields: { purpose: "models" }).body, "model list")
+          models.concat(model_entries(body).map { |raw| model_info(raw) })
+          break unless body.is_a?(Hash) && body["has_more"] && body["last_id"]
+
+          after = body["last_id"].to_s
+        end
+        models
+      end
+
+      # The window (tokens) the host lists for +model+, or nil. The list is
+      # read once per models_ttl; a failed listing answers nil.
+      def context_window(model:)
+        info = cached_models.find { |m| m.id == model.to_s } ||
+               cached_models.find { |m| m.id.casecmp?(model.to_s) }
+        info&.context_window
+      rescue StandardError
+        nil
+      end
+
+      # Whether the host's list says +model+ takes images (ModelInfo#image_input),
+      # or nil when it doesn't say or the listing fails.
+      def image_input(model:)
+        info = cached_models.find { |m| m.id == model.to_s } ||
+               cached_models.find { |m| m.id.casecmp?(model.to_s) }
+        info&.image_input
+      rescue StandardError
+        nil
+      end
+
+      private
+
+      def timeouts(timeout)
+        open_timeout = config_integer("server.open_timeout", 10)
+        read_timeout = config_integer("server.read_timeout", 600)
+        return [open_timeout, read_timeout] unless timeout
+
+        [[open_timeout, timeout].min, timeout]
+      end
+
+      def config_integer(key, default)
+        value = Samagotchi::Config.get(key).to_i
+        value.positive? ? value : default
+      rescue StandardError
+        default
+      end
+
+      def request_body(messages, tools, model, options)
+        body = {
+          model: model,
+          messages: Array(messages).map { |message| wire_message(message) },
+          temperature: 0.0,
+          stream: @stream
+        }
+        body[:stream_options] = { include_usage: true } if @stream
+        unless Array(tools).empty?
+          body[:tools] = tools
+          body[:tool_choice] = "auto"
+        end
+        body.merge(options || {})
+      end
+
+      # A String stays a String; an Array of parts passes as given.
+      def wire_message(message)
+        wire = message.to_h.transform_keys(&:to_sym)
+        wire[:content] = format_content(wire[:content]) if wire.key?(:content)
+        wire
+      end
+
+      def format_content(content)
+        return content if content.is_a?(Array) || content.nil?
+
+        scrub(content.to_s)
+      end
+
+      # Invalid UTF-8 (a tool's garbled output) would make to_json raise.
+      def scrub(text)
+        text.encoding == Encoding::UTF_8 && !text.valid_encoding? ? text.scrub("?") : text
+      end
+
+      def chat_once(request, cancel_controller, log_fields)
+        response = @http.fetch(URI(request.uri.to_s), request, cancel_controller: cancel_controller, log_fields: log_fields)
+        body = parse_json(response.body, "chat response")
+        message = body.is_a?(Hash) ? body.dig("choices", 0, "message") : nil
+        raise ProtocolError.new("#{@host_name}: no message in the chat response", host: @host_name) unless message.is_a?(Hash)
+
+        calls = Array(message["tool_calls"]).map do |call|
+          function = call["function"] || {}
+          ToolCall.new(id: call["id"], name: function["name"].to_s, arguments: self.class.parse_arguments(function["arguments"]))
+        end
+        ChatResponse.new(text: message["content"].to_s,
+                         reasoning: (message["reasoning_content"] || message["reasoning"]).to_s,
+                         tool_calls: calls, usage: Usage.from_payload(body) || Usage.none,
+                         finish_reason: body.dig("choices", 0, "finish_reason"), model: served_model(body))
+      end
+
+      def self.served_model(payload)
+        model = payload.is_a?(Hash) ? payload["model"] : nil
+        model.is_a?(String) && !model.strip.empty? ? model : nil
+      end
+
+      def served_model(payload) = self.class.served_model(payload)
+
+      # The parsed payload of a `data:` line; nil for blank lines, comments
+      # and [DONE]. Error events raise their ProviderError.
+      def parse_line(line)
+        error = HTTP.sse_error(line, host: @host_name)
+        raise error if error
+        return nil unless line.start_with?("data:")
+
+        data = line.delete_prefix("data:").strip
+        return nil if data.empty? || data == "[DONE]"
+
+        payload = parse_json(data, "stream chunk")
+        payload.is_a?(Hash) ? payload : nil
+      end
+
+      def parse_json(text, what)
+        JSON.parse(text.to_s)
+      rescue JSON::ParserError => e
+        raise ProtocolError.new("#{@host_name}: malformed #{what}: #{e.message[0, 200]}", host: @host_name)
+      end
+
+      def post_request(url, body, session_id: nil)
+        uri = URI(url)
+        Net::HTTP::Post.new(uri).tap do |request|
+          request["Content-Type"] = "application/json"
+          request["Session-Id"] = session_id.to_s unless session_id.to_s.empty?
+          authorize(request)
+          request.body = JSON.generate(body)
+        end
+      end
+
+      def get_request(uri)
+        Net::HTTP::Get.new(uri).tap { |request| authorize(request) }
+      end
+
+      def authorize(request)
+        return unless @api_key_env
+
+        key = @env[@api_key_env].to_s
+        if key.strip.empty?
+          raise AuthError.new("#{@host_name}: set #{@api_key_env} (the API key for host #{@host_name})",
+                              host: @host_name)
+        end
+        request["Authorization"] = "Bearer #{key}"
+      end
+
+      def model_entries(body)
+        return [] unless body.is_a?(Hash)
+
+        entries = body["data"].is_a?(Array) ? body["data"] : body["models"]
+        Array(entries).select { |entry| entry.is_a?(Hash) }
+      end
+
+      def model_info(raw)
+        id = (raw["id"] || raw["model"] || raw["name"]).to_s
+        ModelInfo.new(id: id, context_window: window_of(raw), supports_tools: tools_support(raw), raw: raw)
+      end
+
+      # The running window when the list says: context_length, context_window,
+      # max_model_len, or llama.cpp's meta.n_ctx (not n_ctx_train).
+      def window_of(raw)
+        [raw["context_length"], raw["context_window"], raw["max_model_len"], raw.dig("meta", "n_ctx")].each do |value|
+          return value if value.is_a?(Integer) && value.positive?
+        end
+        nil
+      end
+
+      def tools_support(raw)
+        listed = raw["supported_parameters"] || raw["capabilities"]
+        return nil unless listed.is_a?(Array)
+
+        listed.include?("tools") ? true : nil
+      end
+
+      def cached_models
+        @models_mutex.synchronize do
+          fresh = @models_at && (monotonic - @models_at) < @models_ttl
+          return @models if fresh
+        end
+        models = list_models
+        @models_mutex.synchronize do
+          @models = models
+          @models_at = monotonic
+        end
+        models
+      end
+
+      def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      # Streamed deltas put together: text, reasoning, tool calls by index,
+      # the finish reason, the usage chunk and the served model.
+      class Assembly
+        # The chunk carries part of a tool call.
+        def self.tool_call_delta?(payload)
+          choice = payload["choices"].is_a?(Array) ? payload["choices"].first : nil
+          choice.is_a?(Hash) && choice["delta"].is_a?(Hash) && !Array(choice["delta"]["tool_calls"]).empty?
+        end
+
+        def initialize
+          @text = +""
+          @reasoning = +""
+          @calls = {}
+          @finish_reason = nil
+          @usage = nil
+          @model = nil
+        end
+
+        # @return [Array(String, String)] this chunk's content and reasoning
+        def add(payload)
+          @usage = Usage.from_payload(payload) || @usage if payload.key?("usage")
+          @model = OpenAIChat.served_model(payload) || @model
+          choice = payload["choices"].is_a?(Array) ? payload["choices"].first : nil
+          return ["", ""] unless choice.is_a?(Hash)
+
+          @finish_reason = choice["finish_reason"] if choice["finish_reason"]
+          delta = choice["delta"].is_a?(Hash) ? choice["delta"] : {}
+          content = delta["content"].to_s
+          reasoning = (delta["reasoning_content"] || delta["reasoning"]).to_s
+          @text << content
+          @reasoning << reasoning
+          Array(delta["tool_calls"]).each { |call| add_call(call) }
+          [content, reasoning]
+        end
+
+        def response
+          calls = @calls.sort_by { |index, _| index }.map do |_, call|
+            ToolCall.new(id: call[:id], name: call[:name].to_s, arguments: OpenAIChat.parse_arguments(call[:arguments]))
+          end
+          ChatResponse.new(text: @text, reasoning: @reasoning, tool_calls: calls, usage: @usage || Usage.none,
+                           finish_reason: @finish_reason, model: @model)
+        end
+
+        private
+
+        def add_call(delta)
+          return unless delta.is_a?(Hash)
+
+          index = delta["index"].is_a?(Integer) ? delta["index"] : @calls.size
+          call = (@calls[index] ||= { id: nil, name: nil, arguments: +"" })
+          call[:id] ||= delta["id"]
+          function = delta["function"].is_a?(Hash) ? delta["function"] : {}
+          call[:name] ||= function["name"] unless function["name"].to_s.empty?
+          call[:arguments] << function["arguments"].to_s
+        end
+      end
+      private_constant :Assembly
+    end
+  end
+end