lex-agentic-learning 0.1.0

data/spec/legion/extensions/agentic/learning/habit/helpers/constants_spec.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Learning::Habit::Helpers::Constants do
+  describe 'MATURITY_STAGES' do
+    it 'has exactly 5 stages' do
+      expect(described_class::MATURITY_STAGES.size).to eq(5)
+    end
+
+    it 'includes all expected stages' do
+      expect(described_class::MATURITY_STAGES).to include(:novel)
+      expect(described_class::MATURITY_STAGES).to include(:learning)
+      expect(described_class::MATURITY_STAGES).to include(:practiced)
+      expect(described_class::MATURITY_STAGES).to include(:habitual)
+      expect(described_class::MATURITY_STAGES).to include(:automatic)
+    end
+
+    it 'is ordered from least to most mature' do
+      stages = described_class::MATURITY_STAGES
+      expect(stages.first).to eq(:novel)
+      expect(stages.last).to eq(:automatic)
+    end
+  end
+
+  describe 'MATURITY_THRESHOLDS' do
+    it 'has a threshold for each maturity stage' do
+      described_class::MATURITY_STAGES.each do |stage|
+        expect(described_class::MATURITY_THRESHOLDS).to have_key(stage)
+      end
+    end
+
+    it 'thresholds increase with maturity' do
+      stages = described_class::MATURITY_STAGES
+      thresholds = stages.map { |s| described_class::MATURITY_THRESHOLDS[s] }
+      expect(thresholds).to eq(thresholds.sort)
+    end
+
+    it 'novel starts at 0' do
+      expect(described_class::MATURITY_THRESHOLDS[:novel]).to eq(0)
+    end
+  end
+
+  describe 'COGNITIVE_COST' do
+    it 'has a cost for each maturity stage' do
+      described_class::MATURITY_STAGES.each do |stage|
+        expect(described_class::COGNITIVE_COST).to have_key(stage)
+      end
+    end
+
+    it 'cognitive cost decreases with maturity' do
+      stages = described_class::MATURITY_STAGES
+      costs  = stages.map { |s| described_class::COGNITIVE_COST[s] }
+      expect(costs).to eq(costs.sort.reverse)
+    end
+
+    it 'novel has maximum cognitive cost of 1.0' do
+      expect(described_class::COGNITIVE_COST[:novel]).to eq(1.0)
+    end
+
+    it 'automatic has minimum cognitive cost' do
+      expect(described_class::COGNITIVE_COST[:automatic]).to be < described_class::COGNITIVE_COST[:habitual]
+    end
+  end
+
+  describe 'numeric constants' do
+    it 'REINFORCEMENT_RATE is positive' do
+      expect(described_class::REINFORCEMENT_RATE).to be > 0
+    end
+
+    it 'DECAY_RATE is positive' do
+      expect(described_class::DECAY_RATE).to be > 0
+    end
+
+    it 'MIN_SEQUENCE_LENGTH is at least 2' do
+      expect(described_class::MIN_SEQUENCE_LENGTH).to be >= 2
+    end
+
+    it 'MAX_SEQUENCE_LENGTH is greater than MIN_SEQUENCE_LENGTH' do
+      expect(described_class::MAX_SEQUENCE_LENGTH).to be > described_class::MIN_SEQUENCE_LENGTH
+    end
+
+    it 'MAX_HABITS is a positive integer' do
+      expect(described_class::MAX_HABITS).to be > 0
+    end
+
+    it 'SIMILARITY_THRESHOLD is between 0 and 1' do
+      expect(described_class::SIMILARITY_THRESHOLD).to be_between(0.0, 1.0)
+    end
+
+    it 'CHUNKING_THRESHOLD is a positive integer' do
+      expect(described_class::CHUNKING_THRESHOLD).to be > 0
+    end
+
+    it 'HABIT_STRENGTH_FLOOR is positive' do
+      expect(described_class::HABIT_STRENGTH_FLOOR).to be > 0
+    end
+  end
+
+  describe 'CONTEXT_DIMENSIONS' do
+    it 'includes :domain' do
+      expect(described_class::CONTEXT_DIMENSIONS).to include(:domain)
+    end
+
+    it 'includes :mood' do
+      expect(described_class::CONTEXT_DIMENSIONS).to include(:mood)
+    end
+
+    it 'includes :time_of_day' do
+      expect(described_class::CONTEXT_DIMENSIONS).to include(:time_of_day)
+    end
+
+    it 'includes :trigger' do
+      expect(described_class::CONTEXT_DIMENSIONS).to include(:trigger)
+    end
+  end
+end

data/spec/legion/extensions/agentic/learning/habit/helpers/habit_store_spec.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Learning::Habit::Helpers::HabitStore do
+  subject(:store) { described_class.new }
+
+  let(:chunking_threshold) { Legion::Extensions::Agentic::Learning::Habit::Helpers::Constants::CHUNKING_THRESHOLD }
+
+  describe '#initialize' do
+    it 'starts with empty habits' do
+      expect(store.habits).to be_empty
+    end
+
+    it 'starts with empty action buffer' do
+      expect(store.action_buffer).to be_empty
+    end
+  end
+
+  describe '#record_action' do
+    it 'adds an entry to the action buffer' do
+      store.record_action(:fetch)
+      expect(store.action_buffer.size).to eq(1)
+    end
+
+    it 'stores the action as a symbol' do
+      store.record_action('fetch')
+      expect(store.action_buffer.last[:action]).to eq(:fetch)
+    end
+
+    it 'stores associated context' do
+      store.record_action(:fetch, context: { domain: :api })
+      expect(store.action_buffer.last[:context]).to eq({ domain: :api })
+    end
+
+    it 'evicts oldest entry when buffer exceeds MAX_BUFFER_SIZE' do
+      51.times { |i| store.record_action(:"action_#{i}") }
+      expect(store.action_buffer.size).to eq(50)
+    end
+  end
+
+  describe '#detect_patterns' do
+    context 'when a subsequence repeats enough times' do
+      it 'detects and stores a new habit' do
+        # Fill buffer with CHUNKING_THRESHOLD repetitions of the same 2-action sequence
+        chunking_threshold.times do
+          store.record_action(:fetch)
+          store.record_action(:parse)
+        end
+        new_habits = store.detect_patterns
+        expect(new_habits).not_to be_empty
+      end
+
+      it 'returns the detected habit objects' do
+        chunking_threshold.times do
+          store.record_action(:a)
+          store.record_action(:b)
+        end
+        new_habits = store.detect_patterns
+        expect(new_habits.first).to be_a(Legion::Extensions::Agentic::Learning::Habit::Helpers::ActionSequence)
+      end
+    end
+
+    context 'when a subsequence does not repeat enough times' do
+      it 'returns empty array' do
+        store.record_action(:fetch)
+        store.record_action(:parse)
+        new_habits = store.detect_patterns
+        expect(new_habits).to be_empty
+      end
+    end
+
+    context 'when an existing habit matches' do
+      it 'reinforces the existing habit rather than creating a new one' do
+        # Seed initial habit
+        chunking_threshold.times do
+          store.record_action(:x)
+          store.record_action(:y)
+        end
+        store.detect_patterns
+        expect(store.habits.size).to be >= 1
+
+        # The same sequence already exists — find it and record its execution count
+        existing = store.habits.values.find { |h| h.actions == %i[x y] }
+        expect(existing).not_to be_nil
+        before_count = existing.execution_count
+
+        # Clear the buffer and re-seed to isolate the existing-habit path
+        store.action_buffer.clear
+        chunking_threshold.times do
+          store.record_action(:x)
+          store.record_action(:y)
+        end
+        store.detect_patterns
+
+        # Existing habit should have been reinforced
+        expect(existing.execution_count).to be > before_count
+      end
+    end
+  end
+
+  describe '#find_matching' do
+    before do
+      chunking_threshold.times do
+        store.record_action(:fetch, context: { domain: :api })
+        store.record_action(:parse, context: { domain: :api })
+      end
+      store.detect_patterns
+    end
+
+    it 'returns habits matching the given context' do
+      matches = store.find_matching(context: { domain: :api })
+      expect(matches).not_to be_empty
+    end
+
+    it 'returns habits sorted by strength descending' do
+      matches = store.find_matching(context: { domain: :api })
+      strengths = matches.map(&:strength)
+      expect(strengths).to eq(strengths.sort.reverse)
+    end
+
+    it 'returns empty when no context match' do
+      matches = store.find_matching(context: { domain: :db })
+      expect(matches).to be_empty
+    end
+  end
+
+  describe '#get' do
+    it 'returns nil for unknown id' do
+      expect(store.get('unknown-id')).to be_nil
+    end
+
+    it 'returns the habit for a known id' do
+      chunking_threshold.times do
+        store.record_action(:m)
+        store.record_action(:n)
+      end
+      store.detect_patterns
+      id = store.habits.keys.first
+      expect(store.get(id)).to be_a(Legion::Extensions::Agentic::Learning::Habit::Helpers::ActionSequence)
+    end
+  end
+
+  describe '#reinforce' do
+    it 'returns nil for unknown id' do
+      expect(store.reinforce('unknown', success: true)).to be_nil
+    end
+
+    it 'records execution on the habit' do
+      chunking_threshold.times do
+        store.record_action(:p)
+        store.record_action(:q)
+      end
+      store.detect_patterns
+      id     = store.habits.keys.first
+      before = store.get(id).execution_count
+      store.reinforce(id, success: true)
+      expect(store.get(id).execution_count).to be > before
+    end
+  end
+
+  describe '#decay_all' do
+    before do
+      chunking_threshold.times do
+        store.record_action(:d)
+        store.record_action(:e)
+      end
+      store.detect_patterns
+    end
+
+    it 'returns count of removed habits when habits fall below floor' do
+      # Force strength below floor by setting it directly
+      store.habits.each_value do |h|
+        h.instance_variable_set(:@strength, 0.05)
+      end
+      removed = store.decay_all
+      expect(removed).to be >= 0
+    end
+
+    it 'returns 0 when all habits survive decay' do
+      store.habits.each_value do |h|
+        h.instance_variable_set(:@strength, 0.9)
+      end
+      removed = store.decay_all
+      expect(removed).to eq(0)
+    end
+
+    it 'removes habits that fall below the floor' do
+      store.habits.each_value do |h|
+        h.instance_variable_set(:@strength, 0.05)
+      end
+      store.decay_all
+      expect(store.habits).to be_empty
+    end
+  end
+
+  describe '#merge_similar' do
+    it 'returns 0 when there is only one habit' do
+      chunking_threshold.times do
+        store.record_action(:a)
+        store.record_action(:b)
+      end
+      store.detect_patterns
+      expect(store.merge_similar).to eq(0)
+    end
+
+    it 'merges highly similar habits and reduces the count' do
+      # Create two nearly identical habits manually
+      habit_a = Legion::Extensions::Agentic::Learning::Habit::Helpers::ActionSequence.new(actions: %i[x y z])
+      habit_b = Legion::Extensions::Agentic::Learning::Habit::Helpers::ActionSequence.new(actions: %i[x y z])
+      store.habits[habit_a.id] = habit_a
+      store.habits[habit_b.id] = habit_b
+
+      before = store.habits.size
+      merged = store.merge_similar
+      expect(merged).to eq(1)
+      expect(store.habits.size).to eq(before - 1)
+    end
+  end
+
+  describe '#by_maturity' do
+    it 'returns habits at the specified maturity stage' do
+      chunking_threshold.times do
+        store.record_action(:f)
+        store.record_action(:g)
+      end
+      store.detect_patterns
+      novel_habits = store.by_maturity(:novel)
+      novel_habits.each { |h| expect(h.maturity).to eq(:novel) }
+    end
+
+    it 'returns empty array when no habits at stage' do
+      expect(store.by_maturity(:automatic)).to be_empty
+    end
+  end
+
+  describe '#stats' do
+    it 'returns total count of 0 when empty' do
+      expect(store.stats[:total]).to eq(0)
+    end
+
+    it 'returns correct total after detecting patterns' do
+      chunking_threshold.times do
+        store.record_action(:h)
+        store.record_action(:i)
+      end
+      store.detect_patterns
+      expect(store.stats[:total]).to be >= 1
+    end
+
+    it 'includes per_maturity breakdown' do
+      expect(store.stats[:per_maturity]).to be_a(Hash)
+    end
+
+    it 'includes avg_strength' do
+      expect(store.stats[:avg_strength]).to be_a(Numeric)
+    end
+
+    it 'returns nil oldest when empty' do
+      expect(store.stats[:oldest]).to be_nil
+    end
+  end
+
+  describe '#evict_if_needed' do
+    it 'removes weakest habit when over MAX_HABITS' do
+      # Insert MAX_HABITS + 1 habits directly
+      (Legion::Extensions::Agentic::Learning::Habit::Helpers::Constants::MAX_HABITS + 1).times do |i|
+        h = Legion::Extensions::Agentic::Learning::Habit::Helpers::ActionSequence.new(actions: [:"a#{i}", :"b#{i}"])
+        h.instance_variable_set(:@strength, (i + 1).to_f / 1000)
+        store.habits[h.id] = h
+      end
+      store.evict_if_needed
+      expect(store.habits.size).to eq(Legion::Extensions::Agentic::Learning::Habit::Helpers::Constants::MAX_HABITS)
+    end
+  end
+end

data/spec/legion/extensions/agentic/learning/habit/runners/habit_spec.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/learning/habit/client'
+
+RSpec.describe Legion::Extensions::Agentic::Learning::Habit::Runners::Habit do
+  let(:habit_store) { Legion::Extensions::Agentic::Learning::Habit::Helpers::HabitStore.new }
+  let(:client) { Legion::Extensions::Agentic::Learning::Habit::Client.new(habit_store: habit_store) }
+
+  let(:chunking_threshold) { Legion::Extensions::Agentic::Learning::Habit::Helpers::Constants::CHUNKING_THRESHOLD }
+
+  def seed_habit
+    chunking_threshold.times do
+      habit_store.record_action(:fetch)
+      habit_store.record_action(:parse)
+    end
+    habit_store.detect_patterns
+    habit_store.habits.values.first
+  end
+
+  describe '#observe_action' do
+    it 'returns recorded: true' do
+      result = client.observe_action(action: :fetch)
+      expect(result[:recorded]).to be true
+    end
+
+    it 'includes the action in response' do
+      result = client.observe_action(action: :fetch)
+      expect(result[:action]).to eq(:fetch)
+    end
+
+    it 'includes new_habits_detected count' do
+      result = client.observe_action(action: :fetch)
+      expect(result).to have_key(:new_habits_detected)
+    end
+
+    it 'detects new habits after sufficient repetitions' do
+      (chunking_threshold - 1).times do
+        client.observe_action(action: :x)
+        client.observe_action(action: :y)
+      end
+      client.observe_action(action: :x)
+      # The final observe adds the action; next observe_action with :y should trigger detection
+      client.observe_action(action: :y)
+      expect(habit_store.habits.size).to be >= 0
+    end
+
+    it 'includes habits array in response' do
+      result = client.observe_action(action: :fetch)
+      expect(result[:habits]).to be_an(Array)
+    end
+  end
+
+  describe '#suggest_habit' do
+    context 'when no matching habits exist' do
+      it 'returns suggestion: nil' do
+        result = client.suggest_habit(context: { domain: :api })
+        expect(result[:suggestion]).to be_nil
+      end
+
+      it 'returns reason: :no_matching_habits' do
+        result = client.suggest_habit(context: { domain: :api })
+        expect(result[:reason]).to eq(:no_matching_habits)
+      end
+    end
+
+    context 'when matching habits exist' do
+      before do
+        chunking_threshold.times do
+          habit_store.record_action(:fetch, context: { domain: :api })
+          habit_store.record_action(:parse, context: { domain: :api })
+        end
+        habit_store.detect_patterns
+      end
+
+      it 'returns a suggestion hash' do
+        result = client.suggest_habit(context: { domain: :api })
+        expect(result[:suggestion]).to be_a(Hash)
+      end
+
+      it 'returns cognitive_savings as a positive value' do
+        result = client.suggest_habit(context: { domain: :api })
+        expect(result[:cognitive_savings]).to be > 0
+      end
+
+      it 'includes alternatives array' do
+        result = client.suggest_habit(context: { domain: :api })
+        expect(result[:alternatives]).to be_an(Array)
+      end
+    end
+  end
+
+  describe '#execute_habit' do
+    context 'when habit not found' do
+      it 'returns error: :not_found' do
+        result = client.execute_habit(id: 'nonexistent')
+        expect(result[:error]).to eq(:not_found)
+      end
+    end
+
+    context 'when habit exists' do
+      it 'returns executed: true' do
+        habit  = seed_habit
+        result = client.execute_habit(id: habit.id)
+        expect(result[:executed]).to be true
+      end
+
+      it 'returns the updated habit hash' do
+        habit  = seed_habit
+        result = client.execute_habit(id: habit.id)
+        expect(result[:habit]).to be_a(Hash)
+        expect(result[:habit][:id]).to eq(habit.id)
+      end
+
+      it 'returns cognitive_cost' do
+        habit  = seed_habit
+        result = client.execute_habit(id: habit.id)
+        expect(result[:cognitive_cost]).to be_a(Numeric)
+      end
+
+      it 'increments the execution count' do
+        habit  = seed_habit
+        before = habit.execution_count
+        client.execute_habit(id: habit.id, success: true)
+        expect(habit.execution_count).to eq(before + 1)
+      end
+    end
+  end
+
+  describe '#decay_habits' do
+    it 'returns decayed: true' do
+      result = client.decay_habits
+      expect(result[:decayed]).to be true
+    end
+
+    it 'returns removed_count' do
+      result = client.decay_habits
+      expect(result).to have_key(:removed_count)
+    end
+
+    it 'removes habits that fall below floor' do
+      habit = seed_habit
+      habit.instance_variable_set(:@strength, 0.05)
+      client.decay_habits
+      expect(habit_store.get(habit.id)).to be_nil
+    end
+  end
+
+  describe '#merge_habits' do
+    it 'returns merged_count' do
+      result = client.merge_habits
+      expect(result).to have_key(:merged_count)
+    end
+
+    it 'returns 0 when no similar habits to merge' do
+      result = client.merge_habits
+      expect(result[:merged_count]).to eq(0)
+    end
+
+    it 'merges identical habits' do
+      # Manually insert two identical habits
+      h1 = Legion::Extensions::Agentic::Learning::Habit::Helpers::ActionSequence.new(actions: %i[p q r])
+      h2 = Legion::Extensions::Agentic::Learning::Habit::Helpers::ActionSequence.new(actions: %i[p q r])
+      habit_store.habits[h1.id] = h1
+      habit_store.habits[h2.id] = h2
+
+      result = client.merge_habits
+      expect(result[:merged_count]).to eq(1)
+    end
+  end
+
+  describe '#habit_stats' do
+    it 'returns a hash with total key' do
+      result = client.habit_stats
+      expect(result).to have_key(:total)
+    end
+
+    it 'returns per_maturity breakdown' do
+      result = client.habit_stats
+      expect(result[:per_maturity]).to be_a(Hash)
+    end
+
+    it 'returns avg_strength' do
+      result = client.habit_stats
+      expect(result[:avg_strength]).to be_a(Numeric)
+    end
+  end
+
+  describe '#habit_repertoire' do
+    context 'when no maturity filter' do
+      it 'returns all habits' do
+        seed_habit
+        result = client.habit_repertoire
+        expect(result[:habits]).to be_an(Array)
+        expect(result[:total]).to be >= 1
+      end
+    end
+
+    context 'with maturity filter' do
+      it 'returns only habits at the given maturity stage' do
+        seed_habit
+        result = client.habit_repertoire(maturity: :novel)
+        result[:habits].each do |h|
+          expect(h[:maturity]).to eq(:novel)
+        end
+      end
+    end
+
+    it 'respects limit parameter' do
+      10.times do |i|
+        h = Legion::Extensions::Agentic::Learning::Habit::Helpers::ActionSequence.new(actions: [:"action#{i}", :"step#{i}"])
+        habit_store.habits[h.id] = h
+      end
+      result = client.habit_repertoire(limit: 3)
+      expect(result[:habits].size).to be <= 3
+    end
+
+    it 'sorts by strength descending' do
+      3.times do |i|
+        h = Legion::Extensions::Agentic::Learning::Habit::Helpers::ActionSequence.new(actions: [:"s#{i}", :"t#{i}"])
+        h.instance_variable_set(:@strength, (i + 1).to_f / 10)
+        habit_store.habits[h.id] = h
+      end
+      result = client.habit_repertoire
+      strengths = result[:habits].map { |h| h[:strength] }
+      expect(strengths).to eq(strengths.sort.reverse)
+    end
+  end
+end

data/spec/legion/extensions/agentic/learning/hebbian/client_spec.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Learning::Hebbian::Client do
+  subject(:client) { described_class.new }
+
+  it 'includes Runners::HebbianAssembly' do
+    expect(described_class.ancestors).to include(Legion::Extensions::Agentic::Learning::Hebbian::Runners::HebbianAssembly)
+  end
+
+  it 'supports full Hebbian learning lifecycle' do
+    # Repeatedly co-activate a pattern
+    10.times { client.co_activate_units(ids: %i[see dog bark]) }
+
+    # Assembly should form
+    assemblies = client.list_assemblies
+    expect(assemblies[:count]).to be >= 1
+
+    # Pattern completion: given "see" and "dog", predict "bark"
+    completion = client.pattern_complete(partial_ids: %i[see dog])
+    expect(completion[:success]).to be true
+    expect(completion[:completion][:predicted]).to include(:bark)
+
+    # Weights should be strong
+    weight = client.query_weight(from: :see, to: :dog)
+    expect(weight[:weight]).to be > 0.3
+
+    # Find assemblies containing :dog
+    dog_asms = client.assemblies_for(unit_id: :dog)
+    expect(dog_asms[:count]).to be >= 1
+
+    # Decay
+    client.update_hebbian
+
+    # Stats
+    stats = client.hebbian_stats
+    expect(stats[:stats][:units]).to eq(3)
+  end
+end