smith-agents 0.10.0 → 0.12.0

data/lib/smith/artifacts/scoped_store.rb

@@ -2,27 +2,75 @@
 
 module Smith
   module Artifacts
+    # A run's view of the artifact store: it stores under its own
+    # namespace, and reads its own refs and those of the namespaces it may
+    # read (a child run's parent and that parent's ancestors). A store that
+    # records who stored a ref (`stored_by?`, as every built-in store does)
+    # is asked, so a ref names an artifact one of those runs stored and no
+    # other; with any other store the namespace prefix alone decides a read,
+    # and a delete is refused.
+    # Without a `backend:`, the configured store is resolved when a step
+    # first stores or reads, so a run that keeps no artifacts needs none.
     class ScopedStore
-      def initialize(backend:, namespace:)
+      def initialize(namespace:, backend: nil, readable: [])
         @backend = backend
         @namespace = namespace
+        @readable = [namespace, *readable].freeze
       end
 
       def store(data, content_type: "application/octet-stream")
-        inner_ref = @backend.store(data, content_type: content_type, execution_namespace: @namespace)
+        inner_ref = backend.store(data, content_type: content_type, execution_namespace: @namespace)
         "#{@namespace}:#{inner_ref}"
       end
 
       def fetch(ref)
-        return nil unless ref.start_with?("#{@namespace}:")
+        return unless ref.is_a?(String)
 
-        inner_ref = ref.delete_prefix("#{@namespace}:")
-        @backend.fetch(inner_ref)
+        namespace = @readable.find { |candidate| ref.start_with?("#{candidate}:") }
+        return nil unless namespace
+
+        inner = ref.delete_prefix("#{namespace}:")
+        return nil if vouches? && !backend.stored_by?(inner, namespace)
+
+        backend.fetch(inner)
+      end
+
+      # Removes one of this run's own refs (never a readable ancestor's or
+      # another run's): only through a store that can tell which run stored
+      # a ref. A store whose delete takes the run (every built-in one) is
+      # asked to remove only what this run stored, and Memory drops only
+      # this run's claim on bytes other runs share; any other store deletes
+      # a ref this run stored.
+      def delete(ref)
+        unless vouches? && backend.respond_to?(:delete)
+          raise Smith::Error, "deleting a run's artifact needs a store with stored_by? and delete"
+        end
+        return unless ref.is_a?(String)
+
+        inner = ref.delete_prefix("#{@namespace}:")
+        if per_run_delete? then backend.delete(inner, execution_namespace: @namespace)
+        elsif backend.stored_by?(inner, @namespace) then backend.delete(inner)
+        end
+        nil
       end
 
+      # Whether the store can tell which run stored a ref.
+      def vouches? = backend.respond_to?(:stored_by?)
+
       def expired(retention: nil)
-        @backend.expired(retention: retention, execution_namespace: @namespace)
-                .map { |ref| "#{@namespace}:#{ref}" }
+        raise Smith::Error, "the artifact store does not list expired refs" unless backend.respond_to?(:expired)
+
+        backend.expired(retention: retention, execution_namespace: @namespace).map { |ref| "#{@namespace}:#{ref}" }
+      end
+
+      private
+
+      def backend = @backend ||= Smith.artifact_backend
+
+      def per_run_delete?
+        backend.method(:delete).parameters.any? do |kind, name|
+          %i[key keyreq].include?(kind) && name == :execution_namespace
+        end
       end
     end
   end

data/lib/smith/artifacts/store_rules.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Smith
+  module Artifacts
+    # What every built-in store holds to: a tenant `namespace:` of letters,
+    # digits, `-` and `_` (so its refs stay readable), the
+    # `artifact_tenant_isolation` setting (refuse to work without a
+    # namespace), refs that are the store's own (its tenant's prefix, then
+    # the store's ref shape, nothing else), the `artifact_retention`
+    # setting when no retention is given, and no run behind a ref whose run
+    # is not named.
+    module StoreRules
+      NAMESPACE = /\A[A-Za-z0-9_-]+\z/
+      UUID = /\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/
+
+      private
+
+      def check_namespace!(namespace)
+        return namespace if namespace.nil? || (namespace.is_a?(String) && NAMESPACE.match?(namespace))
+
+        raise ArgumentError, "an artifact store's namespace: must be letters, digits, - and _"
+      end
+
+      def enforce_tenant_isolation!
+        return unless Smith.config.artifact_tenant_isolation
+
+        raise Smith::Error, "artifact_tenant_isolation requires a namespace" unless @namespace
+      end
+
+      # The store's tenant prefix, then a ref of the store's shape.
+      def owns_ref?(ref)
+        return false unless ref.is_a?(String)
+
+        inner = @namespace ? ref.delete_prefix("#{@namespace}:") : ref
+        (!@namespace || inner != ref) && self.class::INNER_REF.match?(inner)
+      end
+
+      def effective_retention(retention) = retention || Smith.config.artifact_retention
+
+      # An artifact is bytes: other values would be stored as whatever a
+      # store makes of them (Ruby's inspect, or a refusal).
+      def check_data!(data)
+        raise TypeError, "an artifact is bytes (a String); serialize other values first" unless data.is_a?(String)
+      end
+
+      def generate_ref(raw) = @namespace ? "#{@namespace}:#{raw}" : raw
+    end
+  end
+end

data/lib/smith/artifacts.rb

@@ -1,5 +1,102 @@
 # frozen_string_literal: true
 
 module Smith
-  module Artifacts; end
+  # Where steps keep payloads too large to keep inline, and the documents
+  # and images content parts name. Like workflow state, artifacts must
+  # outlive the process that stored them whenever a run waits, retries or
+  # resumes elsewhere, so the store is configured, never assumed:
+  #
+  #   Smith.configure do |config|
+  #     config.artifact_store = :s3            # or :active_record, :file, :memory, or a store
+  #     config.artifact_options = { bucket: "smith-artifacts",
+  #                                 endpoint: "https://<account>.r2.cloudflarestorage.com" }
+  #   end
+  #
+  # With nothing configured, `Smith.artifacts` raises
+  # Smith::ArtifactStoreMissing, except in `test_mode`, where it is an
+  # in-process Memory store.
+  module Artifacts
+    REQUIRED_METHODS = %i[store fetch].freeze
+    NAMED = { memory: :Memory, file: :File, s3: :S3, active_record: :ActiveRecordStore }.freeze
+
+    # The store a configuration names: a store itself (an object, or a
+    # class or module whose own methods store and fetch), a store class
+    # (built with the options), or one of :memory, :file, :s3 and
+    # :active_record. A store needs `store` and `fetch`; `stored_by?` lets
+    # runs read only their own refs, and `expired` and `delete` serve
+    # cleanup.
+    def self.resolve(store, **)
+      return if store.nil?
+      return store if REQUIRED_METHODS.all? { |method_name| store.respond_to?(method_name) }
+      return validate!(store.new(**)) if store.is_a?(Class)
+      return validate!(store) unless store.is_a?(Symbol) || store.is_a?(String)
+
+      named(store, **)
+    end
+
+    def self.named(store, **)
+      name = NAMED.fetch(store.to_sym) do
+        raise ArgumentError, "unknown artifact store #{store.inspect}; use :s3, :active_record, :file or :memory"
+      end
+      const_get(name).new(**)
+    end
+
+    def self.validate!(store)
+      missing = REQUIRED_METHODS.reject { |method_name| store.respond_to?(method_name) }
+      return store if missing.empty?
+
+      raise ArgumentError, "an artifact store must implement #{missing.join(", ")}"
+    end
+  end
+
+  # Inside a step, the run's scoped view of the artifact store; elsewhere
+  # the store itself.
+  def self.artifacts
+    scoped_artifacts || artifact_backend
+  end
+
+  # The configured store itself, never a run's scoped view of it.
+  # Built once per configuration, under a lock, so threads that resolve it
+  # together share one store.
+  def self.artifact_backend
+    signature = artifact_signature
+    current = @_artifact_current
+    return current.last if current&.first == signature
+
+    (@_artifact_lock ||= Mutex.new).synchronize do
+      current = @_artifact_current
+      return current.last if current&.first == signature
+
+      @_artifact_current = [signature, build_artifact_backend].freeze
+      @_artifact_current.last
+    end
+  end
+
+  def self.build_artifact_backend
+    resolved = Artifacts.resolve(config.artifact_store, **(config.artifact_options || {}))
+    resolved ||= Artifacts::Memory.new if config.test_mode
+    resolved || raise(ArtifactStoreMissing)
+  end
+  private_class_method :build_artifact_backend
+
+  # A configured store object is compared by identity; a name or class by
+  # value, with its options; test_mode matters only when nothing is set.
+  def self.artifact_signature
+    store = config.artifact_store
+    name = store.is_a?(Symbol) || store.is_a?(String) || store.is_a?(Module) ? snapshot_value(store) : store.object_id
+    [name, snapshot_value(config.artifact_options || {}), store.nil? && config.test_mode]
+  end
+  private_class_method :artifact_signature
+
+  def self.artifacts=(store)
+    config.artifact_store = store
+  end
+
+  def self.scoped_artifacts
+    Thread.current[:smith_scoped_artifacts]
+  end
+
+  def self.scoped_artifacts=(store)
+    Thread.current[:smith_scoped_artifacts] = store
+  end
 end

data/lib/smith/batch/message_shape.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Smith
+  module Batch
+    # Whether a succeeded result's message has the shape of an Anthropic
+    # Messages reply, as the provider's parser reads it: `content` an Array of
+    # blocks, each a Hash with a String `type` (a text block's `text` a
+    # String), and `usage` a Hash whose token counts are non-negative
+    # Integers. Anything else is refused before the step runs.
+    module MessageShape
+      COUNTS = %w[input_tokens output_tokens].freeze
+      OPTIONAL_COUNTS = %w[cache_read_input_tokens cache_creation_input_tokens].freeze
+      private_constant :COUNTS, :OPTIONAL_COUNTS
+
+      module_function
+
+      def valid?(message)
+        message.is_a?(Hash) && message["content"].is_a?(Array) && message["content"].all? { block?(_1) } &&
+          usage?(message["usage"])
+      end
+
+      def block?(block)
+        return false unless block.is_a?(Hash) && block["type"].is_a?(String)
+
+        block["type"] != "text" || block["text"].is_a?(String)
+      end
+
+      def usage?(usage)
+        usage.is_a?(Hash) && COUNTS.all? { count?(usage[_1]) } &&
+          OPTIONAL_COUNTS.all? { usage[_1].nil? || count?(usage[_1]) }
+      end
+
+      def count?(value) = value.is_a?(Integer) && !value.negative?
+    end
+  end
+end

data/lib/smith/batch.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+require_relative "diagnostic_text"
+require_relative "batch/message_shape"
+
+module Smith
+  # Batch mode (`execute Agent, mode: :batch`, and the same on `fan_out`): a
+  # step's provider request is sent through the host's batch queue instead of
+  # over the wire, and the step waits for its result. Smith renders exactly
+  # the request a synchronous call would post, hands it to
+  # `Smith.config.batch_queue.enqueue(custom_id:, await_token:, request:,
+  # execution_key:)` and waits on `:batch_result`; the host submits batches
+  # (Smith::Providers::Anthropic::Batches), collects their results, and
+  # resumes the run with every result of its wait. Smith never submits or
+  # polls, and waits for the results without sleeping (an in-process
+  # `retry_on` backoff sleeps as on any step; `durable: true` waits instead).
+  module Batch
+    EVENT = "batch_result"
+    RESULT_TYPES = %w[succeeded errored canceled expired].freeze
+    MISSING = "missing"
+    MAX_REQUEST_BYTES = 32 * 1024 * 1024
+    MAX_RESULTS_BYTES = 64 * 1024 * 1024
+    INVALID_REQUEST = "invalid_request_error"
+    CREDENTIAL_HEADERS = %w[authorization x-api-key x-goog-api-key].freeze
+
+    module_function
+
+    # The request a batch carries for one call: the provider, the payload it
+    # would post, and the call's own headers (never credentials: the
+    # connection's stay in it, and a call's own are refused), JSON-shaped,
+    # bounded and frozen.
+    def request(provider:, params:, headers:)
+      if headers.to_h.keys.any? { CREDENTIAL_HEADERS.include?(_1.to_s.downcase) }
+        raise WorkflowError, "a batch request cannot carry credentials in its headers"
+      end
+
+      encoded = JSON.generate("provider" => provider.to_s, "params" => params, "headers" => headers.to_h)
+      if encoded.bytesize > MAX_REQUEST_BYTES
+        raise WorkflowError, "a batch request is #{encoded.bytesize} bytes, past the #{MAX_REQUEST_BYTES} Smith sends"
+      end
+
+      deep_freeze(JSON.parse(encoded))
+    end
+
+    # What identifies a request's content: a SHA-256 of its payload and
+    # headers as JSON gives them, so the request a delivery answers can be
+    # told from one the step would render now.
+    def digest(request) = digest_of(request.fetch("params"), request.fetch("headers"))
+
+    # Whether a call renders a request other than the one sent (`digest`).
+    # Nothing is sent, so nothing in it is refused; one JSON cannot give
+    # counts as changed.
+    def changed?(digest, params, headers)
+      digest_of(params, headers.to_h) != digest
+    rescue JSON::GeneratorError, JSON::NestingError, Encoding::UndefinedConversionError
+      true
+    end
+
+    def digest_of(params, headers) = Digest::SHA256.hexdigest(JSON.generate([params, headers]))
+
+    # A step's request id: its wait token, and for a fan-out branch a key of
+    # the token and the branch (64 hex characters, a valid custom_id).
+    def custom_id(token, branch_key = nil)
+      branch_key.nil? ? token : Digest::SHA256.hexdigest("#{token}/#{branch_key}")
+    end
+
+    # The delivered results, checked: one per expected id, each a result of
+    # a known type, keys as JSON gives them. Raises ArgumentError otherwise.
+    def results!(payload, expected_ids)
+      results = stringified(payload)
+      unless results.keys.sort == expected_ids.sort
+        raise ArgumentError, "a batch delivery must hold exactly the results of its #{expected_ids.length} requests"
+      end
+
+      results.each_value { |result| check_result!(result) }
+      deep_freeze(results)
+    end
+
+    # The message of a succeeded result, or the error a failed one raises:
+    # BatchRequestInvalid for a request the provider refused, else
+    # BatchResultFailed (retryable).
+    def message!(result)
+      case result.fetch("type")
+      when "succeeded" then result.fetch("message")
+      when "errored" then raise_errored!(result)
+      else raise BatchResultFailed.new(kind: result.fetch("type"))
+      end
+    end
+
+    def raise_errored!(result)
+      error = result["error"]
+      type = error.dig("error", "type") || error["type"] if error.is_a?(Hash)
+      raise BatchRequestInvalid if type == INVALID_REQUEST
+
+      raise BatchResultFailed.new(kind: "errored", error_type: type.is_a?(String) ? type : nil)
+    end
+
+    def check_result!(result)
+      raise ArgumentError, "a batch result must be a Hash with a type" unless result.is_a?(Hash)
+
+      type = result["type"]
+      raise ArgumentError, "a batch result's type must be one of #{RESULT_TYPES.join(", ")}" unless
+        RESULT_TYPES.include?(type) || type == MISSING
+      return unless type == "succeeded" && !MessageShape.valid?(result["message"])
+
+      raise ArgumentError, "a succeeded batch result must carry a message of the provider's reply shape"
+    end
+
+    def stringified(payload)
+      raise ArgumentError, "a batch delivery must be a Hash of request ids to results" unless payload.is_a?(Hash)
+
+      encoded = JSON.generate(payload)
+      raise ArgumentError, "a batch delivery is past #{MAX_RESULTS_BYTES} bytes" if encoded.bytesize > MAX_RESULTS_BYTES
+
+      JSON.parse(encoded)
+    rescue JSON::GeneratorError, JSON::NestingError, Encoding::UndefinedConversionError
+      raise ArgumentError, "a batch delivery must be JSON-shaped"
+    end
+
+    def deep_freeze(value)
+      case value
+      when Hash then value.each_value { deep_freeze(_1) }.freeze
+      when Array then value.each { deep_freeze(_1) }.freeze
+      else value.freeze
+      end
+    end
+
+    # The results a resumed step takes, one per branch (nil for a step
+    # without branches), each with the digest of the request it answers, and
+    # what a result does when its call renders another request
+    # (`on_change`). Each is taken once: a follow-up call the step makes
+    # after it (a repair) goes over the wire. `untaken` is what no call took
+    # (a branch cancelled by a sibling's failure) or set aside (a result its
+    # call would not use), paid for all the same.
+    class Delivery
+      Entry = Struct.new(:result, :digest)
+
+      attr_reader :on_change
+
+      def initialize(entries_by_branch, on_change: :keep)
+        @entries = entries_by_branch.dup
+        @set_aside = {}
+        @on_change = on_change
+        @lock = Mutex.new
+      end
+
+      def take(branch_key) = @lock.synchronize { @entries.delete(branch_key) }
+
+      def for?(branch_key) = @lock.synchronize { @entries.key?(branch_key) }
+
+      def set_aside(branch_key, entry) = @lock.synchronize { @set_aside[branch_key] = entry }
+
+      def untaken
+        @lock.synchronize do
+          @set_aside.merge(@entries).tap do
+            @entries.clear
+            @set_aside.clear
+          end
+        end
+      end
+    end
+  end
+end

data/lib/smith/budget/amount.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Smith
+  module Budget
+    # What a provider request may spend (the hold a host's budget ledger is
+    # asked to admit) or did spend (what it is reconciled with): its input
+    # tokens (uncached, cache reads and cache writes together), its output
+    # tokens (thinking included), and its cost from the pricing catalog, nil
+    # when the model has no price there.
+    Amount = Data.define(:input_tokens, :output_tokens, :cost) do
+      def initialize(input_tokens:, output_tokens:, cost:)
+        unless [input_tokens, output_tokens].all? { _1.is_a?(Integer) && !_1.negative? }
+          raise ArgumentError, "a budget amount's token counts must be non-negative Integers"
+        end
+        unless cost.nil? || (cost.is_a?(Numeric) && cost.finite? && !cost.negative?)
+          raise ArgumentError, "a budget amount's cost must be nil or a non-negative number"
+        end
+
+        super
+      end
+
+      def tokens = input_tokens + output_tokens
+    end
+  end
+end

data/lib/smith/budget/amount_representation.rb

@@ -2,6 +2,7 @@
 
 require "bigdecimal"
 require "dry-initializer"
+require_relative "decimal_context"
 
 module Smith
   module Budget
@@ -26,6 +27,25 @@ module Smith
         finite_float!(amount)
       end
 
+      # Remaining capacity, or one of parts equal shares of it, is reserved as
+      # read, so parts reservations of the external value must never exceed the
+      # exact amount. An Integer keeps floor division; a Float steps down until
+      # its decimal form fits, which takes O(1) steps because Float division
+      # lands within one ulp of the exact share.
+      def externalize_remaining(key, amount, parts = 1)
+        unless parts.is_a?(Integer) && parts.positive?
+          raise ArgumentError, "budget share parts must be a positive Integer"
+        end
+
+        share = externalize_amount(key, amount) / parts
+        return share unless share.is_a?(Float)
+
+        DecimalContext.call do
+          share = share.prev_float while internalize_amount(share) * parts > amount
+        end
+        share
+      end
+
       private
 
       def internalize_amount(amount)

data/lib/smith/budget/continuation.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Smith
+  module Budget
+    # The rest of a tool loop that paused for budget: the messages a step's
+    # call added before a host's budget ledger refused a later round (the
+    # model's tool calls, their results, its thinking and its signatures),
+    # kept with the step's retry so that the retry continues the loop from
+    # them instead of running its tools again. JSON-shaped and at most
+    # MAX_BYTES; a loop whose messages cannot be kept so (an attachment in
+    # them, or too many bytes) does not pause. A response memo
+    # (Smith::ResponseMemo) keeps a call's messages the same way, with each
+    # response's `usage`: its token counts, stop reason and message id.
+    module Continuation
+      MAX_BYTES = 1024 * 1024
+      ROLES = %w[assistant tool user].freeze
+      TOKENS = %w[input_tokens output_tokens cached_tokens cache_creation_tokens thinking_tokens].freeze
+
+      module_function
+
+      # `kept` (an earlier pause's) followed by `messages`, or nil; with
+      # `usage`, each response's usage too (its facts from `facts`, by
+      # message, for a streamed response, whose facts its stream gave).
+      def dump(kept, messages, usage: false, facts: {})
+        dumped = messages.map { message(_1, usage: (facts[_1] || {} if usage)) || (return nil) }
+        list = JSON.parse(JSON.generate([*kept, *dumped]))
+        list if JSON.generate(list).bytesize <= MAX_BYTES
+      rescue JSON::GeneratorError, JSON::NestingError, Encoding::UndefinedConversionError
+        nil
+      end
+
+      def message(message, usage: nil)
+        content = content_of(message.content)
+        return if content == :unkept
+
+        { "role" => message.role.to_s, "content" => content, "tool_call_id" => message.tool_call_id,
+          "model_id" => message.model_id, "tool_calls" => message.tool_calls&.values&.map { tool_call(_1) },
+          "thinking" => thinking_of(message.thinking), "usage" => (usage_of(message, usage) if usage) }.compact
+      end
+
+      def usage_of(message, streamed)
+        tokens = message.respond_to?(:tokens) ? message.tokens&.to_h : nil
+        facts = Providers::ResponseFacts.from_message(message).merge(streamed)
+        usage = { "tokens" => tokens&.transform_keys(&:to_s), "stop_reason" => facts[:stop_reason],
+                  "id" => facts[:provider_message_id] }.compact
+        usage unless usage.empty?
+      end
+
+      def thinking_of(thinking) = thinking && { "text" => thinking.text, "signature" => thinking.signature }.compact
+
+      def content_of(content)
+        case content
+        when nil, String then content
+        when RubyLLM::Content::Raw then { "raw" => content.value }
+        # A structured reply, as RubyLLM parses one under a schema.
+        when Hash, Array then { "json" => content }
+        else :unkept
+        end
+      end
+
+      def tool_call(call)
+        { "id" => call.id, "name" => call.name, "arguments" => call.arguments,
+          "thought_signature" => call.thought_signature }.compact
+      end
+
+      # The messages a kept continuation holds, for a chat; ArgumentError if
+      # it is not one `dump` makes.
+      def load(list)
+        raise ArgumentError, "a budget continuation must be a list of messages" unless valid?(list)
+
+        list.map { message_from(_1) }
+      end
+
+      def message_from(entry)
+        content = entry["content"]
+        message = RubyLLM::Message.new(
+          role: entry["role"].to_sym, content: content(content), tool_call_id: entry["tool_call_id"],
+          model_id: entry["model_id"], tool_calls: tool_calls(entry["tool_calls"]),
+          thinking: thinking(entry["thinking"]), **kept_usage(entry["usage"])
+        )
+        # RubyLLM's constructor reads a Hash as attachments.
+        message.content = content["json"] if structured?(content)
+        message
+      end
+
+      # A kept response's token counts, and its facts as a raw body
+      # Providers::ResponseFacts reads.
+      def kept_usage(usage)
+        return {} unless usage
+
+        { **usage.fetch("tokens", {}).transform_keys(&:to_sym),
+          raw: Providers::ResponseFacts.kept(stop_reason: usage["stop_reason"], id: usage["id"]) }
+      end
+
+      def valid?(list)
+        list.is_a?(Array) && !list.empty? && JSON.generate(list).bytesize <= MAX_BYTES && list.all? { entry?(_1) }
+      rescue JSON::GeneratorError, JSON::NestingError
+        false
+      end
+
+      def entry?(entry)
+        entry.is_a?(Hash) && ROLES.include?(entry["role"]) && content?(entry["content"]) &&
+          entry.values_at("tool_call_id", "model_id").all? { optional_string?(_1) } &&
+          calls?(entry["tool_calls"]) && thinking?(entry["thinking"]) && usage?(entry["usage"])
+      end
+
+      def usage?(usage)
+        return true if usage.nil?
+        return false unless usage.is_a?(Hash) && (usage.keys - %w[tokens stop_reason id]).empty?
+
+        tokens?(usage.fetch("tokens", {})) && optional_string?(usage["stop_reason"]) && optional_string?(usage["id"])
+      end
+
+      def tokens?(tokens)
+        tokens.is_a?(Hash) && (tokens.keys - TOKENS).empty? && tokens.values.all? { _1.is_a?(Integer) && !_1.negative? }
+      end
+
+      def calls?(calls) = calls.nil? || (calls.is_a?(Array) && calls.all? { call?(_1) })
+
+      def thinking?(thinking) = thinking.nil? || (thinking.is_a?(Hash) && thinking.values.all?(String))
+
+      def content?(content)
+        content.nil? || content.is_a?(String) || (content.is_a?(Hash) && [["raw"], ["json"]].include?(content.keys))
+      end
+
+      def structured?(content) = content.is_a?(Hash) && content.key?("json")
+
+      def call?(call)
+        call.is_a?(Hash) && call["id"].is_a?(String) && call["name"].is_a?(String) && call["arguments"].is_a?(Hash) &&
+          optional_string?(call["thought_signature"])
+      end
+
+      def optional_string?(value) = value.nil? || value.is_a?(String)
+
+      def content(value)
+        return value unless value.is_a?(Hash)
+
+        structured?(value) ? nil : RubyLLM::Content::Raw.new(value.fetch("raw"))
+      end
+
+      def tool_calls(calls)
+        calls&.to_h do |call|
+          [call["id"], RubyLLM::ToolCall.new(id: call["id"], name: call["name"], arguments: call["arguments"],
+                                             thought_signature: call["thought_signature"])]
+        end
+      end
+
+      def thinking(value) = value && RubyLLM::Thinking.new(text: value["text"], signature: value["signature"])
+    end
+  end
+end