igniter 0.5.0 → 0.5.2

data/lib/igniter/agents/pipeline/batch_processor_agent.rb

@@ -1,131 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Agents
-    # Processes items in configurable batches with error tracking.
-    #
-    # Items are enqueued via :enqueue and processed synchronously via
-    # :process_next (one batch) or :drain (all remaining items).
-    # Failed items are tracked with their errors for inspection.
-    #
-    # @example
-    #   processor = ->(item:) { DataStore.upsert(item) }
-    #
-    #   ref = BatchProcessorAgent.start(initial_state: { batch_size: 50 })
-    #   ref.send(:enqueue, items: records, callable: processor)
-    #   ref.send(:drain)
-    #
-    #   status = ref.call(:status)
-    #   puts "processed=#{status.processed} failed=#{status.failed}"
-    class BatchProcessorAgent < Igniter::Agent
-      # Returned by the sync :status query.
-      Status = Struct.new(:queue_size, :processed, :failed, keyword_init: true)
-
-      initial_state queue: [], processed: 0, failed: 0, errors: [], batch_size: 10
-
-      # Add items to the processing queue.
-      #
-      # Payload keys:
-      #   items    [Array]  — required; items to process
-      #   callable [#call]  — receives (item:); required unless set via :configure
-      on :enqueue do |state:, payload:|
-        items    = Array(payload.fetch(:items))
-        callable = payload[:callable] || state[:callable]
-        raise ArgumentError, ":callable required" unless callable
-
-        jobs     = items.map { |item| { item: item, callable: callable } }
-        state.merge(queue: state[:queue] + jobs)
-      end
-
-      # Process the next batch_size items.
-      #
-      # Payload keys:
-      #   batch_size [Integer] — override class default (optional)
-      on :process_next do |state:, payload:|
-        size  = payload.fetch(:batch_size, state[:batch_size])
-        agent = new
-        agent.send(:run_batch, state, size)
-      end
-
-      # Process all remaining items synchronously (blocks until queue is empty).
-      on :drain do |state:, payload:|
-        size  = payload.fetch(:batch_size, state[:batch_size])
-        agent = new
-        agent.send(:run_all, state, size)
-      end
-
-      # Sync status query.
-      #
-      # @return [Status]
-      on :status do |state:, **|
-        Status.new(
-          queue_size: state[:queue].size,
-          processed:  state[:processed],
-          failed:     state[:failed]
-        )
-      end
-
-      # Return error log for failed items.
-      #
-      # @return [Array<Hash>]
-      on :errors do |state:, **|
-        state[:errors]
-      end
-
-      # Reset counters and clear errors (queue is preserved).
-      on :reset_stats do |state:, **|
-        state.merge(processed: 0, failed: 0, errors: [])
-      end
-
-      # Set default batch_size and/or default callable.
-      #
-      # Payload keys:
-      #   batch_size [Integer]  — new default
-      #   callable   [#call]    — new default callable
-      on :configure do |state:, payload:|
-        state.merge(
-          batch_size: payload.fetch(:batch_size, state[:batch_size]),
-          callable:   payload.fetch(:callable, state[:callable])
-        )
-      end
-
-      private
-
-      def run_batch(state, size)
-        batch     = state[:queue].first(size)
-        remaining = state[:queue].drop(size)
-        result    = process_jobs(batch)
-        apply_result(state, remaining, result)
-      end
-
-      def run_all(state, size)
-        current = state
-        current = run_batch(current, size) until current[:queue].empty?
-        current
-      end
-
-      def process_jobs(batch)
-        processed = 0
-        failed    = 0
-        errors    = []
-        batch.each do |job|
-          job[:callable].call(item: job[:item])
-          processed += 1
-        rescue StandardError => e
-          failed += 1
-          errors << { item: job[:item], error: e.message }
-        end
-        { processed: processed, failed: failed, errors: errors }
-      end
-
-      def apply_result(state, remaining, result)
-        state.merge(
-          queue:     remaining,
-          processed: state[:processed] + result[:processed],
-          failed:    state[:failed]    + result[:failed],
-          errors:    state[:errors]    + result[:errors]
-        )
-      end
-    end
-  end
-end

data/lib/igniter/agents/proactive_agent.rb

@@ -1,208 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../integrations/agents"
-
-module Igniter
-  module Agents
-    # Base class for proactive (self-initiating) agents.
-    #
-    # A reactive agent waits for messages. A *proactive* agent acts without
-    # being asked — it polls conditions on a schedule, evaluates triggers, and
-    # fires actions when conditions are met.
-    #
-    # == Design
-    #
-    # ProactiveAgent extends the standard Agent DSL with four new keywords:
-    #
-    #   intent      "Human-readable description of the agent's mission"
-    #   scan_interval 5.0          # seconds between automatic scans
-    #   watch  :metric, poll: ->   # callable returning a current reading
-    #   trigger :name,             # rule: condition + action
-    #     condition: ->(ctx) { ... },
-    #     action:    ->(state:, context:) { ... }
-    #
-    # == Execution model
-    #
-    # Every +scan_interval+ seconds the agent's timer fires +:_scan+, which:
-    #   1. Calls each registered watcher to build a +context+ snapshot.
-    #   2. Evaluates every trigger's +condition+ against the context.
-    #   3. Calls the +action+ of every condition that returns truthy.
-    #   4. Merges context, scan count, and fired-trigger history into state.
-    #
-    # +:_scan+ can also be invoked programmatically (useful in specs):
-    #   described_class.handlers[:_scan].call(state: state, payload: {})
-    #
-    # == Built-in message handlers (injected into every subclass)
-    #
-    #   :_scan           — run one scan cycle
-    #   :pause           — suspend automatic reactions (scans still run)
-    #   :resume          — resume reactions
-    #   :status          — sync query → Status struct
-    #   :context         — sync query → last context snapshot Hash
-    #   :trigger_history — sync query → Array<FiredTrigger>
-    #
-    # == Initial state
-    #
-    # Call +proactive_initial_state+ instead of +initial_state+ to include
-    # the required ProactiveAgent keys while also adding your own:
-    #
-    #   proactive_initial_state queue: [], threshold: 0.9
-    #
-    # == Example
-    #
-    #   class ErrorRateMonitor < Igniter::Agents::ProactiveAgent
-    #     intent "Alert when error rate exceeds 5%"
-    #     scan_interval 10.0
-    #
-    #     watch :error_rate, poll: -> { ErrorMetrics.current_rate }
-    #
-    #     trigger :high_errors,
-    #       condition: ->(ctx) { ctx[:error_rate].to_f > 0.05 },
-    #       action:    ->(state:, context:) {
-    #         Notifier.alert("Error rate: #{context[:error_rate]}")
-    #         state.merge(last_alert_at: Time.now)
-    #       }
-    #
-    #     proactive_initial_state last_alert_at: nil
-    #   end
-    #
-    #   ref = ErrorRateMonitor.start
-    #   ref.call(:status)   # => Status(active: true, scan_count: 0, ...)
-    #
-    class ProactiveAgent < Igniter::Agent
-      # Recorded when a trigger fires during a scan cycle.
-      FiredTrigger = Struct.new(:name, :fired_at, :context, keyword_init: true)
-
-      # Returned by the +:status+ sync query.
-      Status = Struct.new(:active, :scan_count, :intent,
-                          :watchers, :triggers, :last_scan_at,
-                          keyword_init: true)
-
-      class << self
-        # ── DSL ─────────────────────────────────────────────────────────────
-
-        # Declare the agent's human-readable mission (metadata only).
-        def intent(desc = nil)
-          return @intent if desc.nil?
-
-          @intent = desc
-        end
-
-        # Set the scan interval in seconds and register the recurring timer.
-        # The timer delegates to the +:_scan+ message handler so both the
-        # production path and specs share identical logic.
-        def scan_interval(seconds)
-          klass = self
-          schedule(:_scan, every: seconds.to_f) do |state:|
-            h = klass.handlers[:_scan]
-            h ? h.call(state: state, payload: {}) : nil
-          end
-        end
-
-        # Register a watcher: a named, zero-argument callable that returns a
-        # current reading of some value.  Called at the start of every scan.
-        #
-        # @param name [Symbol]
-        # @param poll [#call]  — should never raise (errors are rescued to nil)
-        def watch(name, poll:)
-          (@watchers ||= {})[name.to_sym] = poll
-        end
-
-        # Register a trigger: evaluated on every scan cycle.
-        # +condition+ receives the context Hash; +action+ receives
-        # +state:+ and +context:+ and must return a new state Hash or nil.
-        #
-        # @param name      [Symbol]
-        # @param condition [#call]  — (ctx) → truthy/falsy
-        # @param action    [#call]  — (state:, context:) → Hash | nil
-        def trigger(name, condition:, action:)
-          (@proactive_triggers ||= {})[name.to_sym] = {
-            condition: condition,
-            action:    action
-          }
-        end
-
-        # Read accessors (safe even before any DSL calls).
-        def watchers            = @watchers           || {}
-        def proactive_triggers  = @proactive_triggers || {}
-
-        # Convenience: set the initial state including the ProactiveAgent keys.
-        # Use instead of +initial_state+ to avoid forgetting required keys.
-        #
-        # @param extra [Hash]  additional subclass-specific keys
-        def proactive_initial_state(extra = {})
-          initial_state({
-            active:          true,
-            context:         {},
-            scan_count:      0,
-            last_scan_at:    nil,
-            trigger_history: []
-          }.merge(extra))
-        end
-
-        # ── Inheritance ──────────────────────────────────────────────────────
-
-        def inherited(subclass)
-          super  # Agent.inherited: resets @handlers, @timers, @default_state, …
-          inject_proactive_handlers!(subclass)
-        end
-
-        private
-
-        # Inject all ProactiveAgent-level handlers into +klass+.
-        # Uses a captured +klass+ variable so the Procs access the correct
-        # subclass even though their lexical +self+ is ProactiveAgent.
-        def inject_proactive_handlers!(klass) # rubocop:disable Metrics/MethodLength
-          # ── :_scan ────────────────────────────────────────────────────────
-          klass.on(:_scan) do |state:, **|
-            next state unless state.fetch(:active, true)
-
-            ctx = klass.watchers.transform_values do |poll|
-              poll.call
-            rescue StandardError
-              nil
-            end
-
-            fired     = []
-            new_state = klass.proactive_triggers.reduce(state) do |s, (name, t)|
-              next s unless t[:condition].call(ctx)
-
-              fired << FiredTrigger.new(name: name, fired_at: Time.now, context: ctx)
-              result = t[:action].call(state: s, context: ctx)
-              result.is_a?(Hash) ? result : s
-            end
-
-            new_state.merge(
-              context:         ctx,
-              scan_count:      new_state.fetch(:scan_count, 0) + 1,
-              last_scan_at:    Time.now,
-              trigger_history: (new_state.fetch(:trigger_history, []) + fired).last(100)
-            )
-          end
-
-          # ── :pause / :resume ──────────────────────────────────────────────
-          klass.on(:pause)  { |state:, **| state.merge(active: false) }
-          klass.on(:resume) { |state:, **| state.merge(active: true) }
-
-          # ── :status ───────────────────────────────────────────────────────
-          klass.on(:status) do |state:, **|
-            Status.new(
-              active:       state.fetch(:active, true),
-              scan_count:   state.fetch(:scan_count, 0),
-              intent:       klass.intent,
-              watchers:     klass.watchers.keys,
-              triggers:     klass.proactive_triggers.keys,
-              last_scan_at: state[:last_scan_at]
-            )
-          end
-
-          # ── :context ─────────────────────────────────────────────────────
-          klass.on(:context) { |state:, **| state.fetch(:context, {}).dup }
-
-          # ── :trigger_history ─────────────────────────────────────────────
-          klass.on(:trigger_history) { |state:, **| state.fetch(:trigger_history, []).dup }
-        end
-      end
-    end
-  end
-end

data/lib/igniter/agents/reliability/retry_agent.rb

@@ -1,99 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Agents
-    # Executes a callable with automatic retry on failure.
-    #
-    # Supports three backoff strategies:
-    # * :immediate   — retry without delay (useful in tests)
-    # * :linear      — delay grows linearly: base_delay × attempt
-    # * :exponential — delay doubles each time: base_delay × 2^(attempt-1)
-    #                  Add jitter: true to randomise delay ±50%
-    #
-    # Messages that exhaust all retries are stored in the dead letter queue
-    # and retrievable via the sync :dead_letters query.
-    #
-    # NOTE: The handler blocks the agent thread for the duration of all retries
-    # plus sleep intervals. For long-running retries, consider a dedicated
-    # RetryAgent instance per task.
-    #
-    # @example
-    #   ref = RetryAgent.start
-    #   ref.send(:with_retry,
-    #     callable:    ->(x:) { ExternalService.call(x) },
-    #     args:        { x: 42 },
-    #     max_retries: 3,
-    #     backoff:     :exponential,
-    #     base_delay:  0.5
-    #   )
-    #   dead = ref.call(:dead_letters)  # => []  (on success)
-    class RetryAgent < Igniter::Agent
-      # Returned as a sync reply from :dead_letters.
-      DeadLetter = Struct.new(:callable, :args, :error, :attempts, :ts, keyword_init: true)
-
-      initial_state dead_letters: []
-
-      # Execute +callable+ with retry.
-      #
-      # Payload keys:
-      #   callable    [#call]           — required; receives **args
-      #   args        [Hash]            — keyword arguments for callable (default: {})
-      #   max_retries [Integer]         — maximum retry count (default: 3)
-      #   backoff     [Symbol]          — :immediate / :linear / :exponential (default: :exponential)
-      #   base_delay  [Float]           — base sleep time in seconds (default: 1.0)
-      #   jitter      [Boolean]         — add random ±50% jitter to delay (default: false)
-      on :with_retry do |state:, payload:|
-        agent  = new
-        letter = agent.send(:run_with_retry, payload)
-        letter ? state.merge(dead_letters: state[:dead_letters] + [letter]) : state
-      end
-
-      # Sync query — returns Array<DeadLetter>.
-      on :dead_letters do |state:, **|
-        state[:dead_letters]
-      end
-
-      # Clear the dead letter queue.
-      on :clear_dead_letters do |state:, **|
-        state.merge(dead_letters: [])
-      end
-
-      private
-
-      def run_with_retry(payload)
-        callable    = payload.fetch(:callable)
-        args        = payload.fetch(:args, {})
-        max_retries = payload.fetch(:max_retries, 3).to_i
-        backoff     = payload.fetch(:backoff, :exponential).to_sym
-        base_delay  = payload.fetch(:base_delay, 1.0).to_f
-        jitter      = payload.fetch(:jitter, false)
-
-        attempt = 0
-        begin
-          attempt += 1
-          callable.call(**args)
-          nil # success
-        rescue StandardError => e
-          if attempt <= max_retries
-            sleep compute_delay(backoff, base_delay, attempt, jitter)
-            retry
-          else
-            DeadLetter.new(callable: callable, args: args,
-                           error: e.message, attempts: attempt,
-                           ts: Time.now.to_i)
-          end
-        end
-      end
-
-      def compute_delay(strategy, base, attempt, jitter)
-        raw = case strategy
-              when :immediate    then 0.0
-              when :linear       then base * attempt
-              when :exponential  then base * (2**(attempt - 1))
-              else                    0.0
-              end
-        jitter ? raw * (0.5 + rand * 0.5) : raw
-      end
-    end
-  end
-end

data/lib/igniter/agents/scheduling/cron_agent.rb

@@ -1,110 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Agents
-    # Interval-based job scheduler with cron-like semantics.
-    #
-    # Jobs are registered with a name, an interval (seconds), and a callable.
-    # A built-in schedule fires every second to advance due jobs.
-    # The :_tick handler is also exposed for deterministic testing.
-    #
-    # @example
-    #   ref = CronAgent.start
-    #   ref.send(:add_job,
-    #     name:     :cleanup,
-    #     every:    3600,
-    #     callable: -> { DataStore.purge_old_records }
-    #   )
-    #   status = ref.call(:list_jobs)  # => [{ name: :cleanup, every: 3600, runs: 0 }]
-    class CronAgent < Igniter::Agent
-      # Returned by :list_jobs sync query.
-      JobInfo = Struct.new(:name, :every, :runs, :next_in, keyword_init: true)
-
-      initial_state jobs: {}
-
-      # Auto-advance due jobs every second.
-      schedule(:tick, every: 1.0) do |state:|
-        agent = new
-        agent.send(:advance_jobs, state)
-      end
-
-      # Register or replace a job.
-      #
-      # Payload keys:
-      #   name     [Symbol, String]  — unique job identifier
-      #   every    [Numeric]         — interval in seconds
-      #   callable [#call]           — called with no arguments when due
-      on :add_job do |state:, payload:|
-        name     = payload.fetch(:name).to_sym
-        every    = payload.fetch(:every).to_f
-        callable = payload.fetch(:callable)
-
-        job = {
-          name:      name,
-          every:     every,
-          callable:  callable,
-          next_at:   Time.now.to_f + every,
-          runs:      0
-        }
-        state.merge(jobs: state[:jobs].merge(name => job))
-      end
-
-      # Remove a job by name.
-      #
-      # Payload keys:
-      #   name [Symbol, String]
-      on :remove_job do |state:, payload:|
-        name = payload.fetch(:name).to_sym
-        state.merge(jobs: state[:jobs].reject { |k, _| k == name })
-      end
-
-      # Sync query — list registered jobs.
-      #
-      # @return [Array<JobInfo>]
-      on :list_jobs do |state:, **|
-        now = Time.now.to_f
-        state[:jobs].values.map do |j|
-          JobInfo.new(
-            name:    j[:name],
-            every:   j[:every],
-            runs:    j[:runs],
-            next_in: [j[:next_at] - now, 0].max.round(2)
-          )
-        end
-      end
-
-      # Manually advance jobs — useful for testing without real time delays.
-      # Pass +at:+ to simulate a specific point in time.
-      #
-      # Payload keys:
-      #   at [Float, nil] — Unix timestamp to use as "now" (default: Time.now.to_f)
-      on :_tick do |state:, payload:|
-        agent = new
-        agent.send(:advance_jobs, state, payload[:at])
-      end
-
-      private
-
-      # Run all jobs whose next_at has passed and reschedule them.
-      # Errors in job callables are swallowed to keep the scheduler alive.
-      #
-      # @param state [Hash]
-      # @param now   [Float, nil]
-      # @return [Hash] updated state
-      def advance_jobs(state, now = nil)
-        now  = now || Time.now.to_f
-        jobs = state[:jobs].transform_values do |job|
-          next job if job[:next_at] > now
-
-          begin
-            job[:callable].call
-          rescue StandardError
-            nil # scheduler must not crash
-          end
-          job.merge(next_at: now + job[:every], runs: job[:runs] + 1)
-        end
-        state.merge(jobs: jobs)
-      end
-    end
-  end
-end

data/lib/igniter/agents.rb

@@ -1,56 +0,0 @@
-# frozen_string_literal: true
-
-# Standard library of ready-made Igniter agents.
-#
-# Usage:
-#   require "igniter/agents"
-#
-# Provides production-grade agents per domain:
-#
-#   Reliability   — Igniter::Agents::RetryAgent
-#   Pipeline      — Igniter::Agents::BatchProcessorAgent
-#   Scheduling    — Igniter::Agents::CronAgent
-#   AI/LLM        — Igniter::Agents::RouterAgent
-#                   Igniter::Agents::CriticAgent
-#                   Igniter::Agents::PlannerAgent
-#                   Igniter::Agents::ChainAgent
-#                   Igniter::Agents::SelfReflectionAgent
-#                   Igniter::Agents::ObserverAgent
-#                   Igniter::Agents::EvaluatorAgent
-#                   Igniter::Agents::EvolutionAgent
-#   Proactive     — Igniter::Agents::ProactiveAgent  (base)
-#                   Igniter::Agents::AlertAgent
-#                   Igniter::Agents::HealthCheckAgent
-#   Observability — Igniter::Agents::MetricsAgent
-#
-require_relative "integrations/agents"
-require_relative "agents/reliability/retry_agent"
-require_relative "agents/pipeline/batch_processor_agent"
-require_relative "agents/scheduling/cron_agent"
-require_relative "agents/ai/router_agent"
-require_relative "agents/ai/critic_agent"
-require_relative "agents/ai/planner_agent"
-require_relative "agents/ai/chain_agent"
-require_relative "agents/ai/self_reflection_agent"
-require_relative "agents/ai/observer_agent"
-require_relative "agents/ai/evaluator_agent"
-require_relative "agents/ai/evolution_agent"
-require_relative "agents/proactive_agent"
-require_relative "agents/ai/alert_agent"
-require_relative "agents/ai/health_check_agent"
-require_relative "agents/observability/metrics_agent"
-
-module Igniter
-  module Agents
-    # Convenience method — list all registered stdlib agents.
-    #
-    # @return [Array<Class>]
-    def self.all
-      [RetryAgent, BatchProcessorAgent, CronAgent,
-       RouterAgent, CriticAgent, PlannerAgent, ChainAgent,
-       SelfReflectionAgent, ObserverAgent, EvaluatorAgent, EvolutionAgent,
-       AlertAgent, HealthCheckAgent,
-       MetricsAgent]
-    end
-  end
-end

data/lib/igniter/application/app_config.rb

@@ -1,32 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  class Application
-    # Unified configuration object for an Igniter::Application.
-    # Wraps server-level settings in a single place.
-    # Call #to_server_config to get a Server::Config for HttpServer / RackApp.
-    class AppConfig
-      attr_accessor :host, :port, :store, :log_format, :drain_timeout, :metrics_collector
-
-      def initialize
-        @host              = "0.0.0.0"
-        @port              = 4567
-        @store             = nil # nil → MemoryStore default inside Server::Config
-        @log_format        = :text
-        @drain_timeout     = 30
-        @metrics_collector = nil
-      end
-
-      def to_server_config
-        Igniter::Server::Config.new.tap do |sc|
-          sc.host              = host
-          sc.port              = port
-          sc.store             = store if store
-          sc.log_format        = log_format
-          sc.drain_timeout     = drain_timeout
-          sc.metrics_collector = metrics_collector
-        end
-      end
-    end
-  end
-end

data/lib/igniter/application/autoloader.rb

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  class Application
-    # Eagerly loads all .rb files matching a glob path.
-    # Used by Application#executors_path / #contracts_path.
-    class Autoloader
-      def initialize(base_dir:)
-        @base_dir = File.expand_path(base_dir)
-      end
-
-      def load_path(path)
-        full = File.expand_path(path, @base_dir)
-        Dir.glob("#{full}/**/*.rb").sort.each { |f| require f }
-      end
-    end
-  end
-end