igniter 0.5.1 → 0.5.2

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

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

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

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

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