smith-agents 0.11.0 → 0.12.1

data/docs/TOOLS_AND_GUARDRAILS.md

@@ -242,9 +242,8 @@ specific forced tool takes precedence when only one enabled endpoint can carry
 it. If normalization removes a specifically forced tool, Smith clears that
 stale choice and attributes the reset only to that selected tool. An
 endpoint-constrained tool routed to OpenAI Responses inherits the current
-non-streaming Responses contract; callers requesting streaming receive the
-documented explicit unsupported error rather than silent Chat Completions
-fallback.
+non-streaming Responses contract: a caller requesting streaming gets the whole
+reply as one chunk, never a silent Chat Completions fallback.
 
 Bounded completion ownership and tool-call reservations mask asynchronous
 interrupts while installing and restoring process-local state. User work runs
@@ -270,6 +269,28 @@ authoritative replay proof. `ordinal` is allocated from one thread-safe sequence
 shared by every Smith-managed chat, branch, thread, and fiber inside the current
 host invocation scope.
 
+For a key to send with a side-effecting request, a tool running in a workflow
+step calls `idempotency_key(scope)` in `perform`:
+
+```ruby
+class SendInvoice < Smith::Tool
+  def perform(customer_id:, amount_cents:)
+    Billing.send_invoice(customer_id:, amount_cents:,
+                         idempotency_key: idempotency_key(customer_id:, amount_cents:))
+  end
+end
+```
+
+The key is unique to the run, the step and branch the tool runs in, the tool's
+`name` and the scope, including in concurrent tool calls, and it is the same
+when a replay sends the same request. The scope should be the request's stable
+identity (customer and amount here), not free text such as a message body:
+the model can call one tool several times in a step, and a replayed step's
+model may word or order its calls differently. Renaming the tool class changes
+its keys. Outside a workflow step it raises `Smith::WorkflowError`. Smith
+supplies the key; holding operation receipts and reconciling outcomes stays
+with the host, as above. See `docs/PERSISTENCE.md`, Replay Safety.
+
 Hosts that reconstruct an execution may supply an explicit next ordinal:
 
 ```ruby

data/lib/generators/smith/install/install_generator.rb

@@ -1,22 +1,87 @@
 # frozen_string_literal: true
 
 require "rails/generators"
+require "rails/generators/active_record"
 
 module Smith
+  # `rails g smith:install`: the initializer, and a table and model for
+  # workflow state (Smith's :active_record persistence adapter) unless
+  # --skip-state-model.
   class InstallGenerator < Rails::Generators::Base
+    include Rails::Generators::Migration
+
+    # The most a PostgreSQL text column holds (1 GiB less a byte), the
+    # payload's limit when no bound is set.
+    UNBOUNDED_PAYLOAD = 1_073_741_823
+    # The default bound: well above what one step can add to a state (a
+    # map's collected results, 4 MiB; a wait's payload or a paused tool
+    # loop, 1 MiB each), so it refuses runaway growth, not a run Smith built.
+    MAX_STATE_BYTES = 16 * 1024 * 1024
+
     source_root File.expand_path("templates", __dir__)
+    desc "Writes Smith's initializer, and a table and model for workflow state"
+
+    class_option :state_model, type: :string, default: "WorkflowState",
+                               desc: "The model that keeps workflow state"
+    class_option :max_state_bytes, type: :numeric, default: MAX_STATE_BYTES,
+                                   desc: "persistence_max_bytes, and the payload CHECK above it (0: neither)"
+    class_option :skip_state_model, type: :boolean, default: false,
+                                    desc: "Write only the initializer"
+
+    def self.next_migration_number(dirname) = ActiveRecord::Generators::Base.next_migration_number(dirname)
+
+    def check_options
+      bytes = options[:max_state_bytes]
+      return if bytes.is_a?(Integer) && !bytes.negative?
+
+      raise Thor::Error, "--max-state-bytes must be a whole number of bytes (0 for no bound), got #{bytes.inspect}"
+    end
 
     def create_smith_initializer
       template "smith.rb.tt", "config/initializers/smith.rb"
     end
 
+    def create_state_model
+      return if options[:skip_state_model]
+
+      migration_template "create_workflow_states.rb.tt", "db/migrate/create_#{table_name}.rb"
+      template "workflow_state.rb.tt", File.join("app/models", "#{state_model.underscore}.rb")
+    end
+
     def show_next_steps
       say ""
       say "Smith installed. Next steps:", :green
       say "  1. Configure RubyLLM in config/initializers/ruby_llm.rb"
-      say "  2. Run: bin/rails smith:doctor"
-      say "  3. Define your first agent and workflow"
+      say "  2. Run: bin/rails db:migrate" unless options[:skip_state_model]
+      say "  #{options[:skip_state_model] ? 2 : 3}. Run: bin/rails smith:doctor"
       say ""
     end
+
+    private
+
+    def state_model = options[:state_model].camelize
+
+    # The table's name, set on the model: a namespace's own
+    # table_name_prefix cannot move it.
+    def table_name = state_model.demodulize.underscore.pluralize
+
+    def namespaces = state_model.split("::")[0...-1]
+
+    def max_state_bytes = options[:max_state_bytes]
+
+    # The payload CHECK's bound: past persistence_max_bytes by a third and
+    # a little, so Smith's refusal comes first even for a column the host
+    # encrypts (Base64 ciphertext with its headers).
+    def check_bytes
+      (max_state_bytes * 4 / 3) + 4096 if max_state_bytes.positive?
+    end
+
+    # The payload column's limit: MySQL picks its text type by it (TEXT
+    # holds only 64 KiB); PostgreSQL refuses one past 1 GiB and otherwise
+    # ignores it, as SQLite does.
+    def payload_limit = [check_bytes || UNBOUNDED_PAYLOAD, UNBOUNDED_PAYLOAD].min
+
+    # An Integer as a Ruby literal: 16_777_216.
+    def literal(number) = number.to_s.gsub(/\B(?=(\d{3})+(?!\d))/, "_")
   end
 end

data/lib/generators/smith/install/templates/create_workflow_states.rb.tt

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Workflow runs' stored state, for Smith's :active_record persistence
+# adapter: a key the database keeps unique (child runs' keys are 64
+# characters), the state as JSON text, and the lock_version Smith's writes
+# compare. The payload's limit makes MySQL choose a text type that holds it.
+class Create<%= table_name.camelize %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :<%= table_name %> do |t|
+      t.string :key, null: false, index: { unique: true }
+      t.text :payload, null: false, limit: <%= literal(payload_limit) %>
+      t.integer :lock_version, null: false, default: 0
+      t.timestamps
+    end
+<%- if check_bytes -%>
+
+    # Smith refuses a state past persistence_max_bytes (<%= literal(max_state_bytes) %>) before
+    # writing it; this bounds the stored bytes, with room for an encrypted column.
+    add_check_constraint :<%= table_name %>, "#{payload_bytes} <= <%= check_bytes %>",
+                         name: "<%= table_name %>_payload_size"
+<%- end -%>
+  end
+<%- if check_bytes -%>
+
+  private
+
+  def payload_bytes
+    connection.adapter_name.match?(/sqlite/i) ? "length(CAST(payload AS BLOB))" : "octet_length(payload)"
+  end
+<%- end -%>
+end

data/lib/generators/smith/install/templates/smith.rb.tt

@@ -3,7 +3,21 @@
 Smith.configure do |config|
   config.logger = Rails.logger
 
+<%- unless options[:skip_state_model] -%>
+  # Workflow state in the <%= table_name %> table, through <%= state_model %>.
+  config.persistence_adapter = :active_record
+  config.persistence_options = { model: "<%= state_model %>" }
+<%- if max_state_bytes.positive? -%>
+  # The most bytes a run's state may take: past it Smith raises
+  # Smith::PersistedStateTooLarge before writing. The payload column's
+  # CHECK sits above it.
+  config.persistence_max_bytes = <%= literal(max_state_bytes) %>
+<%- end -%>
+
+  # Other persistence adapters:
+<%- else -%>
   # Host durability verification / persistence adapter options:
+<%- end -%>
   # config.persistence_adapter = :rails_cache
   # config.persistence_options = { namespace: "smith" }
   #
@@ -16,29 +30,46 @@ Smith.configure do |config|
   #   namespace: "smith"
   # }
   #
-  # config.persistence_adapter = :active_record
+<%- if options[:skip_state_model] -%>
+  # config.persistence_adapter = :active_record   # `rails g smith:install` writes its table and model
   # config.persistence_options = {
-  #   model: WorkflowState,
+  #   model: "WorkflowState",
   #   key_column: :key,
   #   payload_column: :payload
   # }
   #
+<%- end -%>
   # Custom adapters are also supported if they implement:
   #   store(key, payload)
   #   fetch(key)
   #   delete(key)
 
-  # Artifact storage for large outputs
-  config.artifact_store = Smith::Artifacts::Memory.new
+  # Artifact storage for large outputs and the documents steps attach. Like
+  # workflow state it must outlive the process for runs that wait, retry or
+  # resume elsewhere; with none set, storing or reading an artifact raises
+  # Smith::ArtifactStoreMissing (smith:doctor warns).
+  #
+  # config.artifact_store = :s3   # AWS S3, or Cloudflare R2 (needs the aws-sdk-s3 gem)
+  # config.artifact_options = {
+  #   bucket: "smith-artifacts",
+  #   endpoint: "https://<account>.r2.cloudflarestorage.com", region: "auto",
+  #   access_key_id: ENV["R2_ACCESS_KEY_ID"], secret_access_key: ENV["R2_SECRET_ACCESS_KEY"]
+  # }
+  #
+  # config.artifact_store = :active_record   # a table: see the PERSISTENCE guide, Artifacts
+  # config.artifact_options = { model: "SmithArtifact" }
+  #
+  # config.artifact_store = :memory   # one process only, e.g. in tests
 
   # Trace adapter (Smith::Trace::Memory, Smith::Trace::Logger, Smith::Trace::OpenTelemetry)
   config.trace_adapter = Smith::Trace::Logger
 
   # Best-known model-call cost tracking (optional)
-  # config.pricing = {
-  #   "gpt-4.1-nano" => {
+  # config.pricing = Smith::Pricing.validate_catalog!(
+  #   %w[openai gpt-4.1-nano] => {
   #     input_cost_per_token: 0.0000001,
-  #     output_cost_per_token: 0.0000004
+  #     output_cost_per_token: 0.0000004,
+  #     cache_read_cost_per_token: 0.000000025 # optional; 0 when absent
   #   }
-  # }
+  # )
 end

data/lib/generators/smith/install/templates/workflow_state.rb.tt

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+<%- namespaces.each_with_index do |namespace, depth| -%>
+<%= "  " * depth %>module <%= namespace %>
+<%- end -%>
+<%- indent = "  " * namespaces.length -%>
+<%= indent %># A workflow run's stored state (Smith's :active_record persistence
+<%= indent %># adapter). Keep it to persistence: Smith writes it under optimistic
+<%= indent %># locking, and a callback that raises after the commit leaves a write it
+<%= indent %># cannot confirm. An encrypted payload (`encrypts`) holds runs, but not
+<%= indent %># split-step exact writes (smith doctor warns).
+<%= indent %>class <%= state_model.demodulize %> < ApplicationRecord
+<%- unless namespaces.empty? -%>
+<%= indent %>  self.table_name = "<%= table_name %>"
+<%- end -%>
+<%= indent %>end
+<%- namespaces.length.times.reverse_each do |depth| -%>
+<%= "  " * depth %>end
+<%- end -%>

data/lib/smith/agent/completion.rb

@@ -10,18 +10,27 @@ module Smith
       attribute :response, Types::Any
       attribute :provider_usages, Types::Array.of(Types.Instance(ProviderUsage))
       attribute :usage_complete, Types::Bool
+      # The stop reason and message id of the last provider response,
+      # whether or not that response reported usage.
+      attribute :response_facts, Types::Hash.default({}.freeze)
 
-      def self.from_messages(response:, messages:)
+      # `stream` is set for a streamed call: the facts of each of its
+      # requests, read from the stream, and the request's output limit
+      # (Providers::StreamFacts). Each response's usage carries its facts and
+      # `mode: :stream`. `mode` marks another call's usage (:batch).
+      def self.from_messages(response:, messages:, stream: nil, mode: nil)
         assistant_messages = Array(messages).select do |message|
           message.respond_to?(:role) && message.role.to_s == "assistant"
         end
         usage_source = assistant_messages.empty? ? [response] : assistant_messages
+        facts = response_facts(usage_source, stream)
 
-        provider_usages = build_provider_usages(usage_source)
+        provider_usages = build_provider_usages(usage_source, stream && facts, mode)
         new(
           response: response,
           provider_usages:,
-          usage_complete: provider_usages.length == usage_source.length
+          usage_complete: provider_usages.length == usage_source.length,
+          response_facts: facts.last
         )
       end
 
@@ -37,10 +46,27 @@ module Smith
         provider_usages.sum(&:output_tokens) if usage_complete
       end
 
-      def self.build_provider_usages(messages)
-        messages.filter_map { |message| ProviderUsage.from_message(message) }.freeze
+      # The whole completion's usage, cache and thinking counts and the
+      # final response's stop reason included; nil unless every response
+      # reported usage.
+      def usage
+        ProviderUsage.sum(provider_usages) if usage_complete
       end
-      private_class_method :build_provider_usages
+
+      def self.response_facts(messages, stream)
+        return messages.map { Providers::ResponseFacts.from_message(_1) } unless stream
+
+        Providers::StreamFacts.per_message(messages, stream.fetch(:rounds), stream.fetch(:output_limit))
+      end
+
+      def self.build_provider_usages(messages, streamed_facts, mode)
+        messages.each_with_index.filter_map do |message, index|
+          usage = ProviderUsage.from_message(message)
+          usage = usage.streamed(streamed_facts[index]) if streamed_facts && usage
+          mode && usage ? usage.new(mode:) : usage
+        end.freeze
+      end
+      private_class_method :response_facts, :build_provider_usages
     end
   end
 end

data/lib/smith/agent/completion_usage_recording.rb

@@ -5,33 +5,42 @@ module Smith
     module CompletionUsageRecording
       private
 
-      # Returns [invocation_cost, fully_priced]. The cost is the sum of the
-      # recorded entries' costs (nil when nothing was priced): per-response
-      # pricing is what tiered catalogs bill, so the invocation cost comes
-      # from this sum, never from pricing the aggregate token totals (which
-      # would resolve the wrong tier for multi-response tool loops).
-      # fully_priced is true only when every provider response carried usage
-      # and every usage priced; a partial sum is still returned (it is what
-      # was verifiably billed) but callers must not present it as the
-      # complete invocation cost.
-      def record_completion_usage(agent_class, completion, attempt_kind, model_reference, attempt_id: nil)
+      # Records and prices one usage entry per provider response and returns
+      # the per-response AgentResults: per-response pricing is what tiered
+      # catalogs bill, so an invocation's cost is the sum of these, never the
+      # aggregate token totals priced as one call (which would resolve the
+      # wrong tier for a multi-response tool loop).
+      def record_response_usages(agent_class, usages, attempt_kind, model_reference, attempt_id: nil)
         model_reference = coerce_model_reference(model_reference)
-        costs = completion.provider_usages.map do |usage|
+        usages.map do |usage|
           result = Workflow::AgentResult.new(
             content: nil,
             input_tokens: usage.input_tokens,
             output_tokens: usage.output_tokens,
             cost: nil,
             model_used: model_reference.model_id,
-            provider_used: model_reference.provider
+            provider_used: model_reference.provider,
+            **Workflow::AgentResult.usage_details(usage)
           )
           compute_agent_cost(result)
           record_usage(agent_class, result, attempt_kind, model_reference, attempt_id:)
-          result.cost
+          result
         end
-        summarize_invocation_costs(costs, completion)
       end
 
+      # Returns [invocation_cost, fully_priced, per_response_results].
+      def record_completion_usage(agent_class, completion, attempt_kind, model_reference, attempt_id: nil)
+        results = record_response_usages(agent_class, completion.provider_usages, attempt_kind, model_reference,
+                                         attempt_id:)
+        [*summarize_invocation_costs(results.map(&:cost), completion), results]
+      end
+
+      # Returns [invocation_cost, fully_priced]. The cost is the sum of the
+      # priced responses (nil when none was priced). fully_priced is true
+      # only when every provider response carried usage and every usage
+      # priced; a partial sum is still returned (it is what was verifiably
+      # billed) but callers must not present it as the complete invocation
+      # cost.
       def summarize_invocation_costs(costs, completion)
         priced = costs.compact
         invocation_cost = priced.empty? ? nil : priced.sum

data/lib/smith/agent/content_bytes.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Smith
+  class Agent
+    # The documents and images of one agent invocation, read from the run's
+    # artifacts once, before its first attempt, and checked: readable, a
+    # non-empty String, of the kind its media type names (a PDF, PNG, JPEG,
+    # GIF or WebP by its leading bytes, `text/plain` as UTF-8), an image at
+    # most MAX_IMAGE_BYTES and any part at most Content::MAX_PART_BYTES, and
+    # the request's text with its documents and images as they are sent
+    # (PDFs and images in base64) at most MAX_REQUEST_BYTES. Anything else
+    # raises Smith::ContentUnavailable; the store's own errors pass on.
+    # Held per thread for the invocation, so parallel branches read their
+    # own.
+    module ContentBytes
+      MAX_IMAGE_BYTES = 5 * 1024 * 1024
+      MAX_REQUEST_BYTES = 32 * 1024 * 1024
+      SIGNATURES = {
+        "application/pdf" => ->(bytes) { bytes.start_with?("%PDF-".b) },
+        "image/png" => ->(bytes) { bytes.start_with?("\x89PNG\r\n\x1A\n".b) },
+        "image/jpeg" => ->(bytes) { bytes.start_with?("\xFF\xD8\xFF".b) },
+        "image/gif" => ->(bytes) { bytes.start_with?("GIF87a".b, "GIF89a".b) },
+        "image/webp" => ->(bytes) { bytes.byteslice(0, 4) == "RIFF".b && bytes.byteslice(8, 4) == "WEBP".b },
+        "text/plain" => ->(bytes) { bytes.dup.force_encoding(Encoding::UTF_8).valid_encoding? }
+      }.freeze
+      HELD = :smith_content_bytes
+      private_constant :SIGNATURES, :HELD
+
+      module_function
+
+      def with(messages)
+        outer = Thread.current[HELD]
+        Thread.current[HELD] = read(Array(messages))
+        yield
+      ensure
+        Thread.current[HELD] = outer
+      end
+
+      # A part's bytes, as the invocation read them, or read now.
+      def fetch(part)
+        held = Thread.current[HELD]
+        key = [part["artifact"], part["media_type"]]
+        held&.key?(key) ? held.fetch(key) : checked_bytes(part)
+      end
+
+      def read(messages)
+        held = {}
+        total = 0
+        messages.each do |message|
+          next unless Message.parts?(message)
+
+          (message[:content] || message["content"]).map { |part| Content.check!(part) }.each do |part|
+            total += sent_bytes(part, held)
+            next if total <= MAX_REQUEST_BYTES
+
+            raise ContentUnavailable, "the request's text, documents and images come to more than " \
+                                      "#{MAX_REQUEST_BYTES} bytes as sent"
+          end
+        end
+        held.freeze
+      end
+
+      def sent_bytes(part, held)
+        return part["text"].bytesize if part["type"] == "text"
+
+        bytes = (held[[part["artifact"], part["media_type"]]] ||= checked_bytes(part))
+        part["media_type"] == "text/plain" ? bytes.bytesize : 4 * ((bytes.bytesize + 2) / 3)
+      end
+
+      def checked_bytes(part)
+        bytes = stored_bytes(part)
+        limit = part["type"] == "image" ? MAX_IMAGE_BYTES : Content::MAX_PART_BYTES
+        problem = if !bytes.is_a?(String) then "is missing or expired, or not a String"
+                  elsif bytes.empty? then "is empty"
+                  elsif bytes.bytesize > limit then "is larger than #{limit} bytes"
+                  elsif !SIGNATURES.fetch(part["media_type"]).call(bytes.b) then "is not #{part["media_type"]}"
+                  end
+        return bytes unless problem
+
+        raise ContentUnavailable, "the artifact of a #{part["type"]} part #{problem}"
+      end
+
+      # Through the run's scoped store, which must be able to tell which run
+      # stored a ref. The store's own errors (a timeout, a missing store)
+      # pass on as they are, before any provider attempt, so `retry_on` can
+      # take a transient one.
+      def stored_bytes(part)
+        store = Smith.scoped_artifacts
+        unless store.respond_to?(:vouches?) && store.vouches?
+          raise ContentUnavailable, "content parts are read inside a step, from an artifact store that records " \
+                                    "which run stored each artifact (stored_by?)"
+        end
+
+        store.fetch(part["artifact"])
+      end
+    end
+  end
+end

data/lib/smith/agent/content_parts.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "base64"
+require "stringio"
+
+module Smith
+  class Agent
+    # A message with content parts (Smith::Message) as the provider takes
+    # it, built for each attempt's chat. Anthropic gets native blocks
+    # (`RubyLLM::Content::Raw`), a cached part with `cache_control`, at most
+    # MAX_CACHE_BREAKPOINTS cached blocks in the request (Smith's and the
+    # chat's own). Any other provider gets the parts as one text, in order,
+    # with a `text/plain` document inline and each PDF or image as an
+    # attachment named where it stands in the text; `cache:` is ignored.
+    #
+    # The documents and images of one invocation are read from the run's
+    # artifacts once, before the first attempt (ContentBytes), so a store
+    # failure is never taken for a provider failure.
+    module ContentParts
+      MAX_CACHE_BREAKPOINTS = 4
+      EXTENSIONS = { "application/pdf" => "pdf", "text/plain" => "txt", "image/png" => "png",
+                     "image/jpeg" => "jpg", "image/gif" => "gif", "image/webp" => "webp" }.freeze
+      private_constant :MAX_CACHE_BREAKPOINTS, :EXTENSIONS
+
+      private
+
+      # Counts the cached blocks already in the chat (its instructions) and
+      # those the prepared input adds, before any is added.
+      def check_cache_breakpoints!(chat, messages, provider)
+        return unless anthropic?(provider)
+
+        cached = chat_cache_controls(chat) +
+                 messages.sum { |message| message_parts(message).count { |part| Content.cached?(part) } }
+        return if cached <= MAX_CACHE_BREAKPOINTS
+
+        raise ContentUnavailable, "#{cached} blocks ask to be cached; Anthropic takes at most " \
+                                  "#{MAX_CACHE_BREAKPOINTS} cache breakpoints in one request"
+      end
+
+      def check_chain_cache_breakpoints!(chain, prepared_input)
+        return unless chain.any? { |reference| anthropic?(reference.provider) }
+
+        check_cache_breakpoints!(nil, Array(prepared_input), :anthropic)
+      end
+
+      # A model the chain reaches whose provider takes no such content.
+      def unsupported_content?(error) = error.is_a?(::RubyLLM::UnsupportedAttachmentError)
+
+      def chat_cache_controls(chat)
+        return 0 unless chat.respond_to?(:messages)
+
+        chat.messages.sum do |message|
+          content = message.respond_to?(:content) ? message.content : nil
+          content.is_a?(::RubyLLM::Content::Raw) ? Array(content.value).count { |block| cached_block?(block) } : 0
+        end
+      end
+
+      def cached_block?(block) = block.is_a?(Hash) && !(block[:cache_control] || block["cache_control"]).nil?
+
+      # A parts message's parts: checked where they came in (input:, seeds,
+      # restore) and again before the first attempt (ContentBytes).
+      def message_parts(message)
+        return [] unless Message.parts?(message)
+
+        message[:content] || message["content"]
+      end
+
+      BUILT = :smith_built_contents
+      private_constant :BUILT
+
+      # The contents Smith builds while it adds one prepared input to a
+      # chat, held per thread for that call.
+      def with_built_contents
+        outer = Thread.current[BUILT]
+        Thread.current[BUILT] = {}.compare_by_identity
+        yield
+      ensure
+        Thread.current[BUILT] = outer
+      end
+
+      # The message with its parts as `provider` takes them; the content is
+      # recorded as Smith's own, so it passes to the chat unencoded.
+      def provider_parts_message(message, provider)
+        parts = message_parts(message)
+        content = anthropic?(provider) ? anthropic_content(parts) : provider_content(parts)
+        Thread.current[BUILT]&.store(content, true)
+        { role: Workflow::MessageRoles.role(message).to_sym, content: }
+      end
+
+      def built_content?(content) = Thread.current[BUILT]&.key?(content) || false
+
+      def anthropic?(provider) = provider.to_s == "anthropic"
+
+      def anthropic_content(parts)
+        ::RubyLLM::Content::Raw.new(parts.map { |part| anthropic_block(part) })
+      end
+
+      def anthropic_block(part)
+        block = case part["type"]
+                when "text" then { type: "text", text: part["text"] }
+                when "image" then { type: "image", source: base64_source(part) }
+                else document_block(part)
+                end
+        Content.cached?(part) ? block.merge(cache_control: { type: "ephemeral" }) : block
+      end
+
+      def document_block(part)
+        if part["media_type"] == "text/plain"
+          return { type: "document", source: { type: "text", media_type: "text/plain", data: artifact_text(part) } }
+        end
+
+        { type: "document", source: base64_source(part) }
+      end
+
+      def base64_source(part)
+        { type: "base64", media_type: part["media_type"], data: Base64.strict_encode64(artifact_bytes(part)) }
+      end
+
+      # The parts in order as one text: text parts as they are, a
+      # `text/plain` document inline, and a marker where each PDF or image
+      # stands, attached under the marker's name.
+      def provider_content(parts)
+        texts = []
+        attachments = []
+        parts.each.with_index(1) { |part, position| add_provider_part(part, position, texts, attachments) }
+        text = texts.join("\n\n")
+        return text if attachments.empty?
+
+        ::RubyLLM::Content.new(text.empty? ? nil : text, attachments)
+      end
+
+      def add_provider_part(part, position, texts, attachments)
+        return texts << part["text"] if part["type"] == "text"
+
+        name = "#{part["type"]}-#{position}.#{EXTENSIONS.fetch(part["media_type"])}"
+        if part["media_type"] == "text/plain"
+          texts << "<file name='#{name}' mime_type='text/plain'>#{artifact_text(part)}</file>"
+        else
+          texts << "[attached: #{name}]"
+          attachments << ::RubyLLM::Attachment.new(StringIO.new(artifact_bytes(part)), filename: name)
+        end
+      end
+
+      def artifact_text(part) = artifact_bytes(part).dup.force_encoding(Encoding::UTF_8)
+
+      def artifact_bytes(part) = ContentBytes.fetch(part)
+    end
+  end
+end