igniter 0.4.3 → 0.5.0

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

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Agents
+    # Mission: become better.
+    #
+    # An evolutionary self-improvement agent that maintains a population of
+    # strategies (prompt variants, parameter configs, tool selections — any
+    # Hash), evaluates their fitness, selects survivors, generates mutations,
+    # and tracks lineage across generations.
+    #
+    # The agent is intentionally domain-agnostic. Strategies are plain Hashes
+    # whose semantics are defined by the caller's +fitness_fn+.
+    #
+    # Life-cycle of one generation:
+    #   seed → evaluate_population → evolve   (or: seed → run_generation × N)
+    #
+    # Mutation:
+    # * **Rule-based** (default) — numeric values are scaled ±20 %, booleans
+    #   are flipped, arrays are sub-sampled. Strings are kept unchanged.
+    # * **LLM-assisted** — delegates to any callable that accepts
+    #   +strategy:+ and +generation:+ and returns a Hash.
+    #
+    # @example Evolve a prompt configuration
+    #   fitness = ->(config) { MyEvaluator.score(config) }
+    #   ref = EvolutionAgent.start(initial_state: {
+    #     fitness_fn: fitness,
+    #     population_size: 4
+    #   })
+    #   ref.send(:seed, strategies: [
+    #     { temperature: 0.7, max_tokens: 512 },
+    #     { temperature: 0.3, max_tokens: 256 }
+    #   ])
+    #   3.times { ref.send(:run_generation) }
+    #   best = ref.call(:best)   # => Strategy struct
+    class EvolutionAgent < Igniter::Agent
+      # An individual strategy in the population.
+      Strategy = Struct.new(:id, :config, :fitness, :generation,
+                            :parent_ids, :mutations, keyword_init: true)
+
+      # Summary record for one completed generation.
+      GenerationReport = Struct.new(:generation, :population_size, :best_fitness,
+                                    :mean_fitness, :best_id, keyword_init: true)
+
+      initial_state \
+        population:       [],
+        generation:       0,
+        history:          [],
+        best_strategy:    nil,
+        fitness_fn:       nil,
+        llm:              nil,
+        population_size:  6,
+        mutation_rate:    0.3,
+        elite_fraction:   0.5
+
+      # Seed the population with an initial set of strategy configs.
+      # Resets generation counter and history.
+      #
+      # Payload keys:
+      #   strategies [Array<Hash>]  — initial strategy configs
+      on :seed do |state:, payload:|
+        pop = Array(payload.fetch(:strategies)).each_with_index.map do |cfg, i|
+          Strategy.new(
+            id:         "gen0_#{i}",
+            config:     cfg,
+            fitness:    nil,
+            generation: 0,
+            parent_ids: [],
+            mutations:  []
+          )
+        end
+        state.merge(population: pop, generation: 0, history: [], best_strategy: nil)
+      end
+
+      # Score every strategy in the population using the fitness function.
+      # Strategies that raise are assigned fitness 0.0.
+      #
+      # Payload keys:
+      #   fitness_fn [#call, nil]  — override the state fitness function
+      on :evaluate_population do |state:, payload:|
+        fitness_fn = (payload && payload[:fitness_fn]) || state[:fitness_fn]
+        next state unless fitness_fn
+
+        agent     = new
+        evaluated = agent.send(:score_population, state[:population], fitness_fn)
+        best      = evaluated.max_by { |s| s.fitness || -Float::INFINITY }
+        state.merge(population: evaluated, best_strategy: best)
+      end
+
+      # Select elite survivors, generate children by mutation, increment generation.
+      # Requires the population to be already evaluated (see +:evaluate_population+).
+      on :evolve do |state:, payload:|
+        agent          = new
+        new_pop, report = agent.send(:run_evolution, state)
+        next state unless new_pop
+
+        best = new_pop.max_by { |s| s.fitness || -Float::INFINITY }
+        state.merge(
+          population:    new_pop,
+          generation:    state[:generation] + 1,
+          history:       state[:history] + [report],
+          best_strategy: best
+        )
+      end
+
+      # Convenience: evaluate the current population then evolve — one full cycle.
+      #
+      # Payload keys:
+      #   fitness_fn [#call, nil]  — override the state fitness function
+      on :run_generation do |state:, payload:|
+        fitness_fn = (payload && payload[:fitness_fn]) || state[:fitness_fn]
+        next state unless fitness_fn
+
+        agent = new
+
+        # evaluate
+        evaluated_pop = agent.send(:score_population, state[:population], fitness_fn)
+        with_scores   = state.merge(population: evaluated_pop)
+
+        # evolve
+        new_pop, report = agent.send(:run_evolution, with_scores)
+        next with_scores unless new_pop
+
+        best = new_pop.max_by { |s| s.fitness || -Float::INFINITY }
+        with_scores.merge(
+          population:    new_pop,
+          generation:    state[:generation] + 1,
+          history:       state[:history] + [report],
+          best_strategy: best
+        )
+      end
+
+      # Add a single mutated child of a given strategy to the population.
+      #
+      # Payload keys:
+      #   id [String]  — id of the parent strategy
+      on :mutate_strategy do |state:, payload:|
+        parent = state[:population].find { |s| s.id == payload.fetch(:id) }
+        next state unless parent
+
+        agent = new
+        child = agent.send(:mutate_one, parent, state, state[:population].size)
+        state.merge(population: state[:population] + [child])
+      end
+
+      # Sync query — best evaluated strategy so far.
+      #
+      # @return [Strategy, nil]
+      on :best do |state:, **|
+        state[:best_strategy]
+      end
+
+      # Sync query — current population.
+      #
+      # @return [Array<Strategy>]
+      on :population do |state:, **|
+        state[:population].dup
+      end
+
+      # Sync query — evolution history (one GenerationReport per generation).
+      #
+      # @return [Array<GenerationReport>]
+      on :history do |state:, **|
+        state[:history].dup
+      end
+
+      # Sync query — current generation number.
+      #
+      # @return [Integer]
+      on :generation do |state:, **|
+        state[:generation]
+      end
+
+      # Update agent configuration.
+      #
+      # Payload keys:
+      #   fitness_fn      [#call]
+      #   llm             [#call]
+      #   population_size [Integer]
+      #   mutation_rate   [Float]   — 0.0–1.0
+      #   elite_fraction  [Float]   — 0.0–1.0
+      on :configure do |state:, payload:|
+        state.merge(
+          payload.slice(:fitness_fn, :llm, :population_size,
+                        :mutation_rate, :elite_fraction).compact
+        )
+      end
+
+      # Clear population and history (configuration is preserved).
+      on :reset do |state:, **|
+        state.merge(population: [], generation: 0, history: [], best_strategy: nil)
+      end
+
+      private
+
+      def score_population(population, fitness_fn)
+        population.map do |s|
+          score = begin
+            fitness_fn.call(s.config).to_f
+          rescue StandardError
+            0.0
+          end
+          Strategy.new(
+            id: s.id, config: s.config, fitness: score,
+            generation: s.generation, parent_ids: s.parent_ids, mutations: s.mutations
+          )
+        end
+      end
+
+      def run_evolution(state)
+        evaluated = state[:population].reject { |s| s.fitness.nil? }
+        return [nil, nil] if evaluated.empty?
+
+        elite_count = [(evaluated.size * state[:elite_fraction]).ceil, 1].max
+        elite       = evaluated.sort_by { |s| -(s.fitness || 0) }.first(elite_count)
+
+        fitnesses = elite.map { |s| s.fitness.to_f }
+        report    = GenerationReport.new(
+          generation:      state[:generation],
+          population_size: state[:population].size,
+          best_fitness:    fitnesses.max.round(6),
+          mean_fitness:    (fitnesses.sum / fitnesses.size).round(6),
+          best_id:         elite.first.id
+        )
+
+        target   = [state[:population_size], elite.size].max
+        children = []
+        idx      = 0
+        until elite.size + children.size >= target
+          parent = elite[idx % elite.size]
+          child  = mutate_one(parent, state, elite.size + idx)
+          children << child
+          idx += 1
+        end
+
+        [elite + children, report]
+      end
+
+      def mutate_one(parent, state, idx)
+        next_gen = state[:generation] + 1
+        config   = if state[:llm]
+          mutate_with_llm(state[:llm], parent.config, next_gen)
+        else
+          mutate_rule_based(parent.config, state[:mutation_rate])
+        end
+
+        Strategy.new(
+          id:         "gen#{next_gen}_#{idx}",
+          config:     config,
+          fitness:    nil,
+          generation: next_gen,
+          parent_ids: [parent.id],
+          mutations:  detect_mutations(parent.config, config)
+        )
+      end
+
+      def mutate_rule_based(config, rate)
+        config.each_with_object({}) do |(k, v), acc|
+          acc[k] = rand < rate ? mutate_value(v) : v
+        end
+      end
+
+      def mutate_value(value)
+        case value
+        when Numeric           then (value * (0.8 + rand * 0.4)).round(6)
+        when TrueClass, FalseClass then !value
+        when Array             then value.empty? ? value : value.sample([1, rand(value.size)].max)
+        else value
+        end
+      end
+
+      def mutate_with_llm(llm, config, generation)
+        result = llm.call(strategy: config, generation: generation)
+        result.is_a?(Hash) ? result : mutate_rule_based(config, 0.3)
+      rescue StandardError
+        mutate_rule_based(config, 0.3)
+      end
+
+      def detect_mutations(original, mutated)
+        original.keys.filter_map do |k|
+          "#{k}: #{original[k].inspect} → #{mutated[k].inspect}" if original[k] != mutated[k]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require_relative "../proactive_agent"
+
+module Igniter
+  module Agents
+    # Polls a set of named services and tracks their health status.
+    #
+    # HealthCheckAgent wraps ProactiveAgent with a +check+ DSL keyword that
+    # registers both the watcher (poll callable) and a trigger that fires
+    # when a service transitions to an unhealthy state.
+    #
+    # The poll callable should:
+    # * Return a truthy value when the service is healthy.
+    # * Return falsy OR raise when the service is unhealthy.
+    #
+    # @example
+    #   class InfraHealth < Igniter::Agents::HealthCheckAgent
+    #     intent "Monitor database, cache, and payment gateway"
+    #     scan_interval 30.0
+    #
+    #     check :database,        poll: -> { DB.ping }
+    #     check :redis,           poll: -> { Redis.current.ping == "PONG" }
+    #     check :payment_gateway, poll: -> { PaymentClient.health_check }
+    #   end
+    #
+    #   ref    = InfraHealth.start
+    #   status = ref.call(:health)    # => { database: :healthy, redis: :unhealthy, … }
+    #   all_ok = ref.call(:all_healthy)
+    class HealthCheckAgent < ProactiveAgent
+      # Recorded when a service's health changes (healthy ↔ unhealthy).
+      Transition = Struct.new(:service, :from, :to, :occurred_at, keyword_init: true)
+
+      proactive_initial_state health: {}, transitions: []
+
+      class << self
+        # Register a service health check.
+        # Calling +check+ registers both the watcher and an unhealthy trigger.
+        #
+        # @param service [Symbol, String]
+        # @param poll    [#call]  — returns truthy = healthy, falsy/raises = unhealthy
+        def check(service, poll:)
+          name = service.to_sym
+
+          # Watcher: map poll result to :healthy / :unhealthy symbol
+          watch(name, poll: -> {
+            begin
+              poll.call ? :healthy : :unhealthy
+            rescue StandardError
+              :unhealthy
+            end
+          })
+
+          # Trigger: fires when service is unhealthy AND previous status differs
+          trigger(:"health_#{name}",
+            condition: ->(ctx) { ctx[name] == :unhealthy },
+            action: ->(state:, context:) {
+              prev   = state[:health][name]
+              status = context[name]
+              health = state[:health].merge(name => status)
+
+              # Only record a transition when the status actually changes
+              if prev != status
+                t = Transition.new(
+                  service:     name,
+                  from:        prev || :unknown,
+                  to:          status,
+                  occurred_at: Time.now
+                )
+                transitions = (state[:transitions] + [t]).last(100)
+                state.merge(health: health, transitions: transitions)
+              else
+                state.merge(health: health)
+              end
+            }
+          )
+        end
+      end
+
+      # ── Inheritance ────────────────────────────────────────────────────────
+      # Re-inject HealthCheckAgent-specific handlers so that anonymous test
+      # classes (Class.new(HealthCheckAgent)) also receive them.
+      def self.inherited(subclass)
+        super  # ProactiveAgent.inherited → resets @handlers, injects proactive ones
+        inject_health_handlers!(subclass)
+      end
+
+      private_class_method def self.inject_health_handlers!(klass)
+        klass.on(:health)      { |state:, **| state.fetch(:health, {}).dup }
+        klass.on(:all_healthy) { |state:, **| state.fetch(:health, {}).values.all? { |v| v == :healthy } }
+        klass.on(:transitions) { |state:, **| state.fetch(:transitions, []).dup }
+        klass.on(:reset)       { |state:, **| state.merge(health: {}, transitions: []) }
+      end
+
+      # Sync query — current health status per service.
+      #
+      # @return [Hash<Symbol, :healthy | :unhealthy>]
+      on :health do |state:, **|
+        state.fetch(:health, {}).dup
+      end
+
+      # Sync query — true when all polled services are healthy.
+      #
+      # @return [Boolean]
+      on :all_healthy do |state:, **|
+        state.fetch(:health, {}).values.all? { |v| v == :healthy }
+      end
+
+      # Sync query — list of recorded health transitions.
+      #
+      # @return [Array<Transition>]
+      on :transitions do |state:, **|
+        state.fetch(:transitions, []).dup
+      end
+
+      # Reset health status and transition history.
+      on :reset do |state:, **|
+        state.merge(health: {}, transitions: [])
+      end
+    end
+  end
+end

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

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