smith-agents 0.4.0

data/lib/smith/doctor/checks/persistence_registry.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Smith
+  module Doctor
+    module Checks
+      module PersistenceRegistry
+        def self.check(report, mode)
+          case mode
+          when :database
+            check_database_registry(report)
+          when :bundled
+            report.add(name: "persistence.model_registry_mode", status: :pass,
+                       message: "Model registry mode: bundled (explicit)")
+          else
+            report.add(
+              name: "persistence.model_registry_mode", status: :pass,
+              message: "Model registry mode: bundled fallback (default)",
+              detail: "Set config.ruby_llm_model_registry = :database if DB-backed registry is required"
+            )
+          end
+        end
+
+        def self.check_database_registry(report)
+          registry_class = resolve_registry_class
+          unless registry_class
+            report.add(name: "persistence.model_registry_mode", status: :fail,
+                       message: "DB-backed model registry required but registry class not resolvable",
+                       detail: "RubyLLM.config.model_registry_class could not be resolved to a constant")
+            return
+          end
+
+          unless ar_backed?(registry_class)
+            report.add(name: "persistence.model_registry_mode", status: :fail,
+                       message: "DB-backed model registry required but class is not ActiveRecord-backed",
+                       detail: "#{registry_class.name} does not inherit from ActiveRecord::Base")
+            return
+          end
+
+          verify_registry_table_and_records(report, registry_class)
+        end
+
+        def self.resolve_registry_class
+          raw = ::RubyLLM.config.model_registry_class
+          return nil unless raw
+
+          klass = raw.is_a?(String) ? Object.const_get(raw) : raw
+          klass.is_a?(Class) ? klass : nil
+        rescue NameError
+          nil
+        end
+
+        def self.ar_backed?(klass)
+          klass.ancestors.any? { |a| a.name&.include?("ActiveRecord::Base") }
+        rescue StandardError
+          false
+        end
+
+        def self.verify_registry_table_and_records(report, registry_class)
+          unless registry_class.table_exists?
+            report.add(name: "persistence.model_registry_mode", status: :fail,
+                       message: "DB-backed model registry table missing",
+                       detail: "#{registry_class.table_name} does not exist")
+            return
+          end
+
+          count = registry_class.count
+          if count.positive?
+            report.add(name: "persistence.model_registry_mode", status: :pass,
+                       message: "DB-backed model registry operational (#{count} records)")
+          else
+            report.add(name: "persistence.model_registry_mode", status: :fail,
+                       message: "DB-backed model registry table exists but is empty",
+                       detail: "Run ruby_llm model sync or seeding task")
+          end
+        rescue StandardError => e
+          report.add(name: "persistence.model_registry_mode", status: :fail,
+                     message: "DB-backed model registry query failed", detail: e.message)
+        end
+      end
+    end
+  end
+end

data/lib/smith/doctor/checks/rails.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Smith
+  module Doctor
+    module Checks
+      module Rails
+        def self.run(report)
+          unless defined?(::Rails)
+            report.add(name: "rails.detected", status: :skip, message: "Rails not detected")
+            return
+          end
+
+          check_application(report)
+          check_smith_config(report)
+        end
+
+        def self.check_application(report)
+          present = defined?(::Rails.application) && !::Rails.application.nil?
+          report.add(
+            name: "rails.application",
+            status: present ? :pass : :fail,
+            message: present ? "Rails application present" : "Rails application not found",
+            detail: present ? nil : "Rails is loaded but no application is defined"
+          )
+        end
+
+        def self.check_smith_config(report)
+          accessible = ::Smith.respond_to?(:config) && !::Smith.config.nil?
+          report.add(
+            name: "rails.smith_config",
+            status: accessible ? :pass : :warn,
+            message: accessible ? "Smith config accessible from Rails" : "Smith config not accessible",
+            detail: accessible ? nil : "Ensure config/initializers/smith.rb exists"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/smith/doctor/checks/serialization.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Smith
+  module Doctor
+    module Checks
+      module Serialization
+        def self.run(report)
+          check_to_state(report)
+          check_json_roundtrip(report)
+          check_from_state(report)
+          check_resume(report)
+        end
+
+        def self.check_to_state(report)
+          state = build_probe_class.new.to_state
+          valid = state.is_a?(Hash) && state.key?(:state) && state.key?(:class)
+          report.add(
+            name: "serialization.to_state",
+            status: valid ? :pass : :fail,
+            message: valid ? "to_state produces valid Hash" : "to_state output is malformed"
+          )
+        rescue StandardError => e
+          report.add(name: "serialization.to_state", status: :fail, message: "to_state failed", detail: e.message)
+        end
+
+        def self.check_json_roundtrip(report)
+          state = build_probe_class.new.to_state
+          parsed = JSON.parse(JSON.generate(state))
+          valid = parsed.is_a?(Hash) && parsed.key?("state")
+          report.add(
+            name: "serialization.json_roundtrip",
+            status: valid ? :pass : :fail,
+            message: valid ? "JSON round-trip preserves state" : "JSON round-trip corrupts state"
+          )
+        rescue StandardError => e
+          report.add(name: "serialization.json_roundtrip", status: :fail, message: "JSON round-trip failed",
+                     detail: e.message)
+        end
+
+        def self.check_from_state(report)
+          klass = build_probe_class
+          parsed = JSON.parse(JSON.generate(klass.new.to_state))
+          restored = klass.from_state(parsed)
+          valid = restored.state == :idle
+          report.add(
+            name: "serialization.from_state",
+            status: valid ? :pass : :fail,
+            message: valid ? "from_state restores workflow" : "from_state produced invalid state"
+          )
+        rescue StandardError => e
+          report.add(name: "serialization.from_state", status: :fail, message: "from_state failed", detail: e.message)
+        end
+
+        def self.check_resume(report)
+          result = build_probe_class.new.run!
+          valid = result.state == :done
+          report.add(
+            name: "serialization.resume",
+            status: valid ? :pass : :fail,
+            message: valid ? "Workflow completes after restore" : "Workflow did not reach terminal state"
+          )
+        rescue StandardError => e
+          report.add(name: "serialization.resume", status: :fail, message: "Resume failed", detail: e.message)
+        end
+
+        def self.build_probe_class
+          Class.new(::Smith::Workflow) do
+            initial_state :idle
+            state :done
+            transition :finish, from: :idle, to: :done
+          end
+        end
+      end
+    end
+  end
+end

data/lib/smith/doctor/installer.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Smith
+  module Doctor
+    class Installer
+      def self.run(io: $stdout)
+        new(io:).install
+      end
+
+      def initialize(io:)
+        @io = io
+      end
+
+      def install
+        write_config_file
+        print_next_steps
+      end
+
+      private
+
+      def write_config_file
+        path = target_path
+        if File.exist?(path)
+          @io.puts "  exists  #{path}"
+          return
+        end
+
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, rails? ? rails_template : plain_template)
+        @io.puts "  create  #{path}"
+      end
+
+      def target_path
+        rails? ? "config/initializers/smith.rb" : "config/smith.rb"
+      end
+
+      def rails?
+        defined?(::Rails::Railtie)
+      end
+
+      def rails_template
+        template_path = File.expand_path("../../generators/smith/install/templates/smith.rb.tt", __dir__)
+        File.read(template_path)
+      end
+
+      def plain_template
+        <<~RUBY
+          # frozen_string_literal: true
+
+          require "logger"
+          require "smith"
+
+          Smith.configure do |config|
+            config.logger = Logger.new($stdout)
+            # Host durability verification / persistence adapter options:
+            # config.persistence_adapter = :cache_store
+            # config.persistence_options = {
+            #   store: SomeCacheStore.new,
+            #   namespace: "smith"
+            # }
+            #
+            # config.persistence_adapter = :redis
+            # config.persistence_options = {
+            #   redis: Redis.new(url: ENV.fetch("REDIS_URL")),
+            #   namespace: "smith"
+            # }
+            #
+            # config.persistence_adapter = :active_record
+            # config.persistence_options = {
+            #   model: WorkflowState,
+            #   key_column: :key,
+            #   payload_column: :payload
+            # }
+            #
+            # Custom adapters are also supported if they implement:
+            #   store(key, payload)
+            #   fetch(key)
+            #   delete(key)
+            config.artifact_store = Smith::Artifacts::Memory.new
+            config.trace_adapter = Smith::Trace::Memory.new
+          end
+        RUBY
+      end
+
+      def print_next_steps
+        @io.puts ""
+        if rails?
+          @io.puts "Smith installed. Next steps:"
+          @io.puts "  1. Configure RubyLLM in config/initializers/ruby_llm.rb"
+          @io.puts "  2. Run: bin/rails smith:doctor"
+        else
+          @io.puts "Smith configured. Next steps:"
+          @io.puts "  1. Configure RubyLLM for your provider"
+          @io.puts "  2. Run: smith doctor"
+        end
+        @io.puts "  3. Define your first agent and workflow"
+        @io.puts ""
+      end
+    end
+  end
+end

data/lib/smith/doctor/printer.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Smith
+  module Doctor
+    class Printer
+      CLEAR  = "\e[0m"
+      BOLD   = "\e[1m"
+      RED    = "\e[31m"
+      GREEN  = "\e[32m"
+      YELLOW = "\e[33m"
+      CYAN   = "\e[36m"
+      WHITE  = "\e[37m"
+
+      ICONS = { pass: "\u2713", fail: "\u2717", warn: "!", skip: "-" }.freeze
+      COLORS = { pass: GREEN, fail: RED, warn: YELLOW, skip: CYAN }.freeze
+
+      def initialize(report, io: $stdout)
+        @report = report
+        @io = io
+      end
+
+      def print
+        @io.puts colorize("\nSmith Doctor\n", BOLD, WHITE)
+        print_grouped_checks
+        print_summary
+      end
+
+      private
+
+      def print_grouped_checks
+        @report.grouped.each do |group, checks|
+          @io.puts colorize("  #{format_group(group)}", BOLD, WHITE)
+          checks.each { |c| print_check(c) }
+          @io.puts
+        end
+      end
+
+      def print_check(check)
+        icon = ICONS.fetch(check.status)
+        color = COLORS.fetch(check.status)
+        @io.puts "    #{colorize(icon, color)} #{check.message}"
+        @io.puts "      #{colorize(check.detail, CYAN)}" if check.detail
+      end
+
+      def print_summary
+        color = @report.passed? ? GREEN : RED
+        @io.puts colorize("  #{@report.summary}", BOLD, color)
+        @io.puts
+      end
+
+      def format_group(group)
+        group.split("_").map(&:capitalize).join(" ")
+      end
+
+      def colorize(text, *codes)
+        return text.to_s unless @io.respond_to?(:tty?) && @io.tty? && ENV["NO_COLOR"].nil?
+
+        "#{codes.join}#{text}#{CLEAR}"
+      end
+    end
+  end
+end

data/lib/smith/doctor/report.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Smith
+  module Doctor
+    class Report
+      attr_reader :checks
+
+      def initialize
+        @checks = []
+      end
+
+      def add(name:, status:, message:, detail: nil)
+        @checks << Check.new(name:, status:, message:, detail:)
+      end
+
+      def passed?
+        checks.none?(&:fail?)
+      end
+
+      def exit_code
+        passed? ? 0 : 1
+      end
+
+      def grouped
+        checks.group_by { |c| c.name.split(".").first }
+      end
+
+      def summary
+        counts = checks.group_by(&:status).transform_values(&:size)
+        parts = []
+        parts << "#{counts.fetch(:pass, 0)} passed"
+        parts << "#{counts[:warn]} warnings" if counts[:warn]
+        parts << "#{counts[:fail]} failed" if counts[:fail]
+        parts << "#{counts[:skip]} skipped" if counts[:skip]
+        parts.join(", ")
+      end
+    end
+  end
+end

data/lib/smith/doctor.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "doctor/check"
+require_relative "doctor/report"
+require_relative "doctor/printer"
+require_relative "doctor/installer"
+require_relative "doctor/checks/baseline"
+require_relative "doctor/checks/configuration"
+require_relative "doctor/checks/rails"
+require_relative "doctor/checks/persistence"
+require_relative "doctor/checks/persistence_registry"
+require_relative "doctor/checks/serialization"
+require_relative "doctor/checks/durability"
+require_relative "doctor/checks/live"
+require_relative "doctor/checks/models_registry"
+require_relative "doctor/checks/openai_api_mode"
+require_relative "doctor/checks/persistence_capabilities"
+
+module Smith
+  module Doctor
+    def self.run(profile: :auto, live: false, durability: false, io: $stdout)
+      report = Report.new
+
+      Checks::Baseline.run(report)
+      Checks::Configuration.run(report)
+      Checks::ModelsRegistry.run(report)
+      Checks::OpenaiApiMode.run(report)
+      Checks::Rails.run(report) if detect_rails?
+      Checks::Persistence.run(report) if persistence_profile?(profile)
+      Checks::PersistenceCapabilities.run(report) if persistence_profile?(profile)
+      if durability || durability_profile?(profile)
+        Checks::Serialization.run(report)
+        Checks::Durability.run(report)
+      end
+      Checks::Live.run(report) if live
+
+      Printer.new(report, io:).print
+      report
+    end
+
+    def self.detect_rails?
+      defined?(::Rails::Railtie)
+    end
+
+    def self.persistence_profile?(profile)
+      profile == :rails_persistence
+    end
+
+    def self.durability_profile?(profile)
+      profile == :durable
+    end
+  end
+end

data/lib/smith/errors.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module Smith
+  # Classification surface for host retry policies. Smith owns the
+  # answer to "should the workflow attempt be retried?" so consumers
+  # don't reimplement the case statement in every Execution / Job.
+  module Errors
+    # Returns true when the host should retry the workflow attempt.
+    # AgentError + DeadlineExceeded are always retryable.
+    # DeterministicStepFailure + ToolGuardrailFailed honor their
+    # `retryable` attribute (opt-in at the raise site).
+    # All other Smith errors and non-Smith errors return false.
+    def self.retryable?(error)
+      return false if error.nil?
+
+      case error
+      when Smith::DeterministicStepFailure, Smith::ToolGuardrailFailed
+        error.retryable == true
+      when Smith::AgentError, Smith::DeadlineExceeded
+        true
+      else
+        false
+      end
+    end
+
+    # Always-retryable error classes for explicit ActiveJob retry_on
+    # allow-lists. Excludes the retryable-bearing families because
+    # their retryability is per-raise, not per-class.
+    def self.retryable_classes
+      [Smith::AgentError, Smith::DeadlineExceeded].freeze
+    end
+  end
+
+  class BudgetExceeded < Error; end
+  class DeadlineExceeded < Error; end
+  class MaxTransitionsExceeded < Error; end
+  class GuardrailFailed < Error; end
+  class ToolGuardrailFailed < Error
+    attr_reader :retryable
+
+    def initialize(message, retryable: nil)
+      @retryable = retryable
+      super(message)
+    end
+  end
+  class ToolPolicyDenied < Error; end
+  class AgentError < Error; end
+  class BlankAgentOutputError < AgentError
+    attr_reader :agent_name, :model_used
+
+    def initialize(agent_name:, model_used:)
+      @agent_name = agent_name
+      @model_used = model_used
+
+      detail = +"agent"
+      detail << " :#{agent_name}" if agent_name
+      detail << " returned blank output"
+      detail << " from model #{model_used}" if model_used
+
+      super(detail)
+    end
+  end
+  class WorkflowError < Error; end
+
+  class DeterministicStepFailure < WorkflowError
+    attr_reader :retryable, :kind, :details
+
+    def initialize(message, retryable: nil, kind: nil, details: nil)
+      @retryable = retryable
+      @kind = kind
+      @details = details
+      super(message)
+    end
+  end
+
+  class UnresolvedTransitionError < WorkflowError
+    attr_reader :requested_name, :workflow_class, :origin_state
+
+    def initialize(requested_name, workflow_class, origin_state)
+      @requested_name = requested_name
+      @workflow_class = workflow_class
+      @origin_state = origin_state
+      super("unresolved transition :#{requested_name} in #{workflow_class} from state :#{origin_state}")
+    end
+  end
+
+  class SerializationError < Error; end
+  class AgentRegistryError < Error; end
+
+  # Raised after persistence retry attempts are exhausted. Wraps the
+  # underlying I/O cause (Redis connection error, AR connection error,
+  # cache backend error) so hosts can distinguish a true I/O failure
+  # from a programmatic error.
+  class PersistenceIOError < Error
+    attr_reader :operation, :cause
+
+    def initialize(operation:, cause:)
+      @operation = operation
+      @cause = cause
+      super("persistence I/O error during #{operation}: #{cause.class}: #{cause.message}")
+    end
+  end
+
+  # Raised when an adapter's optimistic-lock check detects a concurrent
+  # write: another process modified the key between this process's
+  # restore and persist. Hosts can rescue + restore + retry, or fail
+  # the workflow run with explicit conflict semantics.
+  class PersistenceVersionConflict < Error
+    attr_reader :key, :expected, :actual
+
+    def initialize(key:, expected:, actual:)
+      @key = key
+      @expected = expected
+      @actual = actual
+      super("persistence version conflict for #{key.inspect}: expected v#{expected}, got #{actual.inspect}")
+    end
+  end
+
+  # Raised when restore detects that the workflow's seed_messages
+  # builder now produces a different digest than what was persisted
+  # (i.e., the system prompt or seed template changed in code after this
+  # workflow was already running). Only fires when the workflow opts into
+  # `seed_validation :strict`; the default `:off` skips validation and
+  # `:warn` logs without raising.
+  class SeedMismatch < Error
+    attr_reader :workflow, :stored_digest, :current_digest
+
+    def initialize(workflow:, stored_digest:, current_digest:)
+      @workflow = workflow
+      @stored_digest = stored_digest
+      @current_digest = current_digest
+      super(
+        "seed_messages drift detected for #{workflow}: stored digest #{stored_digest.inspect}, " \
+        "current digest #{current_digest.inspect}. The seed_messages block changed after this " \
+        "workflow was persisted. Restoring this state would mix old + new prompt context."
+      )
+    end
+  end
+
+  # Raised on restore when the persisted payload has the
+  # step_in_progress marker set AND the workflow class opted into
+  # `idempotency_mode :strict`. Signals that a previous worker crashed
+  # between `persist!` (before advance) and `persist!` (after advance);
+  # the step's effects are unknown, so blindly re-running could
+  # double-execute non-idempotent agent calls or tools.
+  class StepInProgressOnRestore < Error
+    attr_reader :workflow, :persistence_key
+
+    def initialize(workflow:, persistence_key:)
+      @workflow = workflow
+      @persistence_key = persistence_key
+      super(
+        "step in progress on restore for #{workflow} key=#{persistence_key.inspect}: " \
+        "a previous worker crashed mid-step. Hosts using idempotency_mode :strict must " \
+        "decide whether to clear the persisted state (idempotent re-run unsafe) or " \
+        "switch to :lax (assume re-run is safe)."
+      )
+    end
+  end
+
+  # Raised when restoring a persisted payload whose schema_version does
+  # not match the workflow's current persistence_schema_version AND no
+  # migration block is registered to bridge the gap. Hosts fix this by
+  # adding `migrate_from(stored) do |payload| ... end` to the workflow
+  # class, or by bumping persistence_schema_version to match the stored
+  # version. Downgrades (stored > current) always raise; Smith has no
+  # rollback semantics.
+  class PersistenceSchemaMismatch < Error
+    attr_reader :workflow, :stored, :current
+
+    def initialize(workflow:, stored:, current:)
+      @workflow = workflow
+      @stored = stored
+      @current = current
+      super(format_message(workflow, stored, current))
+    end
+
+    private
+
+    def format_message(workflow, stored, current)
+      base = "schema mismatch restoring #{workflow}: stored v#{stored}, current v#{current}."
+      if stored > current
+        base + " Downgrade is not supported (stored state is ahead of the current code). " \
+               "Bump persistence_schema_version to at least #{stored} or roll the code forward."
+      else
+        base + " Declare `migrate_from(#{stored})` to bridge the gap, or bump persistence_schema_version " \
+               "back to #{stored} if this version was rolled out by mistake."
+      end
+    end
+  end
+end

data/lib/smith/event.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+require "securerandom"
+
+module Smith
+  class Event < Dry::Struct
+    attribute(:execution_id, Types::String.default { SecureRandom.uuid })
+    attribute(:trace_id, Types::String.default { SecureRandom.uuid })
+  end
+end