igniter 0.4.5 → 0.5.0

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

@@ -0,0 +1,131 @@
+# 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

@@ -0,0 +1,208 @@
+# 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

@@ -0,0 +1,99 @@
+# 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

@@ -0,0 +1,110 @@
+# 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

@@ -0,0 +1,56 @@
+# 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

@@ -0,0 +1,32 @@
+# 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

@@ -0,0 +1,18 @@
+# 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