smith-agents 0.4.0

data/lib/smith/models.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "dry-container"
+require "monitor"
+
+module Smith
+  # Capability registry for model ids. Decoupled from Smith.config.pricing
+  # (per-installation billing) — this catalog describes payload-shape
+  # capabilities (thinking encoding, temperature acceptance, endpoint
+  # preferences for tools+thinking).
+  #
+  # The library ships NO specific model_id declarations. Smith::Models::Inference
+  # provides PATTERN-BASED PROVIDER RULES that match model_ids at runtime
+  # (e.g., "Anthropic Opus 4.7+ uses adaptive thinking"). Applications register
+  # explicit Profile overrides via Smith::Models.register ONLY when they have
+  # a custom model that diverges from its provider's default behavior.
+  #
+  # Resolution order in find_or_infer(model_id):
+  #   1. Application-registered explicit Profile (override wins)
+  #   2. Library Inference rule match
+  #   3. Safe default (no thinking, accepts temp, no routing)
+  module Models
+    extend Dry::Container::Mixin
+
+    class CollisionError < Smith::Error; end
+
+    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)
+    end
+
+    def self.infer(model_id, provider: nil)
+      inferred = Inference.profile_for(model_id) if defined?(Inference)
+      return inferred if inferred
+
+      Profile.new(
+        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
+      )
+    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
+
+        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
+    end
+
+    PROVIDER_PATTERNS = {
+      anthropic: /\Aclaude/i,
+      openai:    /\A(gpt|o\d)/i,
+      gemini:    /\Agemini/i
+    }.freeze
+    private_constant :PROVIDER_PATTERNS
+
+    def self.guess_provider(model_id)
+      key = normalize_key(model_id)
+      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/persistence_adapters/active_record_store.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Smith
+  module PersistenceAdapters
+    class ActiveRecordStore
+      # AR transient errors resolved via class-name guard so Smith
+      # doesn't require activerecord at load time. Hosts that use this
+      # adapter already have activerecord in their dep tree.
+      TRANSIENT_ERROR_NAMES = %w[
+        ActiveRecord::ConnectionNotEstablished
+        ActiveRecord::StatementInvalid
+        ActiveRecord::TransactionIsolationConflict
+      ].freeze
+
+      def self.transient_errors
+        TRANSIENT_ERROR_NAMES.filter_map do |name|
+          Object.const_get(name)
+        rescue NameError
+          nil
+        end
+      end
+
+      def initialize(model:, key_column: :key, payload_column: :payload, version_column: :lock_version)
+        @model_source = model
+        @key_column = key_column
+        @payload_column = payload_column
+        @version_column = version_column
+      end
+
+      def store(key, payload, ttl: nil) # rubocop:disable Lint/UnusedMethodArgument
+        # TTL is deferred for ActiveRecordStore — would require an
+        # `expires_at` column + a periodic sweeper job. Ignored here;
+        # documented as a known limitation.
+        Retry.with_retries(operation: :store, transient: self.class.transient_errors) do
+          record = model_class.find_or_initialize_by(@key_column => key)
+          record.public_send(:"#{@payload_column}=", payload)
+          record.save!
+        end
+      end
+
+      def fetch(key)
+        Retry.with_retries(operation: :fetch, transient: self.class.transient_errors) do
+          model_class.find_by(@key_column => key)&.public_send(@payload_column)
+        end
+      end
+
+      def delete(key)
+        Retry.with_retries(operation: :delete, transient: self.class.transient_errors) do
+          model_class.where(@key_column => key).delete_all
+        end
+      end
+
+      # Optimistic locking via Rails' built-in optimistic locking on the
+      # `lock_version` column. Requires the AR model to have a
+      # `lock_version` (or configured) integer column with default 0.
+      # If absent, raises ArgumentError directing the host to migrate.
+      def store_versioned(key, payload, expected_version:, ttl: nil) # rubocop:disable Lint/UnusedMethodArgument
+        unless model_class.column_names.include?(@version_column.to_s)
+          raise ArgumentError,
+                "ActiveRecordStore#store_versioned requires a #{@version_column} column on " \
+                "#{model_class.name}. Add via: " \
+                "add_column :#{model_class.table_name}, :#{@version_column}, :integer, default: 0"
+        end
+
+        Retry.with_retries(operation: :store_versioned, transient: self.class.transient_errors) do
+          record = model_class.find_or_initialize_by(@key_column => key)
+          if record.persisted? && record.public_send(@version_column) != expected_version
+            raise Smith::PersistenceVersionConflict.new(
+              key: key, expected: expected_version, actual: record.public_send(@version_column)
+            )
+          end
+          record.public_send(:"#{@payload_column}=", payload)
+          record.save!
+        rescue defined?(::ActiveRecord::StaleObjectError) ? ::ActiveRecord::StaleObjectError : StandardError => e
+          raise unless defined?(::ActiveRecord::StaleObjectError) && e.is_a?(::ActiveRecord::StaleObjectError)
+
+          raise Smith::PersistenceVersionConflict.new(
+            key: key, expected: expected_version, actual: :concurrent
+          )
+        end
+      end
+
+      private
+
+      def model_class
+        @model_class ||= begin
+          case @model_source
+          when String
+            Object.const_get(@model_source)
+          else
+            @model_source
+          end
+        rescue NameError => e
+          raise ArgumentError, "ActiveRecord model #{@model_source.inspect} could not be resolved: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/smith/persistence_adapters/cache_store.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Smith
+  module PersistenceAdapters
+    class CacheStore
+      # Cache backends vary widely; the transient list is intentionally
+      # broad. Hosts using a specific backend can subclass and tighten.
+      # NOTE: NO store_versioned implementation — cache backends don't
+      # have uniform CAS semantics. Workflow#persist! checks via
+      # respond_to? and falls back to non-versioned store + warning.
+      TRANSIENT_ERRORS = [
+        Errno::ECONNREFUSED,
+        Errno::ETIMEDOUT,
+        Errno::EPIPE,
+        IOError
+      ].freeze
+
+      def initialize(store:, namespace: "smith")
+        @store_source = store
+        @namespace = namespace
+      end
+
+      def store(key, payload, ttl: Smith.config.persistence_ttl)
+        Retry.with_retries(operation: :store, transient: TRANSIENT_ERRORS) do
+          if ttl
+            backend.write(namespaced(key), payload, expires_in: ttl)
+          else
+            backend.write(namespaced(key), payload)
+          end
+        end
+      end
+
+      def fetch(key)
+        Retry.with_retries(operation: :fetch, transient: TRANSIENT_ERRORS) do
+          backend.read(namespaced(key))
+        end
+      end
+
+      def delete(key)
+        Retry.with_retries(operation: :delete, transient: TRANSIENT_ERRORS) do
+          backend.delete(namespaced(key))
+        end
+      end
+
+      def backend_name
+        backend.class.name || backend.class.to_s
+      end
+
+      def durability_warning
+        process_local_backend_warning
+      end
+
+      private
+
+      def backend
+        @backend ||= begin
+          store = @store_source.respond_to?(:call) ? @store_source.call : @store_source
+          raise ArgumentError, "cache store is required" unless store
+
+          store
+        end
+      end
+
+      def namespaced(key)
+        [@namespace, key].compact.join(":")
+      end
+
+      def process_local_backend_warning
+        return nil unless process_local_memory_backend?
+
+        "#{backend_name} is process-local memory and will not survive restarts"
+      end
+
+      def process_local_memory_backend?
+        backend_name.end_with?("MemoryStore")
+      end
+    end
+  end
+end

data/lib/smith/persistence_adapters/memory.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Smith
+  module PersistenceAdapters
+    # In-process Hash adapter. Thread-safe via Monitor. No I/O, no
+    # transient errors. Designed for tests and quick smoke runs.
+    #
+    # Tracks TTL via stamped expiry times so it behaves consistently with
+    # other adapters' TTL semantics. Implements `store_versioned` via the
+    # monitor, enabling optimistic-locking tests without Redis.
+    #
+    # Auto-selected by Smith.persistence_adapter when both
+    # Smith.config.persistence_adapter is nil AND Smith.config.test_mode
+    # is true (typically set in spec_helper.rb).
+    class Memory
+      def initialize
+        @store = {}
+        @heartbeats = {}
+        @monitor = Monitor.new
+      end
+
+      def store(key, payload, ttl: Smith.config.persistence_ttl)
+        @monitor.synchronize do
+          @store[key] = { payload: payload, expires_at: ttl ? Time.now.utc + ttl : nil }
+        end
+      end
+
+      def fetch(key)
+        @monitor.synchronize do
+          entry = @store[key]
+          next nil if entry.nil?
+
+          if entry[:expires_at] && entry[:expires_at] < Time.now.utc
+            @store.delete(key)
+            next nil
+          end
+
+          entry[:payload]
+        end
+      end
+
+      def delete(key)
+        @monitor.synchronize do
+          @store.delete(key)
+          @heartbeats.delete(key)
+        end
+      end
+
+      def record_heartbeat(key, ttl: Smith.config.persistence_ttl)
+        @monitor.synchronize do
+          @heartbeats[key] = { at: Time.now.utc, expires_at: ttl ? Time.now.utc + ttl : nil }
+        end
+      end
+
+      def last_heartbeat(key)
+        @monitor.synchronize do
+          entry = @heartbeats[key]
+          next nil if entry.nil?
+
+          if entry[:expires_at] && entry[:expires_at] < Time.now.utc
+            @heartbeats.delete(key)
+            next nil
+          end
+
+          entry[:at]
+        end
+      end
+
+      # Optimistic locking via Monitor-synchronized version compare.
+      # Raises Smith::PersistenceVersionConflict when the stored payload's
+      # version differs from expected_version. The version is read from
+      # the payload's JSON `persistence_version` field (same shape Redis
+      # and ActiveRecord stores use, so the contract is consistent
+      # across all versioned adapters).
+      def store_versioned(key, payload, expected_version:, ttl: Smith.config.persistence_ttl)
+        @monitor.synchronize do
+          entry = @store[key]
+          if entry
+            current_version = parse_version(entry[:payload])
+            if current_version != expected_version
+              raise Smith::PersistenceVersionConflict.new(
+                key: key, expected: expected_version, actual: current_version
+              )
+            end
+          end
+          @store[key] = { payload: payload, expires_at: ttl ? Time.now.utc + ttl : nil }
+        end
+      end
+
+      def clear!
+        @monitor.synchronize { @store.clear }
+      end
+
+      private
+
+      def parse_version(payload)
+        JSON.parse(payload).fetch("persistence_version", 0)
+      rescue JSON::ParserError
+        0
+      end
+    end
+  end
+end

data/lib/smith/persistence_adapters/rails_cache.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Smith
+  module PersistenceAdapters
+    class RailsCache < CacheStore
+      def initialize(store: nil, namespace: "smith")
+        super(store: store || method(:default_store), namespace:)
+      end
+
+      private
+
+      def default_store
+        cache = defined?(::Rails) && ::Rails.respond_to?(:cache) ? ::Rails.cache : nil
+        raise ArgumentError, "Rails.cache is not available" unless cache
+
+        cache
+      end
+    end
+  end
+end

data/lib/smith/persistence_adapters/redis_store.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Smith
+  module PersistenceAdapters
+    class RedisStore
+      # Redis transient errors — narrow list; non-transient errors
+      # (CommandError, etc.) propagate up immediately. Pattern matches
+      # Redis::BaseConnectionError if loaded (covers Connection/Timeout)
+      # via class-name guard so Smith doesn't require redis at load time.
+      TRANSIENT_ERROR_NAMES = %w[
+        Redis::BaseConnectionError
+        Redis::TimeoutError
+        Redis::CannotConnectError
+        Redis::ConnectionError
+      ].freeze
+
+      def self.transient_errors
+        TRANSIENT_ERROR_NAMES.filter_map do |name|
+          Object.const_get(name)
+        rescue NameError
+          nil
+        end + [Errno::ECONNREFUSED, Errno::ETIMEDOUT, Errno::EPIPE]
+      end
+
+      def initialize(redis:, namespace: "smith")
+        @redis_source = redis
+        @namespace = namespace
+      end
+
+      def store(key, payload, ttl: Smith.config.persistence_ttl)
+        Retry.with_retries(operation: :store, transient: self.class.transient_errors) do
+          if ttl
+            client.set(namespaced(key), payload, ex: ttl)
+          else
+            client.set(namespaced(key), payload)
+          end
+        end
+      end
+
+      def fetch(key)
+        Retry.with_retries(operation: :fetch, transient: self.class.transient_errors) do
+          client.get(namespaced(key))
+        end
+      end
+
+      def delete(key)
+        Retry.with_retries(operation: :delete, transient: self.class.transient_errors) do
+          client.del(namespaced(key), namespaced_heartbeat(key))
+        end
+      end
+
+      def record_heartbeat(key, ttl: Smith.config.persistence_ttl)
+        Retry.with_retries(operation: :record_heartbeat, transient: self.class.transient_errors) do
+          iso = Time.now.utc.iso8601
+          if ttl
+            client.set(namespaced_heartbeat(key), iso, ex: ttl)
+          else
+            client.set(namespaced_heartbeat(key), iso)
+          end
+        end
+      end
+
+      def last_heartbeat(key)
+        Retry.with_retries(operation: :last_heartbeat, transient: self.class.transient_errors) do
+          raw = client.get(namespaced_heartbeat(key))
+          next nil if raw.nil?
+
+          Time.parse(raw).utc
+        rescue ArgumentError
+          nil
+        end
+      end
+
+      # Optimistic locking via Redis WATCH/MULTI/EXEC. Raises
+      # Smith::PersistenceVersionConflict on a stale expected_version
+      # OR on EXEC failure (WATCH detected concurrent write).
+      def store_versioned(key, payload, expected_version:, ttl: Smith.config.persistence_ttl)
+        Retry.with_retries(operation: :store_versioned, transient: self.class.transient_errors) do
+          namespaced_key = namespaced(key)
+          result = client.watch(namespaced_key) do
+            current = client.get(namespaced_key)
+            if current && (current_version = parse_version(current)) != expected_version
+              client.unwatch
+              raise Smith::PersistenceVersionConflict.new(
+                key: key, expected: expected_version, actual: current_version
+              )
+            end
+
+            client.multi do |tx|
+              if ttl
+                tx.set(namespaced_key, payload, ex: ttl)
+              else
+                tx.set(namespaced_key, payload)
+              end
+            end
+          end
+
+          if result.nil?
+            raise Smith::PersistenceVersionConflict.new(
+              key: key, expected: expected_version, actual: :concurrent
+            )
+          end
+
+          result
+        end
+      end
+
+      private
+
+      def client
+        @client ||= begin
+          resolved = @redis_source.respond_to?(:call) ? @redis_source.call : @redis_source
+          raise ArgumentError, "Redis client is required" unless resolved
+
+          resolved
+        end
+      end
+
+      def namespaced(key)
+        [@namespace, key].compact.join(":")
+      end
+
+      def namespaced_heartbeat(key)
+        [@namespace, "heartbeat", key].compact.join(":")
+      end
+
+      def parse_version(payload)
+        JSON.parse(payload).fetch("persistence_version", 0)
+      rescue JSON::ParserError
+        0
+      end
+    end
+  end
+end

data/lib/smith/persistence_adapters/retry.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Smith
+  module PersistenceAdapters
+    # Generic retry-with-exponential-backoff wrapper used by adapter
+    # store/fetch/delete/store_versioned operations to survive transient
+    # I/O errors. After attempts exhausted, raises Smith::PersistenceIOError
+    # wrapping the underlying cause.
+    #
+    # Adapter-agnostic: each adapter passes its own `transient:` error
+    # class list because Redis transient errors differ from AR transient
+    # errors differ from cache-backend transient errors. The Memory
+    # adapter passes an empty list (it never raises transient errors).
+    module Retry
+      module_function
+
+      def with_retries(operation:, transient:, policy: Smith.config.persistence_retry_policy,
+                       logger: Smith.config.logger)
+        attempts = policy.fetch(:attempts, 3)
+        base = policy.fetch(:base_delay, 0.1)
+        max_delay = policy.fetch(:max_delay, 1.0)
+        last_error = nil
+
+        attempts.times do |i|
+          return yield
+        rescue *transient => e
+          last_error = e
+          break if i == attempts - 1
+
+          delay = [base * (2**i), max_delay].min
+          logger&.warn(
+            "Smith::PersistenceAdapters::Retry #{operation} attempt #{i + 1}/#{attempts} failed: " \
+            "#{e.class}: #{e.message}; sleeping #{delay}s"
+          )
+          sleep(delay)
+        end
+
+        raise Smith::PersistenceIOError.new(operation: operation, cause: last_error)
+      end
+    end
+  end
+end