igniter 0.4.5 → 0.5.1

data/packages/igniter-agents/lib/igniter/agents/proactive_agent.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require "igniter/agent"
+
+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/packages/igniter-agents/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/packages/igniter-agents/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/packages/igniter-agents/lib/igniter/agents.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "igniter/agent"
+require_relative "agents/reliability/retry_agent"
+require_relative "agents/pipeline/batch_processor_agent"
+require_relative "agents/scheduling/cron_agent"
+require_relative "agents/proactive_agent"
+require_relative "agents/proactive/alert_agent"
+require_relative "agents/proactive/health_check_agent"
+require_relative "agents/observability/metrics_agent"
+
+module Igniter
+  module Agents
+    # Convenience method — list all registered generic stdlib agents.
+    #
+    # @return [Array<Class>]
+    def self.all
+      [RetryAgent, BatchProcessorAgent, CronAgent,
+       ProactiveAgent, AlertAgent, HealthCheckAgent,
+       MetricsAgent]
+    end
+  end
+end

data/packages/igniter-agents/lib/igniter/ai/agents/chain_agent.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Igniter
+  module AI
+    module Agents
+    # Executes a sequence of callables where each step's output becomes the
+    # next step's input.
+    #
+    # Each step callable receives:
+    #   input:   [Object]         — output from the previous step (or initial input)
+    #   context: [Hash]           — shared context unchanged throughout the run
+    #   results: [Array<StepResult>]  — results from all preceding steps
+    #
+    # On error the chain stops immediately by default. Pass +stop_on_error: false+
+    # to continue with the error message as the next step's input.
+    #
+    # @example Summarise → translate → format
+    #   ref = ChainAgent.start
+    #   ref.send(:set_chain, steps: [
+    #     { name: :summarise,  callable: ->(input:, **) { SummariseSkill.call(text: input) } },
+    #     { name: :translate,  callable: ->(input:, **) { TranslateSkill.call(text: input) } },
+    #     { name: :format,     callable: ->(input:, **) { FormatSkill.call(content: input)  } }
+    #   ])
+    #   ref.send(:run, input: long_article, context: { target_lang: "es" })
+    #   steps = ref.call(:results)
+      class ChainAgent < Igniter::Agent
+      # Immutable record for one completed step.
+      StepResult = Struct.new(:name, :input, :output, :status, keyword_init: true)
+
+      initial_state chain: [], results: [], context: {}
+
+      # Append a step to the end of the chain.
+      #
+      # Payload keys:
+      #   name     [String, Symbol]  — step identifier
+      #   callable [#call]           — receives (input:, context:, results:)
+      on :add_step do |state:, payload:|
+        step = { name: payload.fetch(:name).to_s, callable: payload.fetch(:callable) }
+        state.merge(chain: state[:chain] + [step])
+      end
+
+      # Replace the entire chain.
+      #
+      # Payload keys:
+      #   steps [Array<Hash>]  — each element must have :name and :callable keys
+      on :set_chain do |state:, payload:|
+        steps = Array(payload.fetch(:steps)).map do |s|
+          { name: s.fetch(:name).to_s, callable: s.fetch(:callable) }
+        end
+        state.merge(chain: steps)
+      end
+
+      # Remove a step by name.
+      #
+      # Payload keys:
+      #   name [String, Symbol]
+      on :remove_step do |state:, payload:|
+        name = payload.fetch(:name).to_s
+        state.merge(chain: state[:chain].reject { |s| s[:name] == name })
+      end
+
+      # Execute the chain with an initial input.
+      #
+      # Payload keys:
+      #   input         [Object]   — starting value for the first step
+      #   context       [Hash]     — shared context passed to every step (default: {})
+      #   stop_on_error [Boolean]  — halt on first error (default: true)
+      on :run do |state:, payload:|
+        agent = new
+        agent.send(:run_chain, state, payload)
+      end
+
+      # Sync query — step results from the most recent run.
+      #
+      # @return [Array<StepResult>]
+      on :results do |state:, **|
+        state[:results]
+      end
+
+      # Sync query — list registered step names.
+      #
+      # @return [Array<String>]
+      on :steps do |state:, **|
+        state[:chain].map { |s| s[:name] }
+      end
+
+      # Clear results and context from the last run (chain is preserved).
+      on :reset do |state:, **|
+        state.merge(results: [], context: {})
+      end
+
+      private
+
+      def run_chain(state, payload)
+        input         = payload.fetch(:input)
+        context       = payload.fetch(:context, state[:context])
+        stop_on_error = payload.fetch(:stop_on_error, true)
+        results       = []
+        current       = input
+
+        state[:chain].each do |step|
+          output, status = invoke_step(step[:callable], current, context, results)
+
+          results << StepResult.new(
+            name:   step[:name],
+            input:  current,
+            output: output,
+            status: status
+          )
+
+          break if status == :error && stop_on_error
+
+          current = output
+        end
+
+        state.merge(results: results, context: context)
+      end
+
+      # @return [[output, status]]
+      def invoke_step(callable, input, context, results)
+        output = callable.call(input: input, context: context, results: results)
+        [output, :ok]
+      rescue StandardError => e
+        [e.message, :error]
+      end
+      end
+    end
+  end
+end