smith-agents 0.7.0 → 0.8.0

data/lib/smith/models.rb

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
 
 require "dry-container"
-require "monitor"
+
+require_relative "models/profile"
+require_relative "models/ambiguous_profile_error"
+require_relative "models/collision_error"
+require_relative "models/provider_qualified_registry"
 
 module Smith
   # Capability registry for model ids. Decoupled from Smith.config.pricing
@@ -21,97 +25,47 @@ module Smith
   #   3. Safe default (no thinking, accepts temp, no routing)
   module Models
     extend Dry::Container::Mixin
-
-    class CollisionError < Smith::Error; end
+    extend ProviderQualifiedRegistry
 
     def self.normalize_key(model_id)
       model_id.to_s
     end
 
-    def self.find(model_id)
-      registry_monitor.synchronize do
-        key = normalize_key(model_id)
-        key?(key) ? resolve(key) : nil
-      end
-    end
-
     # Application overrides first, then Inference rules, then safe default.
     def self.find_or_infer(model_id, provider: nil)
-      find(model_id) || infer(model_id, provider: provider)
+      find(model_id, provider:) || infer(model_id, provider:)
     end
 
     def self.infer(model_id, provider: nil)
       inferred = Inference.profile_for(model_id) if defined?(Inference)
-      return inferred if inferred
+      return inferred_profile_for_provider(inferred, provider) if inferred
 
       Profile.new(
-        model_id:                   normalize_key(model_id),
-        provider:                   provider || guess_provider(model_id),
-        thinking_shape:             nil,
-        accepts_temperature:        true,
+        model_id: normalize_key(model_id),
+        provider: provider || guess_provider(model_id),
+        thinking_shape: nil,
+        accepts_temperature: true,
         tools_with_thinking_native: false,
-        tools_with_thinking_route:  nil
+        tools_with_thinking_route: nil
       )
     end
 
-    # Register a Profile. Idempotent when re-registering an identical
-    # profile; replaces silently on Rails-reload (same model_id, possibly
-    # different Profile object after autoload swap); raises CollisionError
-    # on a genuinely conflicting registration.
-    #
-    # The stale-reload-binding pattern mirrors Smith::Agent::Registry
-    # (agent/registry.rb:118-124) which solves the same problem for
-    # agent classes during Rails autoreload.
-    def self.register(profile)
-      registry_monitor.synchronize do
-        key = normalize_key(profile.model_id)
-        existing = key?(key) ? resolve(key) : nil
-
-        return profile if existing == profile
+    def self.inferred_profile_for_provider(profile, provider)
+      return profile unless provider && profile.provider != provider.to_sym
 
-        if existing && stale_reload_binding?(existing, profile)
-          # Same model_id, value-unequal Profile — Rails reload swap.
-          # Document trade-off: a host that intentionally re-registers with
-          # different capabilities also gets silent replacement (same
-          # behavior Smith::Agent::Registry chose).
-          _container.delete(key)
-          super(key, profile)
-          return profile
-        end
-
-        if existing
-          raise CollisionError,
-                "model #{key.inspect} already registered with a different profile"
-        end
-
-        super(key, profile)
-        profile
-      end
-    end
-
-    def self.all
-      registry_monitor.synchronize do
-        keys.sort.map { |k| resolve(k) }
-      end
-    end
-
-    def self.clear!
-      registry_monitor.synchronize { @_container&.clear }
-    end
-
-    # Eagerly initialized at module load so concurrent first-callers
-    # cannot race the `||=` lazy-init and end up with separate Monitor
-    # instances (which would partially defeat synchronization).
-    @_registry_monitor = Monitor.new
-
-    def self.registry_monitor
-      @_registry_monitor
+      Profile.new(
+        **profile.to_h,
+        provider: provider.to_sym,
+        tools_with_thinking_native: false,
+        tools_with_thinking_route: nil
+      )
     end
+    private_class_method :inferred_profile_for_provider
 
     PROVIDER_PATTERNS = {
       anthropic: /\Aclaude/i,
-      openai:    /\A(gpt|o\d)/i,
-      gemini:    /\Agemini/i
+      openai: /\A(gpt|o\d)/i,
+      gemini: /\Agemini/i
     }.freeze
     private_constant :PROVIDER_PATTERNS
 
@@ -120,13 +74,5 @@ module Smith
       PROVIDER_PATTERNS.each { |provider, pattern| return provider if key.match?(pattern) }
       :unknown
     end
-
-    # Same model_id but value-unequal Profile objects (e.g., a host
-    # tweaked a built-in profile in config/initializers and Rails
-    # reloaded). Replace silently rather than raise.
-    def self.stale_reload_binding?(existing, profile)
-      existing.model_id == profile.model_id
-    end
-    private_class_method :stale_reload_binding?
   end
 end

data/lib/smith/persisted_failure_invalid.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "error"
+
+module Smith
+  class PersistedFailureInvalid < Error; end
+end

data/lib/smith/pricing.rb

@@ -17,20 +17,137 @@ module Smith
     #     call's input_tokens picks the rate. Used for models with
     #     long-context premium pricing (Gemini 2.5 Pro: $1.25/$10 below
     #     200K input tokens, $2.50/$15 above).
-    def self.compute_cost(model:, input_tokens:, output_tokens:)
+    #
+    # Catalog keys are normalized once per assigned catalog object:
+    #   ["provider", "model"] / [:provider, :model]  -> provider-qualified
+    #   "provider/model" (first slash splits)        -> provider-qualified
+    #   "model" / :model (no slash)                  -> legacy model-only
+    #
+    # Lookup policy: a provider-qualified lookup reads only qualified
+    # entries and NEVER prices from a legacy model-only rate; unpriced
+    # usage stays visibly unpriced (nil cost). This method never raises,
+    # so accounting paths cannot mask a provider error with a pricing
+    # configuration error. The legacy-only-key policy is enforced at
+    # catalog admission time via `validate_catalog!`.
+    def self.compute_cost(model:, input_tokens:, output_tokens:, provider: nil)
       catalog = Smith.config.pricing
-      return nil unless catalog
+      return nil unless catalog.is_a?(Hash)
 
-      entry = catalog[model.to_s]
+      entry = lookup_entry(normalized_index(catalog), model, provider)
       return nil unless entry
 
-      rates = resolve_rates(entry, input_tokens)
-      return nil unless rates
+      input_rate, output_rate = resolve_rates(entry, input_tokens)
+      return nil unless input_rate
 
-      input_rate, output_rate = rates
       (input_tokens * input_rate) + (output_tokens * output_rate)
     end
 
+    def self.lookup_entry(index, model, provider)
+      return index.fetch(:qualified)[[provider.to_s, model.to_s]] if provider
+
+      index.fetch(:legacy)[model.to_s]
+    end
+
+    # Admission-time catalog validation. Call when the pricing catalog
+    # is assigned (`config.pricing = Smith::Pricing.validate_catalog!(catalog)`)
+    # so misconfiguration fails at configuration time instead of inside
+    # an in-flight accounting path. Rejects legacy model-only keys,
+    # unrecognized key shapes, non-Hash entries, and keys that collide
+    # after normalization. Returns the catalog for assignment chaining.
+    def self.validate_catalog!(catalog = Smith.config.pricing)
+      return catalog if catalog.nil?
+      raise Smith::PricingConfigurationError, "pricing catalog must be a Hash" unless catalog.is_a?(Hash)
+
+      catalog.each_with_object({}) do |(key, entry), seen|
+        provider, model = validated_key!(key)
+        validate_entry!(key, entry)
+        reject_collision!(seen, key, provider, model)
+      end
+      catalog
+    end
+
+    def self.validated_key!(key)
+      provider, model = canonical_key(key)
+      raise Smith::PricingConfigurationError, "unrecognized pricing catalog key #{key.inspect}" unless model
+      return [provider, model] if provider
+
+      raise Smith::PricingConfigurationError, "pricing for #{model} must use a provider-qualified catalog key"
+    end
+
+    def self.validate_entry!(key, entry)
+      return if entry.is_a?(Hash)
+
+      raise Smith::PricingConfigurationError, "pricing entry for #{key.inspect} must be a Hash"
+    end
+
+    def self.reject_collision!(seen, key, provider, model)
+      previous = seen[[provider, model]]
+      if previous
+        raise Smith::PricingConfigurationError,
+              "pricing catalog keys #{previous.inspect} and #{key.inspect} collide as #{provider}/#{model}"
+      end
+
+      seen[[provider, model]] = key
+    end
+
+    # The catalog is treated as immutable once assigned: normalization
+    # runs once per catalog object and is memoized by identity, so
+    # replacing the catalog means assigning a new Hash.
+    NORMALIZATION_MUTEX = Mutex.new
+    private_constant :NORMALIZATION_MUTEX
+
+    def self.normalized_index(catalog)
+      NORMALIZATION_MUTEX.synchronize do
+        next @normalized_index if defined?(@normalized_source) && @normalized_source.equal?(catalog)
+
+        @normalized_index = build_normalized_index(catalog)
+        @normalized_source = catalog
+        @normalized_index
+      end
+    end
+
+    # Non-raising by design: compute_cost runs inside success and
+    # failure accounting, so unrecognizable keys are skipped (their
+    # usage stays unpriced) rather than raised. `validate_catalog!`
+    # is the raising surface for the same rules.
+    def self.build_normalized_index(catalog)
+      catalog.each_with_object({ qualified: {}, legacy: {} }) do |(key, entry), index|
+        provider, model = canonical_key(key)
+        next unless model
+
+        provider ? (index[:qualified][[provider, model].freeze] = entry) : (index[:legacy][model] = entry)
+      end
+    end
+
+    # Returns [provider_or_nil, model] for a recognized key, nil otherwise.
+    # Mirrors Smith::Agent::ModelReference: the first slash separates
+    # provider from model, so slashed model ids are keyed with an explicit
+    # provider segment ("openrouter/openai/gpt-5" or [provider, model]).
+    def self.canonical_key(key)
+      case key
+      when Array then array_key(key)
+      when String, Symbol then text_key(key.to_s)
+      end
+    end
+
+    def self.array_key(key)
+      provider, model = key.map { |part| scalar_key(part) } if key.length == 2
+      [provider, model] if provider && model
+    end
+
+    def self.text_key(text)
+      return if text.empty?
+      return [nil, text] unless text.include?("/")
+
+      provider, model = text.split("/", 2)
+      [provider, model] unless provider.empty? || model.empty?
+    end
+
+    def self.scalar_key(value)
+      text = value.to_s if value.is_a?(String) || value.is_a?(Symbol)
+      text unless text.nil? || text.empty?
+    end
+
     # Returns [input_rate, output_rate] or nil if no applicable rate.
     # Tiered shape is recognized by the presence of a :tiers key; flat
     # shape is the legacy default.
@@ -40,26 +157,30 @@ module Smith
         resolve_tiered(tiers, input_tokens)
       else
         flat = [entry[:input_cost_per_token], entry[:output_cost_per_token]]
-        return nil unless flat.all? { |r| r.is_a?(Numeric) }
+        return nil unless flat.all?(Numeric)
 
         flat
       end
     end
-    private_class_method :resolve_rates
 
     def self.resolve_tiered(tiers, input_tokens)
-      tier = tiers.find do |t|
-        max = t[:max_input_tokens] || t["max_input_tokens"]
-        max.nil? || input_tokens <= max
-      end
+      tier = tiers.find { |candidate| tier_applies?(candidate, input_tokens) }
       return nil unless tier
 
-      input_rate = tier[:input_cost_per_token] || tier["input_cost_per_token"]
-      output_rate = tier[:output_cost_per_token] || tier["output_cost_per_token"]
-      return nil unless input_rate.is_a?(Numeric) && output_rate.is_a?(Numeric)
+      rates = [
+        tier[:input_cost_per_token] || tier["input_cost_per_token"],
+        tier[:output_cost_per_token] || tier["output_cost_per_token"]
+      ]
+      rates if rates.all?(Numeric)
+    end
 
-      [input_rate, output_rate]
+    def self.tier_applies?(tier, input_tokens)
+      maximum = tier[:max_input_tokens] || tier["max_input_tokens"]
+      maximum.nil? || input_tokens <= maximum
     end
-    private_class_method :resolve_tiered
+
+    private_class_method :lookup_entry, :validated_key!, :validate_entry!, :reject_collision!,
+                         :normalized_index, :build_normalized_index, :canonical_key, :array_key,
+                         :text_key, :scalar_key, :resolve_rates, :resolve_tiered, :tier_applies?
   end
 end

data/lib/smith/pricing_configuration_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "error"
+
+module Smith
+  class PricingConfigurationError < Error; end
+end

data/lib/smith/provider_permanent_failure.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "error"
+
+module Smith
+  class ProviderPermanentFailure < Error
+    attr_reader :provider, :model_id, :source_error_class
+
+    def initialize(message, provider:, model_id:, source_error_class:)
+      @provider = provider&.to_sym
+      @model_id = model_id.to_s.dup.freeze
+      @source_error_class = source_error_class.to_s.dup.freeze
+      super(message)
+    end
+  end
+end

data/lib/smith/tool/argument_container_reader.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Tool < RubyLLM::Tool
+    class ArgumentContainerReader
+      MODULE_MATCH = Module.instance_method(:===)
+      ARRAY_LENGTH = Array.instance_method(:length)
+      ARRAY_AREF = Array.instance_method(:[])
+      ARRAY_INITIALIZE_COPY = Array.instance_method(:initialize_copy)
+      HASH_LENGTH = Hash.instance_method(:length)
+      HASH_KEYS = Hash.instance_method(:keys)
+      HASH_FETCH = Hash.instance_method(:fetch)
+      HASH_INITIALIZE_COPY = Hash.instance_method(:initialize_copy)
+      SYMBOL_TO_S = Symbol.instance_method(:to_s)
+      private_constant :MODULE_MATCH, :ARRAY_LENGTH, :ARRAY_AREF, :ARRAY_INITIALIZE_COPY,
+                       :HASH_LENGTH, :HASH_KEYS, :HASH_FETCH, :HASH_INITIALIZE_COPY, :SYMBOL_TO_S
+
+      extend Dry::Initializer
+
+      option :scalar_snapshot
+      option :byte_count
+
+      def type(value)
+        return :hash if MODULE_MATCH.bind_call(Hash, value)
+
+        :array if MODULE_MATCH.bind_call(Array, value)
+      end
+
+      def size(source, type)
+        type == :hash ? HASH_LENGTH.bind_call(source) : ARRAY_LENGTH.bind_call(source)
+      end
+
+      def snapshot(source, type)
+        target = type == :hash ? Hash.allocate : Array.allocate
+        initializer = type == :hash ? HASH_INITIALIZE_COPY : ARRAY_INITIALIZE_COPY
+        initializer.bind_call(target, source)
+        target.freeze
+      end
+
+      def target(type, size) = type == :hash ? {} : Array.new(size)
+
+      def append_children(pending:, source:, target:, depth:, metrics:)
+        if type(source) == :hash
+          append_hash_children(pending, source, target, depth, metrics)
+        else
+          append_array_children(pending, source, target, depth, metrics)
+        end
+      end
+
+      private
+
+      def append_array_children(pending, source, target, depth, metrics)
+        (ARRAY_LENGTH.bind_call(source) - 1).downto(0) do |index|
+          child = ARRAY_AREF.bind_call(source, index)
+          pending << [:visit, child, target, index, depth + 1, metrics]
+        end
+      end
+
+      def append_hash_children(pending, source, target, depth, metrics)
+        expected_size = HASH_LENGTH.bind_call(source)
+        keys = HASH_KEYS.bind_call(source)
+        unless ARRAY_LENGTH.bind_call(keys) == expected_size
+          raise Error, "tool argument object changed while it was being captured"
+        end
+
+        capture_hash_pairs(source, keys, expected_size, metrics).reverse_each do |key, child|
+          pending << [:visit, child, target, key, depth + 1, metrics]
+        end
+      rescue KeyError
+        raise Error, "tool argument object changed while it was being captured"
+      end
+
+      def capture_hash_pairs(source, keys, expected_size, metrics)
+        pairs = Array.new(expected_size)
+        canonical_keys = {}
+        keys.each_with_index do |source_key, index|
+          copied_key = copy_hash_key(source_key, canonical_keys, metrics)
+          pairs[index] = [copied_key, HASH_FETCH.bind_call(source, source_key)]
+        end
+        pairs
+      end
+
+      def copy_hash_key(key, canonical_keys, metrics)
+        previous_bytes = byte_count.call
+        copied_key = scalar_snapshot.copy_key(key)
+        canonical = MODULE_MATCH.bind_call(String, copied_key) ? copied_key : SYMBOL_TO_S.bind_call(copied_key)
+        raise Error, "tool arguments contain duplicate canonical Hash keys" if canonical_keys.key?(canonical)
+
+        canonical_keys[canonical] = true
+        metrics[:byte_count] += byte_count.call - previous_bytes
+        copied_key
+      end
+    end
+  end
+end

data/lib/smith/tool/argument_scalar_snapshot.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Tool < RubyLLM::Tool
+    class ArgumentScalarSnapshot
+      STRING_BYTESIZE = String.instance_method(:bytesize)
+      STRING_ENCODE = String.instance_method(:encode)
+      STRING_VALID_ENCODING = String.instance_method(:valid_encoding?)
+      MODULE_MATCH = Module.instance_method(:===)
+      DECIMAL_DIGIT_LOWER_BOUND_NUMERATOR = 301
+      DECIMAL_DIGIT_LOWER_BOUND_DENOMINATOR = 1_000
+
+      private_constant :STRING_BYTESIZE, :STRING_ENCODE, :STRING_VALID_ENCODING, :MODULE_MATCH,
+                       :DECIMAL_DIGIT_LOWER_BOUND_NUMERATOR, :DECIMAL_DIGIT_LOWER_BOUND_DENOMINATOR
+
+      extend Dry::Initializer
+
+      option :byte_counter
+      option :byte_validator
+
+      def copy(value)
+        case value
+        when String then copy_string(value)
+        when Integer then copy_integer(value)
+        when TrueClass, FalseClass, NilClass then count(value)
+        when Float then copy_float(value)
+        else
+          raise Error, "tool arguments must contain JSON-compatible values"
+        end
+      end
+
+      def copy_key(key)
+        raise Error, "tool argument object keys must be strings or symbols" unless string?(key) || symbol?(key)
+
+        normalized = if string?(key)
+                       normalize_utf8(key)
+                     else
+                       normalize_utf8(Symbol.instance_method(:to_s).bind_call(key))
+                     end
+        byte_counter.call(normalized.bytesize)
+        string?(key) ? normalized : key
+      end
+
+      private
+
+      def copy_string(value)
+        normalized = normalize_utf8(value)
+        byte_counter.call(normalized.bytesize)
+        normalized
+      end
+
+      def copy_float(value)
+        raise Error, "tool arguments must contain finite numbers" unless value.finite?
+
+        count(value)
+      end
+
+      def copy_integer(value)
+        byte_validator.call(minimum_integer_bytes(value))
+        count(value)
+      end
+
+      def count(value)
+        byte_counter.call(value.to_s.bytesize)
+        value
+      end
+
+      def minimum_integer_bytes(value)
+        bits = value.bit_length
+        digits = if bits.zero?
+                   1
+                 else
+                   (((bits - 1) * DECIMAL_DIGIT_LOWER_BOUND_NUMERATOR) /
+                    DECIMAL_DIGIT_LOWER_BOUND_DENOMINATOR) + 1
+                 end
+        value.negative? ? digits + 1 : digits
+      end
+
+      def normalize_utf8(value)
+        byte_validator.call(STRING_BYTESIZE.bind_call(value))
+        raise Encoding::InvalidByteSequenceError unless STRING_VALID_ENCODING.bind_call(value)
+
+        encoded = STRING_ENCODE.bind_call(value, Encoding::UTF_8)
+        normalized = String.new(encoded).freeze
+        raise Encoding::InvalidByteSequenceError unless STRING_VALID_ENCODING.bind_call(normalized)
+
+        normalized
+      rescue EncodingError
+        raise Error, "tool arguments must contain valid UTF-8 strings"
+      end
+
+      def string?(value) = MODULE_MATCH.bind_call(String, value)
+
+      def symbol?(value) = MODULE_MATCH.bind_call(Symbol, value)
+    end
+  end
+end

data/lib/smith/tool/argument_snapshot.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Tool < RubyLLM::Tool
+    class ArgumentSnapshot
+      MAX_DEPTH = ArgumentSnapshotTraversal::MAX_DEPTH
+      MAX_NODES = ArgumentSnapshotTraversal::MAX_NODES
+      MAX_BYTES = ArgumentSnapshotTraversal::MAX_BYTES
+
+      extend Dry::Initializer
+
+      param :value
+
+      def call = ArgumentSnapshotTraversal.new(value).call
+    end
+  end
+end

data/lib/smith/tool/argument_snapshot_accounting.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Tool < RubyLLM::Tool
+    class ArgumentSnapshotAccounting
+      extend Dry::Initializer
+
+      option :max_depth
+      option :max_nodes
+      option :max_bytes
+
+      attr_reader :node_count, :byte_count
+
+      def initialize(...)
+        super
+        @node_count = 0
+        @allocated_node_count = 1
+        @byte_count = 0
+      end
+
+      def visit!(depth)
+        raise Error, "tool arguments exceed #{max_depth} levels" if depth > max_depth
+
+        add_nodes!(1)
+      end
+
+      def reserve_children!(count)
+        @allocated_node_count += count
+        raise Error, "tool arguments exceed #{max_nodes} values" if @allocated_node_count > max_nodes
+      end
+
+      def add_bytes!(bytes)
+        @byte_count += bytes
+        raise Error, "tool arguments exceed #{max_bytes} bytes" if @byte_count > max_bytes
+      end
+
+      def validate_bytes!(bytes)
+        raise Error, "tool arguments exceed #{max_bytes} bytes" if @byte_count + bytes > max_bytes
+      end
+
+      def account_reused!(metrics, depth)
+        raise Error, "tool arguments exceed #{max_depth} levels" if depth + metrics.fetch(:max_depth) > max_depth
+
+        add_nodes!(metrics.fetch(:node_count) - 1)
+        add_bytes!(metrics.fetch(:byte_count))
+      end
+
+      def propagate!(parent_metrics, child_metrics)
+        return unless parent_metrics
+
+        parent_metrics[:node_count] += child_metrics.fetch(:node_count)
+        parent_metrics[:byte_count] += child_metrics.fetch(:byte_count)
+        parent_metrics[:max_depth] = [
+          parent_metrics[:max_depth],
+          child_metrics.fetch(:max_depth) + 1
+        ].max
+      end
+
+      private
+
+      def add_nodes!(count)
+        @node_count += count
+        raise Error, "tool arguments exceed #{max_nodes} values" if @node_count > max_nodes
+      end
+    end
+  end
+end

data/lib/smith/tool/argument_snapshot_result.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+
+require_relative "../types"
+
+module Smith
+  class Tool < RubyLLM::Tool
+    class ArgumentSnapshotResult < Dry::Struct
+      attribute :value, Types::Hash
+      attribute :node_count, Types::Integer.constrained(gteq: 1)
+      attribute :byte_count, Types::Integer.constrained(gteq: 0)
+    end
+  end
+end