igniter 0.4.5 → 0.5.1

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

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module Igniter
+  module AI
+    module Agents
+    # Passive-watching agent that records observations from other agents or
+    # systems, applies user-defined anomaly-detection rules, and surfaces
+    # detected anomalies for inspection or alerting.
+    #
+    # Design:
+    # * Observations are appended via +:observe+.
+    # * Anomaly rules are callables +:matcher+ stored with a +:name+.
+    # * Call +:check+ to scan new (unscanned) observations against all rules.
+    #   The agent tracks a cursor so rules are never applied twice to the same
+    #   observation, preventing duplicates.
+    #
+    # @example Detect error spikes
+    #   ref = ObserverAgent.start
+    #   ref.send(:watch, subject: :payments)
+    #   ref.send(:add_rule,
+    #     name:    :consecutive_errors,
+    #     matcher: ->(obs) { obs.event == :error })
+    #   ref.send(:observe, subject: :payments, event: :error)
+    #   ref.send(:check)
+    #   ref.call(:anomalies)   # => [Anomaly(...)]
+      class ObserverAgent < Igniter::Agent
+      # A single recorded event.
+      Observation = Struct.new(:subject, :event, :data, :observed_at, keyword_init: true)
+
+      # A detected rule violation.
+      Anomaly = Struct.new(:subject, :rule, :observation, :detected_at, keyword_init: true)
+
+      # A detection rule.
+      Rule = Struct.new(:name, :matcher, keyword_init: true)
+
+      # Sync-query summary.
+      Summary = Struct.new(:subjects, :observations, :anomalies, :rules, keyword_init: true)
+
+      initial_state \
+        subjects:         [],
+        observations:     [],
+        anomalies:        [],
+        rules:            [],
+        checked_until:    0,
+        max_observations: 500
+
+      # Register a subject to watch.
+      #
+      # Payload keys:
+      #   subject [Symbol, String]
+      on :watch do |state:, payload:|
+        subject = payload.fetch(:subject).to_sym
+        next state if state[:subjects].include?(subject)
+
+        state.merge(subjects: state[:subjects] + [subject])
+      end
+
+      # Stop watching a subject.
+      #
+      # Payload keys:
+      #   subject [Symbol, String]
+      on :unwatch do |state:, payload:|
+        subject = payload.fetch(:subject).to_sym
+        state.merge(subjects: state[:subjects] - [subject])
+      end
+
+      # Record an observation event.
+      #
+      # Payload keys:
+      #   subject [Symbol, String]  — source of the event
+      #   event   [Symbol, String]  — event type
+      #   data    [Hash]            — optional extra data
+      on :observe do |state:, payload:|
+        obs = Observation.new(
+          subject:     payload.fetch(:subject),
+          event:       payload.fetch(:event),
+          data:        payload.fetch(:data, {}),
+          observed_at: Time.now
+        )
+        kept = (state[:observations] + [obs]).last(state[:max_observations])
+        state.merge(observations: kept)
+      end
+
+      # Add (or replace) an anomaly-detection rule.
+      #
+      # Payload keys:
+      #   name    [Symbol, String]  — unique rule identifier
+      #   matcher [#call]           — callable(Observation) → truthy when anomaly
+      on :add_rule do |state:, payload:|
+        rule  = Rule.new(name: payload.fetch(:name).to_sym, matcher: payload.fetch(:matcher))
+        rules = state[:rules].reject { |r| r.name == rule.name } + [rule]
+        state.merge(rules: rules)
+      end
+
+      # Remove a rule by name.
+      #
+      # Payload keys:
+      #   name [Symbol, String]
+      on :remove_rule do |state:, payload:|
+        name = payload.fetch(:name).to_sym
+        state.merge(rules: state[:rules].reject { |r| r.name == name })
+      end
+
+      # Scan observations added since the last check against all rules.
+      # Uses a cursor to guarantee each observation is checked at most once.
+      #
+      # Payload keys:
+      #   window [Integer, nil]  — max recent observations to scan (default: all new)
+      on :check do |state:, payload:|
+        cursor  = state[:checked_until]
+        new_obs = state[:observations].drop(cursor)
+        new_obs = new_obs.last(payload[:window]) if payload&.fetch(:window, nil)
+
+        detected = new_obs.flat_map do |obs|
+          state[:rules].filter_map do |rule|
+            next unless rule.matcher.call(obs)
+
+            Anomaly.new(
+              subject:     obs.subject,
+              rule:        rule.name,
+              observation: obs,
+              detected_at: Time.now
+            )
+          end
+        end
+
+        state.merge(
+          anomalies:     state[:anomalies] + detected,
+          checked_until: state[:observations].size
+        )
+      end
+
+      # Sync query — return observations, optionally filtered by subject.
+      #
+      # Payload keys:
+      #   subject [Symbol, String, nil]
+      #
+      # @return [Array<Observation>]
+      on :observations do |state:, payload:|
+        filter = payload&.fetch(:subject, nil)
+        obs    = state[:observations]
+        obs    = obs.select { |o| o.subject.to_s == filter.to_s } if filter
+        obs.dup
+      end
+
+      # Sync query — return anomalies, optionally filtered by subject.
+      #
+      # Payload keys:
+      #   subject [Symbol, String, nil]
+      #
+      # @return [Array<Anomaly>]
+      on :anomalies do |state:, payload:|
+        filter = payload&.fetch(:subject, nil)
+        anoms  = state[:anomalies]
+        anoms  = anoms.select { |a| a.subject.to_s == filter.to_s } if filter
+        anoms.dup
+      end
+
+      # Sync query — aggregate counts.
+      #
+      # @return [Summary]
+      on :summary do |state:, **|
+        Summary.new(
+          subjects:     state[:subjects].size,
+          observations: state[:observations].size,
+          anomalies:    state[:anomalies].size,
+          rules:        state[:rules].size
+        )
+      end
+
+      # Clear detected anomalies (observations and rules are preserved).
+      on :clear_anomalies do |state:, **|
+        state.merge(anomalies: [], checked_until: 0)
+      end
+
+      # Update configuration.
+      #
+      # Payload keys:
+      #   max_observations [Integer]
+      on :configure do |state:, payload:|
+        state.merge(payload.slice(:max_observations).compact)
+      end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+module Igniter
+  module AI
+    module Agents
+    # Decomposes a goal into an ordered sequence of steps and executes them.
+    #
+    # Implements a lightweight ReAct-style planning loop:
+    # 1. +:plan+ — decompose a goal into steps (LLM or rule-based fallback)
+    # 2. +:execute_next+ — execute one step and advance the cursor
+    # 3. +:run_to_completion+ — plan + execute all steps in a single call
+    #
+    # == Step decomposition
+    #
+    # When a +planner:+ callable is configured it receives +goal:+ and
+    # +context:+ and must return one of:
+    # * +Array<String>+ — one element per step description
+    # * +String+ — newline-separated or numbered list; parsed automatically
+    # * +Hash+ with +:steps+ key
+    #
+    # Without a planner the goal itself becomes a single-step plan.
+    #
+    # == Step execution
+    #
+    # When a +step_handler:+ callable is configured it receives:
+    #   step:    [String]  — step description
+    #   index:   [Integer] — zero-based step index
+    #   context: [Hash]    — shared execution context
+    #   results: [Array]   — results from previous steps
+    #
+    # Without a handler, steps are marked :skipped.
+    #
+    # @example
+    #   planner = ->(goal:, context:) { MyDecomposerSkill.call(goal: goal).steps }
+    #   executor = ->(step:, index:, context:, results:) { RunStep.call(step) }
+    #
+    #   ref = PlannerAgent.start(initial_state: {
+    #     planner:      planner,
+    #     step_handler: executor
+    #   })
+    #   ref.send(:run_to_completion, goal: "Build a landing page", context: { tone: :casual })
+    #   puts ref.call(:status).inspect
+      class PlannerAgent < Igniter::Agent
+      # Immutable step record.
+      Step = Struct.new(:index, :description, :status, :result, keyword_init: true)
+
+      # Returned by the sync :status query.
+      PlanStatus = Struct.new(:goal, :total_steps, :current_step,
+                               :completed, :failed, keyword_init: true)
+
+      initial_state planner: nil, step_handler: nil, plan: [], current_step: 0,
+                    goal: nil, context: {}, results: []
+
+      # Decompose a goal into a plan.
+      # Replaces any existing plan; resets cursor and results.
+      #
+      # Payload keys:
+      #   goal         [String]        — required
+      #   context      [Hash]          — shared context forwarded to all steps (default: {})
+      #   planner      [#call, nil]    — override state planner
+      #   step_handler [#call, nil]    — set/override step handler
+      on :plan do |state:, payload:|
+        agent = new
+        agent.send(:create_plan, state, payload)
+      end
+
+      # Execute the next pending step.
+      # No-op when the plan is complete or no plan has been created.
+      #
+      # Payload keys:
+      #   step_handler [#call, nil]  — override state step_handler for this call
+      on :execute_next do |state:, payload:|
+        agent = new
+        agent.send(:execute_one_step, state, payload)
+      end
+
+      # Plan and execute all steps in one call (blocks until done).
+      #
+      # Accepts the same payload as :plan plus any :execute_next overrides.
+      on :run_to_completion do |state:, payload:|
+        agent = new
+        agent.send(:run_all, state, payload)
+      end
+
+      # Sync query — current plan progress.
+      #
+      # @return [PlanStatus]
+      on :status do |state:, **|
+        PlanStatus.new(
+          goal:         state[:goal],
+          total_steps:  state[:plan].size,
+          current_step: state[:current_step],
+          completed:    state[:plan].count { |s| s.status == :done },
+          failed:       state[:plan].count { |s| s.status == :failed }
+        )
+      end
+
+      # Sync query — step results from the last run.
+      #
+      # @return [Array<Hash>]
+      on :results do |state:, **|
+        state[:results]
+      end
+
+      # Clear plan, cursor, and results.
+      on :reset do |state:, **|
+        state.merge(plan: [], current_step: 0, goal: nil, results: [])
+      end
+
+      # Update planner and/or step_handler.
+      #
+      # Payload keys:
+      #   planner      [#call]
+      #   step_handler [#call]
+      on :configure do |state:, payload:|
+        state.merge(
+          planner:      payload.fetch(:planner,      state[:planner]),
+          step_handler: payload.fetch(:step_handler, state[:step_handler])
+        )
+      end
+
+      private
+
+      def create_plan(state, payload)
+        goal         = payload.fetch(:goal)
+        context      = payload.fetch(:context, state[:context])
+        planner      = payload.fetch(:planner, state[:planner])
+        step_handler = payload.fetch(:step_handler, state[:step_handler])
+
+        descriptions = planner ? decompose_with_planner(planner, goal, context)
+                                : [goal.to_s]
+
+        plan = descriptions.each_with_index.map do |desc, i|
+          Step.new(index: i, description: desc, status: :pending, result: nil)
+        end
+
+        state.merge(
+          goal:         goal,
+          context:      context,
+          plan:         plan,
+          current_step: 0,
+          results:      [],
+          step_handler: step_handler || state[:step_handler]
+        )
+      end
+
+      def execute_one_step(state, payload)
+        idx          = state[:current_step]
+        plan         = state[:plan]
+        return state if idx >= plan.size
+
+        step         = plan[idx]
+        step_handler = payload.fetch(:step_handler, state[:step_handler])
+
+        result, status = run_step(step_handler, step, state)
+
+        updated_plan    = plan.dup
+        updated_plan[idx] = Step.new(
+          index:       step.index,
+          description: step.description,
+          status:      status,
+          result:      result
+        )
+
+        state.merge(
+          plan:         updated_plan,
+          current_step: idx + 1,
+          results:      state[:results] + [{ step: step.description, result: result, status: status }]
+        )
+      end
+
+      def run_all(state, payload)
+        planned = create_plan(state, payload)
+        planned[:plan].size.times.reduce(planned) { |s, _| execute_one_step(s, payload) }
+      end
+
+      # @return [[result, status]]
+      def run_step(step_handler, step, state)
+        return ["No handler configured", :skipped] unless step_handler
+
+        result = step_handler.call(
+          step:    step.description,
+          index:   step.index,
+          context: state[:context],
+          results: state[:results]
+        )
+        [result, :done]
+      rescue StandardError => e
+        [e.message, :failed]
+      end
+
+      # Parse planner output into Array<String> step descriptions.
+      def decompose_with_planner(planner, goal, context)
+        raw = planner.call(goal: goal, context: context)
+        case raw
+        when Array  then raw.map(&:to_s).reject(&:empty?)
+        when Hash   then Array(raw[:steps] || raw["steps"]).map(&:to_s).reject(&:empty?)
+        when String then parse_step_list(raw)
+        else             [raw.to_s]
+        end
+      end
+
+      # Split a numbered or newline-delimited string into step descriptions.
+      def parse_step_list(text)
+        text.split("\n")
+            .map { |l| l.sub(/\A\s*\d+[\.\)\-]\s*/, "").strip }
+            .reject(&:empty?)
+      end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Igniter
+  module AI
+    module Agents
+    # Classifies incoming tasks by intent and dispatches to registered handlers.
+    #
+    # Two classification modes:
+    # * **Keyword** (default) — checks whether the task string contains the
+    #   intent name (case-insensitive). Zero external dependencies.
+    # * **LLM-assisted** — uses an Igniter LLM executor to classify; falls back
+    #   to keyword mode when the LLM returns an unrecognised intent.
+    #
+    # Handlers are callables that receive +task:+, +intent:+, and +context:+.
+    # A fallback handler can be registered for unmatched tasks.
+    #
+    # @example Keyword routing
+    #   ref = RouterAgent.start
+    #   ref.send(:register_route, intent: :refund,   handler: RefundSkill.new)
+    #   ref.send(:register_route, intent: :shipping, handler: ShippingSkill.new)
+    #   ref.send(:set_fallback,   handler: ->(task:, **) { puts "Unknown: #{task}" })
+    #   ref.send(:route, task: "I want a refund", context: { user_id: 42 })
+    #
+    # @example LLM routing
+    #   ref = RouterAgent.start
+    #   ref.send(:configure_llm, executor: MyLLMClassifier.new)
+    #   ref.send(:register_route, intent: :billing, handler: BillingSkill.new)
+    #   ref.send(:route, task: "charge me for the premium plan")
+      class RouterAgent < Igniter::Agent
+      # Returned by :routes sync query.
+      RouteInfo = Struct.new(:intent, :handler_class, keyword_init: true)
+
+      initial_state routes: {}, fallback_handler: nil, llm: nil
+
+      # Register a handler for a named intent.
+      #
+      # Payload keys:
+      #   intent  [Symbol, String]  — intent identifier
+      #   handler [#call]           — receives (task:, intent:, context:)
+      on :register_route do |state:, payload:|
+        intent  = payload.fetch(:intent).to_sym
+        handler = payload.fetch(:handler)
+        state.merge(routes: state[:routes].merge(intent => handler))
+      end
+
+      # Remove a route.
+      #
+      # Payload keys:
+      #   intent [Symbol, String]
+      on :remove_route do |state:, payload:|
+        intent = payload.fetch(:intent).to_sym
+        state.merge(routes: state[:routes].reject { |k, _| k == intent })
+      end
+
+      # Set the fallback handler for unmatched tasks.
+      #
+      # Payload keys:
+      #   handler [#call]  — receives (task:, intent:, context:)
+      on :set_fallback do |state:, payload:|
+        state.merge(fallback_handler: payload.fetch(:handler))
+      end
+
+      # Configure an LLM executor for intent classification.
+      # The executor must respond to :call and receive a Hash with:
+      #   task:, context:, intents: (Array<String> of registered intent names)
+      # It must return a Hash with :intent key (String or Symbol).
+      #
+      # Payload keys:
+      #   executor [#call]
+      on :configure_llm do |state:, payload:|
+        state.merge(llm: payload.fetch(:executor))
+      end
+
+      # Route a task to the appropriate handler.
+      #
+      # Payload keys:
+      #   task       [String]        — the task or query to route
+      #   context    [Hash]          — additional context forwarded to the handler
+      #   on_unrouted [#call, nil]   — called with (task:, intent:) when no handler found
+      on :route do |state:, payload:|
+        agent = new
+        agent.send(:dispatch, payload, state)
+        state
+      end
+
+      # Sync query — list registered intents.
+      #
+      # @return [Array<RouteInfo>]
+      on :routes do |state:, **|
+        state[:routes].map { |intent, handler|
+          RouteInfo.new(intent: intent, handler_class: handler.class.name)
+        }
+      end
+
+      private
+
+      def dispatch(payload, state)
+        task        = payload.fetch(:task)
+        context     = payload.fetch(:context, {})
+        on_unrouted = payload[:on_unrouted] || state[:on_unrouted]
+        routes      = state[:routes]
+        llm         = state[:llm]
+
+        intent  = llm ? classify_llm(task, context, routes, llm) : nil
+        intent  = classify_keyword(task, routes) if intent.nil? || !routes.key?(intent)
+        handler = routes[intent] || state[:fallback_handler]
+
+        if handler
+          handler.call(task: task, intent: intent, context: context)
+        elsif on_unrouted
+          on_unrouted.call(task: task, intent: intent)
+        end
+      end
+
+      def classify_llm(task, context, routes, llm)
+        result = llm.call(
+          task:    task,
+          context: context,
+          intents: routes.keys.map(&:to_s)
+        )
+        result[:intent]&.to_sym
+      rescue StandardError
+        nil # fall through to keyword classification
+      end
+
+      def classify_keyword(task, routes)
+        task_lower = task.to_s.downcase
+        routes.keys.find { |intent| task_lower.include?(intent.to_s.downcase) }
+      end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Igniter
+  module AI
+    module Agents
+    # Reflects on a rolling window of past action episodes, surfaces patterns
+    # in failures and successes, and proposes behavioural patches.
+    #
+    # Two reflection modes:
+    # * **Heuristic** (default) — computes success rate and top failing actions;
+    #   requires no external dependencies.
+    # * **LLM-assisted** — delegates to any callable that accepts
+    #   +reflection_prompt: String+ and returns a String summary.
+    #
+    # @example Record episodes and reflect
+    #   ref = SelfReflectionAgent.start
+    #   ref.send(:record_episode, action: :process_order, outcome: :success)
+    #   ref.send(:record_episode, action: :send_email,    outcome: :failure, details: { reason: "timeout" })
+    #   ref.send(:reflect)
+    #   status = ref.call(:status)   # => StatusInfo struct
+    #   recs   = ref.call(:reflections)
+      class SelfReflectionAgent < Igniter::Agent
+      # Sync-query return type.
+      StatusInfo = Struct.new(:episodes, :reflections, :patches_applied,
+                              :last_reflected_at, keyword_init: true)
+
+      # A single recorded activity.
+      Episode = Struct.new(:action, :outcome, :details, :occurred_at, keyword_init: true)
+
+      # One completed reflection cycle.
+      ReflectionRecord = Struct.new(:summary, :insights, :patch,
+                                    :reflected_at, keyword_init: true)
+
+      initial_state \
+        episodes: [],
+        reflections: [],
+        patches: [],
+        llm: nil,
+        window: 50,
+        patches_applied: 0
+
+      # Record a single action outcome.
+      #
+      # Payload keys:
+      #   action  [Symbol, String]  — name of the action performed
+      #   outcome [Symbol]          — :success | :failure | any meaningful symbol
+      #   details [Hash]            — optional extra context
+      on :record_episode do |state:, payload:|
+        ep = Episode.new(
+          action:      payload.fetch(:action),
+          outcome:     payload.fetch(:outcome),
+          details:     payload.fetch(:details, {}),
+          occurred_at: Time.now
+        )
+        # keep at most 2× the reflection window to avoid unbounded growth
+        kept = (state[:episodes] + [ep]).last(state[:window] * 2)
+        state.merge(episodes: kept)
+      end
+
+      # Run a reflection cycle over the latest +window+ episodes.
+      # Appends a ReflectionRecord to the reflection log.
+      on :reflect do |state:, payload:|
+        agent = new
+        rec   = agent.send(:run_reflection, state, payload || {})
+        state.merge(reflections: state[:reflections] + [rec])
+      end
+
+      # Store an externally generated or LLM-proposed behavioural patch.
+      #
+      # Payload keys:
+      #   patch [String]  — description of the proposed change
+      on :apply_patch do |state:, payload:|
+        entry   = { patch: payload.fetch(:patch), applied_at: Time.now }
+        patches = state[:patches] + [entry]
+        state.merge(patches: patches, patches_applied: state[:patches_applied] + 1)
+      end
+
+      # Sync query — current operational summary.
+      #
+      # @return [StatusInfo]
+      on :status do |state:, **|
+        last_r = state[:reflections].last
+        StatusInfo.new(
+          episodes:          state[:episodes].size,
+          reflections:       state[:reflections].size,
+          patches_applied:   state[:patches_applied],
+          last_reflected_at: last_r&.reflected_at
+        )
+      end
+
+      # Sync query — all ReflectionRecord objects.
+      on :reflections do |state:, **|
+        state[:reflections].dup
+      end
+
+      # Sync query — all recorded Episode objects.
+      on :episodes do |state:, **|
+        state[:episodes].dup
+      end
+
+      # Update agent configuration.
+      #
+      # Payload keys:
+      #   llm    [#call, nil]  — optional LLM callable
+      #   window [Integer]     — number of recent episodes to reflect on
+      on :configure do |state:, payload:|
+        state.merge(payload.slice(:llm, :window).compact)
+      end
+
+      # Clear all recorded state (does not reset configuration).
+      on :reset do |state:, **|
+        state.merge(episodes: [], reflections: [], patches: [], patches_applied: 0)
+      end
+
+      private
+
+      def run_reflection(state, _payload)
+        episodes = state[:episodes].last(state[:window])
+        llm      = state[:llm]
+
+        summary, insights, patch =
+          if llm
+            reflect_with_llm(llm, episodes)
+          else
+            reflect_heuristic(episodes)
+          end
+
+        ReflectionRecord.new(
+          summary:      summary,
+          insights:     insights,
+          patch:        patch,
+          reflected_at: Time.now
+        )
+      end
+
+      def reflect_with_llm(llm, episodes)
+        successes = episodes.count { |e| [:success, "success"].include?(e.outcome) }
+        failures  = episodes.count { |e| [:failure, "failure"].include?(e.outcome) }
+        digest    = episodes.map { |e| "#{e.action}:#{e.outcome}" }.join(", ")
+
+        prompt = "Reflect on #{episodes.size} recent episodes " \
+                 "(#{successes} succeeded, #{failures} failed): #{digest}. " \
+                 "Provide a brief summary, up to 3 key insights, " \
+                 "and one suggested behavioural patch."
+
+        summary = llm.call(reflection_prompt: prompt).to_s
+        [summary, [], nil]
+      rescue StandardError
+        reflect_heuristic(episodes)
+      end
+
+      def reflect_heuristic(episodes)
+        return ["No episodes to reflect on.", [], nil] if episodes.empty?
+
+        total    = episodes.size
+        failures = episodes.select { |e| [:failure, "failure"].include?(e.outcome) }
+        rate     = ((total - failures.size).to_f / total * 100).round(1)
+
+        top_failing = failures.map(&:action).tally
+                              .sort_by { |_, c| -c }
+                              .first(3)
+
+        insights = ["Success rate: #{rate}%"]
+        unless top_failing.empty?
+          insights << "Top failing actions: #{top_failing.map { |a, c| "#{a}(×#{c})" }.join(", ")}"
+        end
+
+        patch = if rate < 50
+          "Consider retries or simplification for: #{top_failing.map(&:first).join(", ")}"
+        end
+
+        ["Reflected on #{total} episodes. #{rate}% success rate.", insights, patch]
+      end
+      end
+    end
+  end
+end