igniter 0.4.3 → 0.5.0

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

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+module Igniter
+  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

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

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Igniter
+  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

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

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module Igniter
+  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

data/lib/igniter/agents/observability/metrics_agent.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Agents
+    # In-process metrics collection with Prometheus text export.
+    #
+    # Supports three metric types:
+    # * **counter**   — monotonically increasing value (:increment)
+    # * **gauge**     — arbitrary current value (:gauge)
+    # * **histogram** — observed value distribution (:observe)
+    #
+    # All metric names are coerced to strings. Tags (labels) are stored but not
+    # yet aggregated — they are included in the snapshot for external processing.
+    #
+    # @example
+    #   ref = MetricsAgent.start
+    #   ref.send(:increment, name: "http.requests", by: 1, tags: { method: "GET" })
+    #   ref.send(:gauge,     name: "queue.depth",   value: 42)
+    #   ref.send(:observe,   name: "response_time", value: 0.123)
+    #
+    #   snap = ref.call(:snapshot)
+    #   puts snap.counters["http.requests"]   # => 1.0
+    #
+    #   puts ref.call(:prometheus_text)
+    class MetricsAgent < Igniter::Agent
+      # Returned by the sync :snapshot query.
+      Snapshot = Struct.new(:counters, :gauges, :histograms, keyword_init: true)
+
+      initial_state counters: {}, gauges: {}, histograms: {}
+
+      # Increment a counter.
+      #
+      # Payload keys:
+      #   name [String, Symbol]  — metric name
+      #   by   [Numeric]         — increment amount (default: 1)
+      #   tags [Hash]            — labels (stored, not aggregated)
+      on :increment do |state:, payload:|
+        name     = payload.fetch(:name).to_s
+        by       = payload.fetch(:by, 1).to_f
+        counters = state[:counters].dup
+        counters[name] = (counters[name] || 0.0) + by
+        state.merge(counters: counters)
+      end
+
+      # Set a gauge to an exact value.
+      #
+      # Payload keys:
+      #   name  [String, Symbol]
+      #   value [Numeric]
+      #   tags  [Hash]
+      on :gauge do |state:, payload:|
+        name   = payload.fetch(:name).to_s
+        value  = payload.fetch(:value).to_f
+        gauges = state[:gauges].merge(name => value)
+        state.merge(gauges: gauges)
+      end
+
+      # Record a histogram observation.
+      #
+      # Payload keys:
+      #   name  [String, Symbol]
+      #   value [Numeric]
+      on :observe do |state:, payload:|
+        name       = payload.fetch(:name).to_s
+        value      = payload.fetch(:value).to_f
+        histograms = state[:histograms].dup
+        bucket     = histograms[name] || { count: 0, sum: 0.0, min: Float::INFINITY,
+                                           max: -Float::INFINITY, values: [] }
+        updated    = bucket.merge(
+          count:  bucket[:count] + 1,
+          sum:    bucket[:sum]   + value,
+          min:    [bucket[:min], value].min,
+          max:    [bucket[:max], value].max,
+          values: bucket[:values] + [value]
+        )
+        state.merge(histograms: histograms.merge(name => updated))
+      end
+
+      # Sync snapshot query — returns all current metric values.
+      #
+      # @return [Snapshot]
+      on :snapshot do |state:, **|
+        Snapshot.new(
+          counters:   state[:counters].dup,
+          gauges:     state[:gauges].dup,
+          histograms: state[:histograms].transform_values { |h|
+            { count: h[:count], sum: h[:sum], min: h[:min], max: h[:max],
+              avg: h[:count] > 0 ? h[:sum] / h[:count] : 0.0 }
+          }
+        )
+      end
+
+      # Sync query — render metrics in Prometheus text format.
+      #
+      # @return [String]
+      on :prometheus_text do |state:, **|
+        render_prometheus(state)
+      end
+
+      # Reset all metrics.
+      on :reset do |state:, **|
+        state.merge(counters: {}, gauges: {}, histograms: {})
+      end
+
+      class << self
+        # Render state as Prometheus exposition format.
+        #
+        # @param state [Hash]
+        # @return [String]
+        def render_prometheus(state)
+          lines = []
+          state[:counters].each do |name, value|
+            lines << "# TYPE #{name} counter"
+            lines << "#{name} #{value}"
+          end
+          state[:gauges].each do |name, value|
+            lines << "# TYPE #{name} gauge"
+            lines << "#{name} #{value}"
+          end
+          state[:histograms].each do |name, h|
+            lines << "# TYPE #{name} histogram"
+            lines << "#{name}_count #{h[:count]}"
+            lines << "#{name}_sum #{h[:sum]}"
+          end
+          lines.join("\n")
+        end
+      end
+    end
+  end
+end