samagotchi 0.64.0 → 0.66.0

data/lib/samagotchi/llm/anthropic_messages.rb

@@ -0,0 +1,416 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+require_relative "../config"
+require_relative "../sampling_settings"
+require_relative "../thinking"
+require_relative "errors"
+require_relative "http"
+require_relative "model_listing"
+require_relative "openai_chat"
+require_relative "prompt_cache"
+require_relative "anthropic_assembly"
+require_relative "anthropic_wire"
+require_relative "dialect"
+
+module Samagotchi
+  module LLM
+    # Anthropic's Messages API (`POST {base}/v1/messages`: Anthropic's own,
+    # a gateway, or a local server such as Splash) on our own HTTP layer, for
+    # the same chat loop as OpenAIChat: ChatLoop's OpenAI-shaped wire
+    # messages are translated here (AnthropicWire), and the answer comes back
+    # as a ChatResponse whose provider_content holds the content blocks to
+    # send back verbatim (#replays_content?).
+    #
+    # A host's dialect (LLM::Dialect, `dialect:`) overrides parts of the
+    # standard wire: its default auth header, the thinking `display`, the
+    # cache breakpoints and a session-affinity header.
+    #
+    # Nothing here keys on a model id: fields are sent explicitly, read
+    # leniently, and a host's 400 for a field it refuses is what changes a
+    # request. Those 400s are handled here, once per request, and
+    # remembered for the adapter's life (a host's worker), so ChatLoop's
+    # broader refusal paths never see them:
+    # - adaptive thinking (or output_config.effort) refused: the model gets
+    #   the budget form instead (#budget_form), per model;
+    # - thinking.display refused (a provider whose thinking schema has no
+    #   such field, e.g. Fireworks without its dialect): no display for the
+    #   host, the thinking itself kept;
+    # - cache_control refused (Fireworks lists it unsupported): no
+    #   breakpoints for the host;
+    # - max_tokens over the model's output limit: the limit the message
+    #   names, per model.
+    class AnthropicMessages
+      include ModelListing
+
+      API_VERSION = "2023-06-01"
+      DEFAULT_MODELS_TTL = 60
+      MAX_MODEL_PAGES = 20
+      # The budget form's budget_tokens per level (a model that takes no
+      # adaptive thinking), and Messages' smallest budget.
+      BUDGETS = { low: 2048, medium: 8192, high: 24_576 }.freeze
+      MIN_BUDGET = 1024
+      # A 400 refusing adaptive thinking or its effort.
+      ADAPTIVE_REFUSED_RE = /adaptive|output_config|effort/i
+      CACHE_CONTROL_RE = /cache_control/i
+      # A 400 refusing the thinking display field: its path (pydantic:
+      # "thinking.adaptive.display"), or the field named as unknown or not
+      # permitted. Not an error that only echoes the input
+      # (input_value={'type': 'adaptive', 'display': ...}).
+      DISPLAY_RE = /thinking\.[\w.]*\bdisplay\b|
+                    (?:unknown|unexpected|unrecognized|extra|invalid)\s+(?:field|parameter|key|input)s?\W{0,4}display\b|
+                    \bdisplay\W{0,4}(?:extra\s+inputs\s+are\s+not\s+permitted|is\s+not\s+(?:permitted|allowed|supported))/xi
+      # "max_tokens: 200000 > 128000, which is the maximum allowed number of output tokens for …"
+      OUTPUT_CAP_RE = /max_tokens`?:?\s*\d+\s*>\s*(\d+)/i
+      # How much of a 200's non-stream body is read as a possible JSON error.
+      PLAIN_ERROR_LIMIT = 64 * 1024
+      # max_tokens when default.max_tokens is unset and the model list names
+      # none (a listed one is capped by it too).
+      DEFAULT_MAX_TOKENS = 64_000
+      # chi's OpenAI-only request fields: never sent to a Messages host
+      # (configured sampling passes as written).
+      DROPPED_OPTIONS = %i[reasoning_effort chat_template_kwargs stream_options prompt_cache_key logprobs top_logprobs
+                           max_completion_tokens].freeze
+
+      attr_reader :base_url, :host_name, :api_key_env, :models_ttl, :first_token_timeout, :dialect
+
+      # @param entry [HostRegistry::HostEntry]
+      def self.for(entry, **)
+        new(base_url: entry.api_base_url, host_name: entry.name, api_key_env: entry.api_key_env, auth: entry.auth,
+            dialect: entry.dialect, remote: entry.remote?, **)
+      end
+
+      # @param base_url [String] the API root without /v1 (HostEntry#api_base_url)
+      # @param auth [Symbol, nil] the header the key goes in (ApiKey::SCHEMES);
+      #   nil: the dialect's (x-api-key on the standard one)
+      # @param dialect [String, nil] the host's dialect: name (Dialect.for)
+      # The rest as OpenAIChat#initialize takes them.
+      def initialize(base_url:, host_name:, api_key_env: nil, auth: nil, dialect: 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", open_timeout: nil)
+        @dialect = Dialect.for(dialect)
+        @remote = remote
+        @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
+        init_model_listing(models_ttl)
+        @thinking_form_refused = Set.new
+        @output_caps = {}
+        @cache_control_refused = false
+        @thinking_display_refused = false
+        open_timeout, read_timeout = timeouts(timeout, open_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,
+                         api_key: ApiKey.for(api_key_env, host: @host_name, env: env, scheme: auth || @dialect.auth))
+      end
+
+      # The same contract as OpenAIChat#chat; +messages+ are ChatLoop's
+      # OpenAI-shaped wire messages.
+      # @return [ChatResponse]
+      def chat(messages:, model:, tools: [], cancel_controller: nil, on_delta: nil, on_retry: nil, options: {},
+               session_id: nil)
+        fixed = []
+        begin
+          body = request_body(messages, tools, model, options)
+          request = post_request("#{@base_url}/v1/messages", body, session_id: session_id)
+          log_fields = { model: model, purpose: @purpose, sampling: sampling_summary(body), cache: cache_summary(body) }
+          return chat_once(request, cancel_controller, log_fields) unless @stream
+
+          chat_streamed(request, cancel_controller, on_delta, on_retry, log_fields)
+        rescue BadRequest => e
+          fix = refusal_fix(e, body, model)
+          raise if fix.nil? || fixed.include?(fix)
+
+          fixed << fix
+          retry
+        end
+      end
+
+      # A provider on the network: no llama.cpp /props to ask for the window.
+      def remote? = @remote
+
+      # The response's blocks go back verbatim (ChatLoop#wire_messages
+      # copies a model entry's anthropic_content onto its wire message).
+      def replays_content? = true
+
+      # true when a streamed event (as #chat's on_delta gets it) carries
+      # part of a tool call.
+      def tool_call_delta?(payload) = AnthropicAssembly.tool_call_delta?(payload)
+
+      # The request fields a thinking +level+ (Thinking::LEVELS) adds on this
+      # wire: default nothing (the provider's own default), off
+      # `thinking: disabled`, low/medium/high adaptive thinking at that
+      # effort, shown the dialect's way (summarized; no display field on a
+      # dialect that has none).
+      # @return [Hash] frozen
+      def thinking_fields(level)
+        case level
+        when :off then { thinking: { type: "disabled" }.freeze }.freeze
+        when *Thinking::EFFORTS
+          thinking = { type: "adaptive", display: @dialect.thinking_display }.compact.freeze
+          { thinking: thinking, output_config: { effort: level.to_s }.freeze }.freeze
+        else {}.freeze
+        end
+      end
+
+      # The thinking fields for a short side answer (a recap, ctx.ask_model,
+      # a triage) from a model that refused thinking off: an always-thinking
+      # model can't skip it, so it thinks at low effort (IdleClient leaves
+      # room for the answer).
+      # @return [Hash] frozen
+      def thinking_off_refused_fields = thinking_fields(:low)
+
+      # The host's models, every page: GET {base}/v1/models with
+      # limit=1000 and after_id paging (has_more/last_id). Anthropic's shape
+      # (max_input_tokens, max_tokens, capabilities) and the OpenAI shape a
+      # gateway or Splash serves here are both read (ModelListing).
+      # Whether +model+ gets the budget form (it refused adaptive thinking).
+      def budget_form?(model) = @thinking_form_refused.include?(model.to_s)
+
+      # @return [Array<ModelInfo>]
+      def list_models
+        models = []
+        after = nil
+        MAX_MODEL_PAGES.times do
+          query = URI.encode_www_form({ limit: 1000, after_id: after }.compact)
+          uri = URI("#{@base_url}/v1/models?#{query}")
+          body = parse_json(@http.fetch(uri, Net::HTTP::Get.new(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
+
+      private
+
+      # Anthropic lists the window as max_input_tokens; else the fields an
+      # OpenAI-shaped list carries.
+      def window_of(raw)
+        window = raw["max_input_tokens"]
+        window.is_a?(Integer) && window.positive? ? window : super
+      end
+
+      def timeouts(timeout, open_limit = nil)
+        open_timeout = Samagotchi::Config.positive_seconds("server.open_timeout")
+        read_timeout = Samagotchi::Config.positive_seconds("server.read_timeout")
+        open_timeout = [open_timeout, open_limit].min if open_limit
+        return [open_timeout, read_timeout] unless timeout
+
+        [[open_timeout, timeout].min, timeout]
+      end
+
+      # The Messages body: model, max_tokens, the system blocks, the
+      # messages, the stream flag, the tools (tool_choice auto with them),
+      # then the options as Messages takes them (chi's OpenAI-only fields
+      # dropped; a null drops a field).
+      def request_body(messages, tools, model, options)
+        options = (options || {}).to_h.transform_keys(&:to_sym).except(*DROPPED_OPTIONS)
+        options = budget_form(options) if budget_form?(model)
+        options = without_display(options) if @thinking_display_refused
+        cache = PromptCache.control if @purpose == "chat" && @dialect.cache_breakpoints && !@cache_control_refused
+        translated = AnthropicWire.translate(messages, cache: cache)
+        max_tokens = options.delete(:max_tokens) || default_max_tokens(model)
+        max_tokens = [max_tokens, @output_caps[model.to_s]].min if @output_caps[model.to_s]
+        body = { model: model, max_tokens: max_tokens }
+        body[:system] = translated.system unless translated.system.empty?
+        body[:messages] = translated.messages
+        body[:stream] = @stream
+        unless Array(tools).empty?
+          body[:tools] = AnthropicWire.tools(tools)
+          body[:tool_choice] = { type: "auto" }
+        end
+        with_budget_room(body.merge(options).compact)
+      end
+
+      # Adaptive thinking at a level as the budget form: thinking enabled
+      # with BUDGETS' budget (medium without an effort), shown as asked (no
+      # display when it asked none), and no effort (a model without
+      # adaptive thinking may take none).
+      def budget_form(options)
+        thinking = options[:thinking].is_a?(Hash) ? options[:thinking].transform_keys(&:to_sym) : nil
+        return options unless thinking && thinking[:type].to_s == "adaptive"
+
+        config = options[:output_config].is_a?(Hash) ? options[:output_config].transform_keys(&:to_sym) : {}
+        budget = BUDGETS.fetch(config[:effort].to_s.to_sym, BUDGETS[:medium])
+        config = config.except(:effort)
+        options.merge(thinking: { type: "enabled", budget_tokens: budget, display: thinking[:display] }.compact,
+                      output_config: config.empty? ? nil : config)
+      end
+
+      # +options+ with no thinking.display (the host refused the field).
+      def without_display(options)
+        thinking = options[:thinking]
+        return options unless thinking.is_a?(Hash)
+
+        options.merge(thinking: thinking.transform_keys(&:to_sym).except(:display))
+      end
+
+      # Messages wants max_tokens > budget_tokens (and a budget of at least
+      # MIN_BUDGET): a budget without that room is lowered to leave
+      # MIN_BUDGET for the answer; below MIN_BUDGET itself, max_tokens is
+      # raised to 2 * MIN_BUDGET with the smallest budget.
+      def with_budget_room(body)
+        thinking = body[:thinking]
+        return body unless thinking.is_a?(Hash) && thinking[:budget_tokens].is_a?(Integer)
+
+        budget = thinking[:budget_tokens]
+        max_tokens = body[:max_tokens].to_i
+        return body if max_tokens > budget + MIN_BUDGET
+
+        budget = max_tokens - MIN_BUDGET
+        if budget < MIN_BUDGET
+          budget = MIN_BUDGET
+          max_tokens = 2 * MIN_BUDGET
+        end
+        body.merge(max_tokens: max_tokens, thinking: thinking.merge(budget_tokens: budget))
+      end
+
+      # What a 400 for +body+ changes (remembered), or nil: the error goes
+      # on as it is.
+      def refusal_fix(error, body, model)
+        return nil if error.context_overflow? || error.status != 400 || body.nil?
+        # Those are the loop's (a sampling field) or P3's (signatures,
+        # binding controls): a mention of "effort" in them is no form refusal.
+        return nil if error.sampling_refused? || error.thinking_signature? || error.thinking_binding_unsupported?
+
+        detail = error.detail.to_s
+        # Before the adaptive check: the refused field's path
+        # ("thinking.adaptive.display") names adaptive too.
+        if !@thinking_display_refused && body[:thinking].is_a?(Hash) && body[:thinking].key?(:display) &&
+           DISPLAY_RE.match?(detail)
+          @thinking_display_refused = true
+          Log.info(:http, "thinking_display_refused", host: @host_name, detail: detail[0, 200])
+          :thinking_display
+        elsif body.dig(:thinking, :type) == "adaptive" && ADAPTIVE_REFUSED_RE.match?(detail)
+          @thinking_form_refused << model.to_s
+          Log.info(:http, "thinking_form_switched", host: @host_name, model: model.to_s, to: "budget", detail: detail[0, 200])
+          :thinking_form
+        elsif !@cache_control_refused && CACHE_CONTROL_RE.match?(detail) && cache_summary(body)
+          @cache_control_refused = true
+          Log.info(:http, "cache_control_refused", host: @host_name, detail: detail[0, 200])
+          :cache_control
+        elsif (cap = detail[OUTPUT_CAP_RE, 1]&.to_i) && cap.positive? && body[:max_tokens].to_i > cap
+          @output_caps[model.to_s] = cap
+          Log.info(:http, "output_cap", host: @host_name, model: model.to_s, max_tokens: cap)
+          :max_tokens
+        end
+      end
+
+      # The model list's max_tokens for +model+ (capped), else the cap.
+      def default_max_tokens(model)
+        listed = listed_model(model)&.raw&.dig("max_tokens")
+        listed.is_a?(Integer) && listed.positive? ? [listed, DEFAULT_MAX_TOKENS].min : DEFAULT_MAX_TOKENS
+      rescue StandardError
+        DEFAULT_MAX_TOKENS
+      end
+
+      # The log line's cache= : on for breakpoints with the default TTL, 1h
+      # for cache.ttl 1h, nil for none.
+      def cache_summary(body)
+        controls = [*Array(body[:system]), *Array(body[:messages]).flat_map { |m| Array(m[:content]) }]
+                   .filter_map { |block| block.is_a?(Hash) && (block[:cache_control] || block["cache_control"]) }
+        return nil if controls.empty?
+
+        controls.any? { |control| control[:ttl] == "1h" } ? "1h" : "on"
+      end
+
+      def sampling_summary(body)
+        SamplingSettings.log_text(body.except(:model, :system, :messages, :stream, :tools, :tool_choice))
+      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")
+        error = ProviderErrors.from_error_body(response.body.to_s, host: @host_name)
+        raise error if error
+        raise ProtocolError.new("#{@host_name}: no content in the Messages response", host: @host_name) unless message?(body)
+
+        AnthropicAssembly.from_message(body).response
+      end
+
+      def message?(body) = body.is_a?(Hash) && body["content"].is_a?(Array)
+
+      # The SSE stream: each `data:` event goes through the assembly (the
+      # `event:` lines are not needed, so a gateway that drops them works);
+      # on_delta gets every event but pings, with its text and reasoning.
+      def chat_streamed(request, cancel_controller, on_delta, on_retry, log_fields)
+        assembly = AnthropicAssembly.new
+        events = 0
+        other = +""
+        plain = +""
+        # A retry streams the answer from the start again.
+        restart = lambda do |**event|
+          assembly = AnthropicAssembly.new
+          plain = +""
+          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
+          raise_plain_error(plain, line) if events.zero?
+          event = parse_line(line)
+          next unless event
+
+          content, reasoning = assembly.add(event)
+          shown.call if AnthropicAssembly.shows?(event)
+          on_delta&.call(content: content, reasoning: reasoning, payload: assembly.with_usage(event)) unless event["type"] == "ping"
+        end
+        raise ProtocolError.new("#{@host_name}: the response had no stream events: #{other}", host: @host_name) if events.zero?
+
+        assembly.response
+      end
+
+      # A 200 whose body is a plain JSON error instead of a stream: raised
+      # from inside the stream (so it is retried by its kind) once the lines
+      # so far parse as an error object (OpenAIChat's rule).
+      def raise_plain_error(plain, line)
+        return if line.empty? || line.start_with?(":") || (plain.empty? && !line.start_with?("{"))
+        return if plain.bytesize > PLAIN_ERROR_LIMIT
+
+        plain << line << "\n"
+        error = ProviderErrors.from_error_body(plain, host: @host_name)
+        raise error if error
+      end
+
+      # The parsed event of a `data:` line; nil for `event:` lines, blank
+      # lines and comments. An error event raises its 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]"
+
+        event = parse_json(data, "stream event")
+        event.is_a?(Hash) ? event : 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)
+        Net::HTTP::Post.new(URI(url)).tap do |request|
+          request["Content-Type"] = "application/json"
+          request["anthropic-version"] = API_VERSION
+          unless session_id.to_s.empty?
+            request["Session-Id"] = session_id.to_s
+            request[@dialect.session_header] = session_id.to_s if @dialect.session_header
+          end
+          request.body = JSON.generate(body)
+        end
+      end
+    end
+  end
+end

data/lib/samagotchi/llm/anthropic_wire.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require_relative "../log"
+require_relative "utf8_scrub"
+
+module Samagotchi
+  module LLM
+    # ChatLoop's wire messages (the OpenAI shape #wire_messages builds) as a
+    # Messages request's top-level system blocks and messages
+    # (AnthropicMessages):
+    # - the head system message → the top-level system, as text blocks: with
+    #   its cache_split, two blocks, the breakpoint on the first; a later
+    #   system message → user text (a mid-conversation system role is
+    #   model-gated);
+    # - an assistant message → its saved blocks verbatim (anthropic_content),
+    #   else a text block and its tool_use blocks (arguments as the input
+    #   object); one with neither is dropped;
+    # - tool messages → tool_result blocks in a user message;
+    # - user parts → text blocks and image blocks (a data URL as base64, an
+    #   http(s) URL as a url source).
+    # Consecutive messages of one role go as one message (so a turn's tool
+    # results and the "[images from tool results]" message after them make
+    # one user message), its tool_result blocks first (Messages wants them
+    # before any other block). Empty or blank text blocks are never
+    # sent; a user message left with none says PLACEHOLDER. reasoning_content
+    # and cache_split never go out.
+    module AnthropicWire
+      PLACEHOLDER = "(empty)"
+      # What Messages takes as a tool_use id.
+      TOOL_ID_INVALID = /[^a-zA-Z0-9_-]/
+      # What Messages takes as a tool name.
+      TOOL_NAME = /\A[a-zA-Z0-9_-]{1,128}\z/
+      # Blocks that can't carry a cache_control breakpoint.
+      UNMARKABLE = %w[thinking redacted_thinking].freeze
+
+      # A request's system blocks and messages.
+      Translated = Data.define(:system, :messages)
+
+      module_function
+
+      # @param wire [Array<Hash>] ChatLoop's wire messages (symbol or string keys)
+      # @param cache [Hash, nil] the cache_control the breakpoints carry
+      #   (PromptCache.control): on the head system's first block and on the
+      #   last block that didn't come from a later system message (a tail
+      #   note moves each request, as PromptCache's rule says); nil sets none
+      # @return [Translated]
+      def translate(wire, cache: nil)
+        system = []
+        messages = []
+        notes = {}.compare_by_identity
+        Array(wire).each_with_index do |raw, index|
+          message = raw.to_h.transform_keys(&:to_sym)
+          role = message[:role].to_s
+          if role == "system" && index.zero?
+            system = system_blocks(message[:content], message[:cache_split], cache)
+            next
+          end
+
+          case role
+          when "assistant" then append(messages, "assistant", assistant_blocks(message))
+          when "tool" then append(messages, "user", [tool_result(message)])
+          when "system"
+            blocks = content_blocks(message[:content])
+            blocks.each { |block| notes[block] = true }
+            append(messages, "user", blocks)
+          else append(messages, "user", content_blocks(message[:content]))
+          end
+        end
+        messages.each { |message| message[:content] << text_block(PLACEHOLDER) if message[:content].empty? }
+        mark_last(messages, cache, notes) if cache
+        Translated.new(system: system, messages: messages)
+      end
+
+      # ChatLoop's function definitions as Messages tools.
+      # @param tools [Array<Hash>] {type: "function", function: {name:, description:, parameters:}}
+      def tools(tools)
+        Array(tools).map do |tool|
+          function = (tool[:function] || tool["function"] || tool).to_h.transform_keys(&:to_sym)
+          { name: function[:name].to_s, description: function[:description],
+            input_schema: function[:parameters] || { type: "object", properties: {} } }.compact
+        end
+      end
+
+      # +id+ as Messages takes it (^[a-zA-Z0-9_-]+$), the same in tool_use
+      # and tool_result: a valid id as it is, another with its invalid
+      # characters replaced and a short hash of it appended (so "a.b" and
+      # "a_b" stay apart).
+      def tool_id(id)
+        text = id.to_s
+        return text if !text.empty? && !text.match?(TOOL_ID_INVALID)
+
+        "#{text.gsub(TOOL_ID_INVALID, "_")}_#{Digest::SHA256.hexdigest(text)[0, 8]}"
+      end
+
+      # A tool name as Messages takes it (TOOL_NAME): a model's malformed one
+      # ("get_weather\n</parameter", a streaming glitch) would 400 every
+      # later request once sent back.
+      def tool_name(name)
+        text = name.to_s
+        return text if text.match?(TOOL_NAME)
+
+        text = text.gsub(TOOL_ID_INVALID, "_")[0, 128]
+        text.empty? ? "tool" : text
+      end
+
+      # A message joins the one before it when the role is the same; an
+      # assistant message with no blocks is dropped.
+      def append(messages, role, blocks)
+        return if role == "assistant" && blocks.empty?
+
+        if messages.last && messages.last[:role] == role
+          content = messages.last[:content].concat(blocks)
+          results, rest = content.partition { |block| type_of(block) == "tool_result" }
+          messages.last[:content] = results + rest
+        else
+          messages << { role: role, content: blocks }
+        end
+      end
+
+      def system_blocks(content, split, cache)
+        text = scrub(content.to_s)
+        return [] if blank?(text)
+
+        head = split.is_a?(Integer) && split.positive? && split < text.length ? text[0, split] : text
+        tail = head.length < text.length ? text[head.length..] : ""
+        first = text_block(head)
+        first[:cache_control] = cache if cache
+        blank?(tail) ? [first] : [first, text_block(tail)]
+      end
+
+      # The saved blocks go back as they came (string keys); otherwise the
+      # text, then the calls.
+      def assistant_blocks(message)
+        saved = message[:anthropic_content]
+        return saved.map { |block| valid_tool_use(block) } if saved.is_a?(Array) && !saved.empty?
+
+        blocks = content_blocks(message[:content])
+        Array(message[:tool_calls]).each do |raw|
+          call = raw.to_h.transform_keys(&:to_sym)
+          function = (call[:function] || {}).to_h.transform_keys(&:to_sym)
+          name = function[:name].to_s
+          blocks << { type: "tool_use", id: tool_id(call[:id]), name: tool_name(name), input: input_of(function[:arguments], name) }
+        end
+        blocks
+      end
+
+      # A saved block as it came, but a tool_use's name made valid and its
+      # id mapped as its tool_result's is (#tool_id: a provider may answer
+      # an id such as "functions.get_weather:0", which Messages refuses
+      # sent back, and the result would name another id).
+      def valid_tool_use(block)
+        return block.dup unless block.is_a?(Hash) && type_of(block) == "tool_use"
+
+        name_key = block.key?("name") ? "name" : :name
+        id_key = block.key?("id") ? "id" : :id
+        block.merge(name_key => tool_name(block[name_key]), id_key => tool_id(block[id_key]))
+      end
+
+      # A tool call's arguments as the input object: ChatLoop sends a JSON
+      # String (raw when it was invalid, for a paired call): one that isn't
+      # an object goes as {}.
+      def input_of(arguments, name)
+        return arguments if arguments.is_a?(Hash)
+
+        text = arguments.to_s
+        return {} if text.strip.empty?
+
+        parsed = JSON.parse(text)
+        return parsed if parsed.is_a?(Hash)
+
+        warn_arguments(name)
+      rescue JSON::ParserError
+        warn_arguments(name)
+      end
+
+      def warn_arguments(name)
+        Log.warn(:model, "tool_arguments_invalid", tool: name, detail: "sent as {} to a Messages host")
+        {}
+      end
+
+      def tool_result(message)
+        block = { type: "tool_result", tool_use_id: tool_id(message[:tool_call_id]) }
+        text = scrub(message[:content].to_s)
+        block[:content] = text unless blank?(text)
+        block
+      end
+
+      # A String or a parts list as blocks.
+      def content_blocks(content)
+        return blank?(content.to_s) ? [] : [text_block(scrub(content.to_s))] unless content.is_a?(Array)
+
+        content.filter_map do |raw|
+          next unless raw.is_a?(Hash)
+
+          part = raw.transform_keys(&:to_sym)
+          case part[:type].to_s
+          when "text" then blank?(part[:text].to_s) ? nil : text_block(scrub(part[:text].to_s))
+          when "image_url" then image_block(part[:image_url])
+          when "image" then raw
+          end
+        end
+      end
+
+      def image_block(image_url)
+        url = image_url.is_a?(Hash) ? (image_url[:url] || image_url["url"]).to_s : image_url.to_s
+        if (match = url.match(/\Adata:([^;,]+);base64,(.*)\z/m))
+          { type: "image", source: { type: "base64", media_type: match[1], data: match[2] } }
+        elsif url.match?(%r{\Ahttps?://}i)
+          { type: "image", source: { type: "url", url: url } }
+        end
+      end
+
+      # Breakpoint #2: the last user block that can carry one and didn't
+      # come from a later system message (+notes+).
+      def mark_last(messages, cache, notes)
+        markable = ->(block) { !UNMARKABLE.include?(type_of(block)) && !notes.key?(block) }
+        message = messages.reverse_each.find { |m| m[:role] == "user" && m[:content].any?(&markable) } or return
+        index = message[:content].rindex(&markable)
+        block = message[:content][index]
+        key = block.key?("type") ? "cache_control" : :cache_control
+        message[:content][index] = block.merge(key => cache)
+      end
+
+      def type_of(block) = (block[:type] || block["type"]).to_s
+
+      def text_block(text) = { type: "text", text: text }
+
+      def blank?(text) = text.strip.empty?
+
+      def scrub(text) = Utf8Scrub.call(text)
+
+      private_class_method :append, :system_blocks, :assistant_blocks, :input_of, :warn_arguments, :tool_result,
+                           :content_blocks, :image_block, :mark_last, :valid_tool_use, :type_of, :text_block, :blank?, :scrub
+    end
+  end
+end