igniter 0.5.0 → 0.5.2

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

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

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

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

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