igniter 0.5.0 → 0.5.2

data/lib/igniter/invariant.rb

@@ -1,50 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  # Represents a named condition that must always hold for a contract's outputs.
-  #
-  # An Invariant wraps a block that receives the contract's declared output values
-  # as keyword arguments and returns a truthy value when the condition holds.
-  #
-  # @example
-  #   inv = Igniter::Invariant.new(:total_non_negative) { |total:, **| total >= 0 }
-  #   inv.check(total: 42)    # => nil  (passed)
-  #   inv.check(total: -1)    # => InvariantViolation
-  class Invariant
-    attr_reader :name, :block
-
-    def initialize(name, &block)
-      raise ArgumentError, "invariant :#{name} requires a block" unless block
-
-      @name  = name.to_sym
-      @block = block
-      freeze
-    end
-
-    # Evaluate invariant against the resolved output values.
-    #
-    # @param resolved_values [Hash] output_name => value for all declared outputs
-    # @return [InvariantViolation, nil] nil when the invariant holds
-    def check(resolved_values)
-      passed = block.call(**resolved_values)
-      passed ? nil : InvariantViolation.new(name: name, passed: false)
-    rescue StandardError => e
-      InvariantViolation.new(name: name, passed: false, error: e)
-    end
-  end
-
-  # Records a single invariant check outcome.
-  class InvariantViolation
-    attr_reader :name, :error
-
-    def initialize(name:, passed:, error: nil)
-      @name   = name.to_sym
-      @passed = passed
-      @error  = error
-      freeze
-    end
-
-    def passed? = @passed
-    def failed? = !@passed
-  end
-end

data/lib/igniter/memory/agent_memory.rb

@@ -1,104 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Memory
-    # Facade that pre-fills +agent_id+ on all Store operations.
-    #
-    # Callers interact with AgentMemory instead of the raw Store so they never
-    # have to pass +agent_id:+ explicitly. An optional +session_id+ groups
-    # episodes within a single interaction session.
-    #
-    # @example
-    #   store  = Igniter::Memory::Stores::InMemory.new
-    #   memory = Igniter::Memory::AgentMemory.new(store: store, agent_id: "MyAgent:1")
-    #
-    #   memory.record(type: :tool_call, content: "searched web for Ruby docs")
-    #   memory.recall(query: "Ruby")      # => [Episode, ...]
-    #   memory.remember(:user_tz, "UTC")
-    #   memory.facts                      # => { "user_tz" => Fact }
-    class AgentMemory
-      # @param store      [Store]         backing store implementation
-      # @param agent_id   [String]        identifier for this agent
-      # @param session_id [String, nil]   optional session grouping key
-      def initialize(store:, agent_id:, session_id: nil)
-        @store      = store
-        @agent_id   = agent_id
-        @session_id = session_id
-      end
-
-      # Record a new episode.
-      #
-      # @param type       [String, Symbol] category tag
-      # @param content    [String]         textual description of the event
-      # @param outcome    [String, nil]    result label, e.g. "success"/"failure"
-      # @param importance [Float]          relevance weight 0.0–1.0
-      # @return [Episode]
-      def record(type:, content:, outcome: nil, importance: 0.5)
-        @store.record(
-          agent_id: @agent_id,
-          type: type,
-          content: content,
-          session_id: @session_id,
-          outcome: outcome,
-          importance: importance
-        )
-      end
-
-      # Keyword-search episodes for this agent.
-      #
-      # @param query [String, nil] search term; nil returns most recent
-      # @param limit [Integer]     maximum results (default 10)
-      # @param type  [String, Symbol, nil] optional type filter
-      # @return [Array<Episode>]
-      def recall(query: nil, limit: 10, type: nil)
-        @store.retrieve(agent_id: @agent_id, query: query, limit: limit, type: type)
-      end
-
-      # Store or update a named fact.
-      #
-      # @param key        [String, Symbol]  fact name
-      # @param value      [Object]          fact value
-      # @param confidence [Float]           confidence score 0.0–1.0
-      # @return [Fact]
-      def remember(key, value, confidence: 1.0)
-        @store.store_fact(agent_id: @agent_id, key: key, value: value, confidence: confidence)
-      end
-
-      # Returns all stored facts for this agent.
-      #
-      # @return [Hash{String => Fact}]
-      def facts
-        @store.facts(agent_id: @agent_id)
-      end
-
-      # Returns recent episodes.
-      #
-      # @param last [Integer]              maximum episodes to return
-      # @param type [String, Symbol, nil]  optional type filter
-      # @return [Array<Episode>]
-      def recent(last: 20, type: nil)
-        @store.episodes(agent_id: @agent_id, last: last, type: type)
-      end
-
-      # Run a reflection cycle and record the result.
-      #
-      # @param current_system_prompt [String, nil] current prompt to compare against
-      # @return [ReflectionRecord]
-      def reflect(current_system_prompt: nil)
-        ReflectionCycle.new(store: @store).reflect(
-          agent_id: @agent_id,
-          current_system_prompt: current_system_prompt
-        )
-      end
-
-      # Check whether the agent should run a reflection cycle.
-      #
-      # Returns true when the recent failure rate exceeds the threshold.
-      #
-      # @return [Boolean]
-      def should_reflect?
-        ReflectionCycle.new(store: @store).should_reflect?(agent_id: @agent_id)
-      end
-    end
-  end
-end

data/lib/igniter/memory/episode.rb

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Memory
-    # Immutable value object representing a single recorded event in agent history.
-    #
-    # @!attribute [r] id
-    #   @return [Integer] unique identifier within the store
-    # @!attribute [r] agent_id
-    #   @return [String] identifier of the agent that recorded this episode
-    # @!attribute [r] session_id
-    #   @return [String, nil] optional session grouping identifier
-    # @!attribute [r] ts
-    #   @return [Integer] Unix timestamp of when the episode was recorded
-    # @!attribute [r] type
-    #   @return [String, Symbol] category of the episode (e.g. :tool_call, :response)
-    # @!attribute [r] content
-    #   @return [String] textual description of what happened
-    # @!attribute [r] outcome
-    #   @return [String, nil] result descriptor, e.g. "success" or "failure"
-    # @!attribute [r] importance
-    #   @return [Float] relevance weight in [0.0, 1.0], default 0.5
-    Episode = Struct.new(
-      :id, :agent_id, :session_id, :ts,
-      :type, :content, :outcome, :importance,
-      keyword_init: true
-    )
-  end
-end

data/lib/igniter/memory/fact.rb

@@ -1,27 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Memory
-    # Immutable value object representing a persisted learned fact for an agent.
-    #
-    # Facts represent stable knowledge extracted from experience, keyed by a
-    # string name and associated with a confidence score.
-    #
-    # @!attribute [r] id
-    #   @return [Integer] unique identifier within the store
-    # @!attribute [r] agent_id
-    #   @return [String] identifier of the agent that owns this fact
-    # @!attribute [r] key
-    #   @return [String] fact name (e.g. "user_timezone", "preferred_format")
-    # @!attribute [r] value
-    #   @return [Object] the fact's value
-    # @!attribute [r] confidence
-    #   @return [Float] confidence score in [0.0, 1.0], default 1.0
-    # @!attribute [r] updated_at
-    #   @return [Integer] Unix timestamp of last upsert
-    Fact = Struct.new(
-      :id, :agent_id, :key, :value, :confidence, :updated_at,
-      keyword_init: true
-    )
-  end
-end

data/lib/igniter/memory/memorable.rb

@@ -1,90 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Memory
-    # Mixin that adds episodic memory capabilities to Igniter::Agent and
-    # Igniter::LLM::Executor subclasses (or any class that includes it).
-    #
-    # Including +Memorable+ adds:
-    # * A class-level +enable_memory+ DSL method for opt-in activation
-    # * A +memory+ instance accessor returning a bound AgentMemory facade
-    # * Automatic agent_id derived from the class name and object_id
-    #
-    # Memory is NOT enabled by default — call +enable_memory+ in the class body.
-    #
-    # == Example
-    #
-    #   class MyAgent < Igniter::Agent
-    #     include Igniter::Memory::Memorable
-    #
-    #     enable_memory store: Igniter::Memory::Stores::InMemory.new
-    #
-    #     on :task do |state:, payload:, **|
-    #       memory.record(type: :task, content: payload[:description])
-    #       # ... handle task
-    #       state
-    #     end
-    #   end
-    #
-    # == Inheritance
-    #
-    # Subclasses inherit +memory_enabled?+ and +memory_store+ from their parent.
-    # Each subclass can override them independently.
-    module Memorable
-      def self.included(base)
-        base.extend(ClassMethods)
-        base.instance_variable_set(:@memory_store, nil)
-        base.instance_variable_set(:@memory_enabled, false)
-      end
-
-      module ClassMethods
-        # Enable episodic memory for this class.
-        #
-        # @param store [Store, nil] backing store; falls back to Igniter::Memory.default_store
-        # @return [void]
-        def enable_memory(store: nil)
-          @memory_enabled = true
-          @memory_store   = store || Igniter::Memory.default_store
-        end
-
-        # Returns the configured memory store, walking up the inheritance chain
-        # if none is set on this class.
-        #
-        # @return [Store]
-        def memory_store
-          @memory_store ||
-            (superclass.respond_to?(:memory_store) ? superclass.memory_store : Igniter::Memory.default_store)
-        end
-
-        # Returns whether memory has been enabled for this class or any ancestor.
-        #
-        # @return [Boolean]
-        def memory_enabled?
-          @memory_enabled ||
-            (superclass.respond_to?(:memory_enabled?) && superclass.memory_enabled?)
-        end
-      end
-
-      # Returns the AgentMemory facade bound to this instance.
-      #
-      # Lazily initialised on first access. The agent_id incorporates the class
-      # name and object_id to keep instances isolated.
-      #
-      # @return [AgentMemory]
-      def memory
-        @memory ||= AgentMemory.new(
-          store: self.class.memory_store,
-          agent_id: memory_agent_id,
-          session_id: respond_to?(:session_id, true) ? session_id : nil
-        )
-      end
-
-      private
-
-      def memory_agent_id
-        cls_name = self.class.name || "anonymous"
-        "#{cls_name}:#{object_id}"
-      end
-    end
-  end
-end

data/lib/igniter/memory/reflection_cycle.rb

@@ -1,96 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Memory
-    # Evaluates recent episodes and produces a ReflectionRecord.
-    #
-    # ReflectionCycle can operate in two modes:
-    #
-    # * **Rule-based** (default) — analyses failure rates using simple heuristics,
-    #   requiring no LLM. Always available.
-    # * **LLM-assisted** — delegates to an LLM executor for a richer summary and
-    #   an optional system-prompt patch. Enabled by passing an +llm:+ object.
-    #
-    # @example Rule-based reflection
-    #   cycle = Igniter::Memory::ReflectionCycle.new(store: store)
-    #   rec   = cycle.reflect(agent_id: "MyAgent:1")
-    #   # => ReflectionRecord (summary describes failure breakdown)
-    #
-    # @example With failure threshold check
-    #   cycle.should_reflect?(agent_id: "MyAgent:1")
-    #   # => true when recent failures >= DEFAULT_FAILURE_THRESHOLD
-    class ReflectionCycle
-      DEFAULT_FAILURE_THRESHOLD = 5
-      DEFAULT_WINDOW            = 50
-
-      # @param store             [Store]    backing episode store
-      # @param failure_threshold [Integer]  minimum failures to trigger reflection
-      # @param window            [Integer]  how many recent episodes to inspect
-      # @param llm               [#call, nil] optional LLM executor for smart reflection
-      def initialize(store:, failure_threshold: DEFAULT_FAILURE_THRESHOLD,
-                     window: DEFAULT_WINDOW, llm: nil)
-        @store             = store
-        @failure_threshold = failure_threshold
-        @window            = window
-        @llm               = llm
-      end
-
-      # Check whether a reflection cycle should be triggered.
-      #
-      # Returns true when the number of recent "failure" outcomes meets or
-      # exceeds the configured +failure_threshold+.
-      #
-      # @param agent_id [String]
-      # @return [Boolean]
-      def should_reflect?(agent_id:)
-        recent   = @store.episodes(agent_id: agent_id, last: @window)
-        failures = recent.count { |e| e.outcome == "failure" }
-        failures >= @failure_threshold
-      end
-
-      # Run a reflection cycle and persist the result.
-      #
-      # Analyses the most recent +window+ episodes and produces a
-      # ReflectionRecord with a summary (and optional system-prompt patch when
-      # an LLM is configured).
-      #
-      # @param agent_id              [String]
-      # @param current_system_prompt [String, nil] passed to the LLM if available
-      # @return [ReflectionRecord]
-      def reflect(agent_id:, current_system_prompt: nil) # rubocop:disable Metrics/MethodLength
-        recent = @store.episodes(agent_id: agent_id, last: @window)
-        summary, patch = if @llm
-                           smart_reflect(recent, current_system_prompt)
-                         else
-                           rule_based_reflect(recent)
-                         end
-
-        @store.record_reflection(
-          agent_id: agent_id,
-          summary: summary,
-          system_patch: patch
-        )
-      end
-
-      private
-
-      def rule_based_reflect(episodes) # rubocop:disable Metrics/CyclomaticComplexity
-        failures      = episodes.select { |e| e.outcome == "failure" }
-        failure_types = failures.group_by(&:type).transform_values(&:count)
-        top           = failure_types.max_by { |_, v| v }
-
-        summary = "#{failures.size}/#{episodes.size} failures. " \
-                  "Top failure type: #{top&.first || "none"} (#{top&.last || 0}\xc3\x97)"
-        [summary, nil]
-      end
-
-      def smart_reflect(episodes, current_system_prompt)
-        result = @llm.call(
-          episodes: episodes.map { |e| { type: e.type, content: e.content, outcome: e.outcome } },
-          current_system_prompt: current_system_prompt
-        )
-        [result[:summary], result[:system_patch]]
-      end
-    end
-  end
-end

data/lib/igniter/memory/reflection_record.rb

@@ -1,28 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Memory
-    # Immutable value object representing the output of a reflection cycle.
-    #
-    # A ReflectionRecord captures the summary and optional system-prompt patch
-    # produced by a ReflectionCycle run. It can be applied to update an agent's
-    # system prompt or used as an audit trail.
-    #
-    # @!attribute [r] id
-    #   @return [Integer] unique identifier within the store
-    # @!attribute [r] agent_id
-    #   @return [String] identifier of the agent this reflection belongs to
-    # @!attribute [r] ts
-    #   @return [Integer] Unix timestamp when the reflection was recorded
-    # @!attribute [r] summary
-    #   @return [String] human-readable summary of findings
-    # @!attribute [r] system_patch
-    #   @return [String, nil] optional suggested replacement/patch for system prompt
-    # @!attribute [r] applied
-    #   @return [Boolean] whether this reflection has been applied to the agent
-    ReflectionRecord = Struct.new(
-      :id, :agent_id, :ts, :summary, :system_patch, :applied,
-      keyword_init: true
-    )
-  end
-end

data/lib/igniter/memory/store.rb

@@ -1,115 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Memory
-    # Abstract base class defining the Store interface for episodic memory.
-    #
-    # Concrete adapters must subclass Store and implement all public methods.
-    # All methods raise +NotImplementedError+ by default.
-    #
-    # == Interface
-    #
-    #   store.record(agent_id:, type:, content:)             # => Episode
-    #   store.episodes(agent_id:, last: 50)                  # => Array<Episode>
-    #   store.retrieve(agent_id:, query: "keyword")          # => Array<Episode>
-    #   store.store_fact(agent_id:, key:, value:)
-    #   store.facts(agent_id:)                               # => Hash{key => Fact}
-    #   store.record_reflection(agent_id:, summary:)         # => ReflectionRecord
-    #   store.reflections(agent_id:)                         # => Array<ReflectionRecord>
-    #   store.apply_reflection(id:)                          # => true/false
-    #   store.clear(agent_id:)
-    class Store
-      # Record an episode. Returns the persisted Episode.
-      #
-      # @param agent_id  [String]         identifier of the owning agent
-      # @param type      [String, Symbol]  category tag for the episode
-      # @param content   [String]          textual description of the event
-      # @param session_id [String, nil]    optional session grouping key
-      # @param outcome   [String, nil]     result label, e.g. "success"/"failure"
-      # @param importance [Float]          relevance weight 0.0-1.0 (default 0.5)
-      # @return [Episode]
-      def record(agent_id:, type:, content:, session_id: nil, outcome: nil, importance: 0.5) # rubocop:disable Metrics/ParameterLists
-        raise NotImplementedError, "#{self.class}#record not implemented"
-      end
-
-      # Return episodes for an agent, newest last.
-      #
-      # @param agent_id [String]         identifier of the agent
-      # @param last     [Integer]        maximum number of episodes to return
-      # @param type     [String, Symbol, nil] optional type filter
-      # @return [Array<Episode>]
-      def episodes(agent_id:, last: 50, type: nil)
-        raise NotImplementedError, "#{self.class}#episodes not implemented"
-      end
-
-      # Keyword-search episodes. Returns Array<Episode>.
-      #
-      # When +query+ is nil, returns the last +limit+ episodes.
-      # When +query+ is provided, filters by case-insensitive substring or FTS match.
-      #
-      # @param agent_id [String]
-      # @param query    [String, nil] search term
-      # @param limit    [Integer]     maximum results (default 10)
-      # @param type     [String, Symbol, nil] optional type filter
-      # @return [Array<Episode>]
-      def retrieve(agent_id:, query: nil, limit: 10, type: nil)
-        raise NotImplementedError, "#{self.class}#retrieve not implemented"
-      end
-
-      # Upsert a fact for an agent.
-      #
-      # @param agent_id   [String]  identifier of the owning agent
-      # @param key        [String]  fact name
-      # @param value      [Object]  fact value
-      # @param confidence [Float]   confidence score 0.0-1.0 (default 1.0)
-      # @return [Fact]
-      def store_fact(agent_id:, key:, value:, confidence: 1.0)
-        raise NotImplementedError, "#{self.class}#store_fact not implemented"
-      end
-
-      # Returns all facts for an agent as a Hash keyed by string key.
-      #
-      # @param agent_id [String]
-      # @return [Hash{String => Fact}]
-      def facts(agent_id:)
-        raise NotImplementedError, "#{self.class}#facts not implemented"
-      end
-
-      # Store a reflection record. Returns the persisted ReflectionRecord.
-      #
-      # @param agent_id    [String]      owning agent identifier
-      # @param summary     [String]      human-readable reflection summary
-      # @param system_patch [String, nil] optional suggested system prompt patch
-      # @param applied     [Boolean]     whether already applied (default false)
-      # @return [ReflectionRecord]
-      def record_reflection(agent_id:, summary:, system_patch: nil, applied: false)
-        raise NotImplementedError, "#{self.class}#record_reflection not implemented"
-      end
-
-      # Returns reflection records for an agent.
-      #
-      # @param agent_id [String]
-      # @param applied  [Boolean, nil] nil returns all; true/false filters by applied flag
-      # @return [Array<ReflectionRecord>]
-      def reflections(agent_id:, applied: nil)
-        raise NotImplementedError, "#{self.class}#reflections not implemented"
-      end
-
-      # Mark a reflection as applied.
-      #
-      # @param id [Integer] reflection identifier
-      # @return [Boolean] true if found and updated, false if not found
-      def apply_reflection(id:)
-        raise NotImplementedError, "#{self.class}#apply_reflection not implemented"
-      end
-
-      # Clear all stored data for an agent.
-      #
-      # @param agent_id [String]
-      # @return [void]
-      def clear(agent_id:)
-        raise NotImplementedError, "#{self.class}#clear not implemented"
-      end
-    end
-  end
-end

data/lib/igniter/memory/stores/in_memory.rb

@@ -1,136 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Memory
-    module Stores
-      # Thread-safe in-memory implementation of the Store interface.
-      #
-      # Stores all data in process memory. Suitable for testing and
-      # single-process applications where persistence is not required.
-      # All operations are protected by a single Mutex for thread safety.
-      #
-      # @example
-      #   store = Igniter::Memory::Stores::InMemory.new
-      #   ep    = store.record(agent_id: "bot:1", type: :tool_call, content: "searched web")
-      #   store.episodes(agent_id: "bot:1") # => [ep]
-      class InMemory < Store
-        def initialize # rubocop:disable Lint/MissingSuper
-          @episodes    = []
-          @facts       = {}
-          @reflections = []
-          @seq         = 0
-          @mutex       = Mutex.new
-        end
-
-        # @see Store#record
-        def record(agent_id:, type:, content:, session_id: nil, outcome: nil, importance: 0.5) # rubocop:disable Metrics/ParameterLists, Metrics/MethodLength
-          @mutex.synchronize do
-            ep = Episode.new(
-              id: next_id,
-              agent_id: agent_id,
-              session_id: session_id,
-              ts: Time.now.to_i,
-              type: type,
-              content: content,
-              outcome: outcome,
-              importance: importance
-            )
-            @episodes << ep
-            ep
-          end
-        end
-
-        # @see Store#episodes
-        def episodes(agent_id:, last: 50, type: nil)
-          @mutex.synchronize do
-            result = @episodes.select { |e| e.agent_id == agent_id }
-            result = result.select { |e| e.type == type } if type
-            result.last(last)
-          end
-        end
-
-        # @see Store#retrieve
-        def retrieve(agent_id:, query: nil, limit: 10, type: nil)
-          eps = episodes(agent_id: agent_id, last: 1000, type: type)
-          return eps.last(limit) unless query
-
-          q = query.to_s.downcase
-          eps.select { |e| e.content.to_s.downcase.include?(q) }.last(limit)
-        end
-
-        # @see Store#store_fact
-        def store_fact(agent_id:, key:, value:, confidence: 1.0) # rubocop:disable Metrics/MethodLength
-          @mutex.synchronize do
-            @facts[agent_id] ||= {}
-            fact = Fact.new(
-              id: next_id,
-              agent_id: agent_id,
-              key: key.to_s,
-              value: value,
-              confidence: confidence,
-              updated_at: Time.now.to_i
-            )
-            @facts[agent_id][key.to_s] = fact
-            fact
-          end
-        end
-
-        # @see Store#facts
-        def facts(agent_id:)
-          @mutex.synchronize { (@facts[agent_id] || {}).dup }
-        end
-
-        # @see Store#record_reflection
-        def record_reflection(agent_id:, summary:, system_patch: nil, applied: false) # rubocop:disable Metrics/MethodLength
-          @mutex.synchronize do
-            rec = ReflectionRecord.new(
-              id: next_id,
-              agent_id: agent_id,
-              ts: Time.now.to_i,
-              summary: summary,
-              system_patch: system_patch,
-              applied: applied
-            )
-            @reflections << rec
-            rec
-          end
-        end
-
-        # @see Store#reflections
-        def reflections(agent_id:, applied: nil)
-          @mutex.synchronize do
-            result = @reflections.select { |r| r.agent_id == agent_id }
-            applied.nil? ? result : result.select { |r| r.applied == applied }
-          end
-        end
-
-        # @see Store#apply_reflection
-        def apply_reflection(id:)
-          @mutex.synchronize do
-            rec = @reflections.find { |r| r.id == id }
-            return false unless rec
-
-            idx = @reflections.index(rec)
-            @reflections[idx] = ReflectionRecord.new(**rec.to_h.merge(applied: true))
-            true
-          end
-        end
-
-        # @see Store#clear
-        def clear(agent_id:)
-          @mutex.synchronize do
-            @episodes.reject! { |e| e.agent_id == agent_id }
-            @facts.delete(agent_id)
-            @reflections.reject! { |r| r.agent_id == agent_id }
-          end
-        end
-
-        private
-
-        def next_id
-          @seq += 1
-        end
-      end
-    end
-  end
-end