lex-agentic-attention 0.1.0

data/spec/legion/extensions/agentic/attention/latent_inhibition/client_spec.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::LatentInhibition::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to all runner methods' do
+    %i[expose associate disinhibit novel_stimuli most_inhibited inhibition_report].each do |method|
+      expect(client).to respond_to(method)
+    end
+  end
+
+  it 'maintains state across calls on the default engine' do
+    client.expose(label: 'persistent')
+    client.expose(label: 'persistent')
+    report = client.inhibition_report
+    expect(report[:total_stimuli]).to eq(1)
+  end
+
+  it 'demonstrates the full latent inhibition cycle' do
+    # Pre-expose stimulus without consequence — builds inhibition
+    # 15 exposures => inhibition = 0.45, effectiveness = 0.55
+    15.times { client.expose(label: 'neutral_tone') }
+
+    # Now try to form an association
+    result = client.associate(label: 'neutral_tone', outcome: 'shock')
+    expect(result[:effectiveness]).to be < 0.6
+
+    # Compare with a novel stimulus
+    novel_result = client.associate(label: 'new_tone', outcome: 'shock')
+    expect(novel_result[:effectiveness]).to be > result[:effectiveness]
+  end
+
+  it 'disinhibits a pre-exposed stimulus so it can learn again' do
+    10.times { client.expose(label: 'primed') }
+    before_eff = client.associate(label: 'primed', outcome: 'test')[:effectiveness]
+
+    client.disinhibit(label: 'primed', intensity: 1.0)
+    after_eff = client.associate(label: 'primed', outcome: 'test')[:effectiveness]
+
+    expect(after_eff).to be > before_eff
+  end
+
+  it 'identifies novel stimuli correctly' do
+    client.expose(label: 'brand_new')
+    result = client.novel_stimuli
+    labels = result[:stimuli].map { |s| s[:label] }
+    expect(labels).to include('brand_new')
+  end
+end

data/spec/legion/extensions/agentic/attention/latent_inhibition/helpers/constants_spec.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::LatentInhibition::Helpers::Constants do
+  describe 'MAX_STIMULI' do
+    it 'is 500' do
+      expect(described_class::MAX_STIMULI).to eq(500)
+    end
+  end
+
+  describe 'INHIBITION_RATE' do
+    it 'is 0.03' do
+      expect(described_class::INHIBITION_RATE).to eq(0.03)
+    end
+  end
+
+  describe 'DISINHIBITION_RATE' do
+    it 'is 0.2' do
+      expect(described_class::DISINHIBITION_RATE).to eq(0.2)
+    end
+  end
+
+  describe 'NOVELTY_THRESHOLD' do
+    it 'is 3' do
+      expect(described_class::NOVELTY_THRESHOLD).to eq(3)
+    end
+  end
+
+  describe 'INHIBITION_LABELS' do
+    it 'covers the full 0.0..1.0 range' do
+      scores = [0.0, 0.1, 0.3, 0.5, 0.7, 0.9, 1.0]
+      scores.each do |score|
+        match = described_class::INHIBITION_LABELS.find { |range, _| range.cover?(score) }
+        expect(match).not_to be_nil, "no label found for score #{score}"
+      end
+    end
+
+    it 'labels 0.0 as uninhibited' do
+      label = described_class::INHIBITION_LABELS.find { |range, _| range.cover?(0.0) }&.last
+      expect(label).to eq(:uninhibited)
+    end
+
+    it 'labels 1.0 as saturated' do
+      label = described_class::INHIBITION_LABELS.find { |range, _| range.cover?(1.0) }&.last
+      expect(label).to eq(:saturated)
+    end
+  end
+
+  describe 'NOVELTY_LABELS' do
+    it 'maps true to :novel' do
+      expect(described_class::NOVELTY_LABELS[true]).to eq(:novel)
+    end
+
+    it 'maps false to :familiar' do
+      expect(described_class::NOVELTY_LABELS[false]).to eq(:familiar)
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/latent_inhibition/helpers/inhibition_engine_spec.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::LatentInhibition::Helpers::InhibitionEngine do
+  subject(:engine) { described_class.new }
+
+  describe '#expose_stimulus' do
+    it 'returns a hash with stimulus data' do
+      result = engine.expose_stimulus(label: 'bell')
+      expect(result).to be_a(Hash)
+      expect(result[:label]).to eq('bell')
+    end
+
+    it 'increments exposure_count on repeated calls' do
+      engine.expose_stimulus(label: 'bell')
+      result = engine.expose_stimulus(label: 'bell')
+      expect(result[:exposure_count]).to eq(2)
+    end
+
+    it 'raises inhibition_score over time' do
+      result1 = engine.expose_stimulus(label: 'tone')
+      result2 = engine.expose_stimulus(label: 'tone')
+      expect(result2[:inhibition_score]).to be > result1[:inhibition_score]
+    end
+
+    it 'tracks novel status correctly' do
+      result = engine.expose_stimulus(label: 'new_thing')
+      expect(result[:novel]).to be(true)
+    end
+
+    it 'marks stimulus as not novel after threshold exposures' do
+      threshold = Legion::Extensions::Agentic::Attention::LatentInhibition::Helpers::Constants::NOVELTY_THRESHOLD
+      threshold.times { engine.expose_stimulus(label: 'frequent') }
+      result = engine.expose_stimulus(label: 'frequent')
+      expect(result[:novel]).to be(false)
+    end
+
+    it 'creates distinct stimuli for different labels' do
+      engine.expose_stimulus(label: 'a')
+      engine.expose_stimulus(label: 'b')
+      report = engine.inhibition_report
+      expect(report[:total_stimuli]).to eq(2)
+    end
+  end
+
+  describe '#attempt_association' do
+    it 'returns a hash with outcome and effectiveness' do
+      result = engine.attempt_association(label: 'bell', outcome: 'food')
+      expect(result[:outcome]).to eq('food')
+      expect(result[:effectiveness]).to be_between(0.0, 1.0)
+    end
+
+    it 'returns high effectiveness for novel stimulus' do
+      result = engine.attempt_association(label: 'new', outcome: 'reward')
+      expect(result[:effectiveness]).to be_within(0.001).of(1.0)
+    end
+
+    it 'returns reduced effectiveness after many exposures' do
+      20.times { engine.expose_stimulus(label: 'old') }
+      result = engine.attempt_association(label: 'old', outcome: 'reward')
+      expect(result[:effectiveness]).to be < 0.5
+    end
+
+    it 'marks association as blocked when effectiveness is very low' do
+      50.times { engine.expose_stimulus(label: 'saturated') }
+      result = engine.attempt_association(label: 'saturated', outcome: 'something')
+      expect(result[:blocked]).to be(true)
+    end
+
+    it 'includes inhibition_score and inhibition_label' do
+      result = engine.attempt_association(label: 'bell', outcome: 'food')
+      expect(result).to have_key(:inhibition_score)
+      expect(result).to have_key(:inhibition_label)
+    end
+  end
+
+  describe '#disinhibit' do
+    it 'returns not_found status for unknown label' do
+      result = engine.disinhibit(label: 'unknown', intensity: 1.0)
+      expect(result[:status]).to eq(:not_found)
+    end
+
+    it 'reduces inhibition_score for known stimulus' do
+      10.times { engine.expose_stimulus(label: 'bell') }
+      result = engine.disinhibit(label: 'bell', intensity: 1.0)
+      expect(result[:new_score]).to be < result[:prior_score]
+    end
+
+    it 'returns prior_score and new_score' do
+      5.times { engine.expose_stimulus(label: 'tone') }
+      result = engine.disinhibit(label: 'tone', intensity: 0.5)
+      expect(result[:prior_score]).to be > 0.0
+      expect(result[:new_score]).to be < result[:prior_score]
+    end
+
+    it 'includes reduction amount' do
+      5.times { engine.expose_stimulus(label: 'cue') }
+      result = engine.disinhibit(label: 'cue', intensity: 1.0)
+      expect(result[:reduction]).to be_within(0.001).of(result[:prior_score] - result[:new_score])
+    end
+  end
+
+  describe '#novel_stimuli' do
+    it 'returns empty array when no stimuli exist' do
+      expect(engine.novel_stimuli).to be_empty
+    end
+
+    it 'returns novel stimuli' do
+      engine.expose_stimulus(label: 'fresh')
+      stimuli = engine.novel_stimuli
+      expect(stimuli.map { |s| s[:label] }).to include('fresh')
+    end
+
+    it 'excludes familiar stimuli' do
+      threshold = Legion::Extensions::Agentic::Attention::LatentInhibition::Helpers::Constants::NOVELTY_THRESHOLD
+      (threshold + 1).times { engine.expose_stimulus(label: 'old') }
+      stimuli = engine.novel_stimuli
+      expect(stimuli.map { |s| s[:label] }).not_to include('old')
+    end
+  end
+
+  describe '#most_inhibited' do
+    before do
+      5.times  { engine.expose_stimulus(label: 'low') }
+      20.times { engine.expose_stimulus(label: 'high') }
+      engine.expose_stimulus(label: 'fresh')
+    end
+
+    it 'returns stimuli ordered by inhibition_score descending' do
+      stimuli = engine.most_inhibited(limit: 3)
+      scores = stimuli.map { |s| s[:inhibition_score] }
+      expect(scores).to eq(scores.sort.reverse)
+    end
+
+    it 'respects the limit parameter' do
+      stimuli = engine.most_inhibited(limit: 2)
+      expect(stimuli.size).to be <= 2
+    end
+
+    it 'includes the most inhibited stimulus first' do
+      stimuli = engine.most_inhibited(limit: 1)
+      expect(stimuli.first[:label]).to eq('high')
+    end
+  end
+
+  describe '#inhibition_report' do
+    it 'returns empty report when no stimuli exist' do
+      report = engine.inhibition_report
+      expect(report[:total_stimuli]).to eq(0)
+      expect(report[:mean_inhibition]).to eq(0.0)
+    end
+
+    it 'counts total stimuli correctly' do
+      engine.expose_stimulus(label: 'a')
+      engine.expose_stimulus(label: 'b')
+      expect(engine.inhibition_report[:total_stimuli]).to eq(2)
+    end
+
+    it 'counts novel stimuli' do
+      engine.expose_stimulus(label: 'new')
+      report = engine.inhibition_report
+      expect(report[:novel_count]).to eq(1)
+    end
+
+    it 'computes mean_inhibition' do
+      engine.expose_stimulus(label: 'x')
+      report = engine.inhibition_report
+      expect(report[:mean_inhibition]).to be > 0.0
+    end
+
+    it 'includes max_inhibition' do
+      10.times { engine.expose_stimulus(label: 'heavy') }
+      engine.expose_stimulus(label: 'light')
+      report = engine.inhibition_report
+      expect(report[:max_inhibition]).to be > report[:mean_inhibition]
+    end
+
+    it 'includes label_breakdown hash' do
+      engine.expose_stimulus(label: 'x')
+      report = engine.inhibition_report
+      expect(report[:label_breakdown]).to be_a(Hash)
+    end
+
+    it 'counts saturated stimuli' do
+      50.times { engine.expose_stimulus(label: 'saturated') }
+      report = engine.inhibition_report
+      expect(report[:saturated_count]).to eq(1)
+    end
+  end
+
+  describe '#prune_if_needed' do
+    it 'prunes oldest stimuli when MAX_STIMULI is exceeded' do
+      max = Legion::Extensions::Agentic::Attention::LatentInhibition::Helpers::Constants::MAX_STIMULI
+      (max + 5).times { |i| engine.expose_stimulus(label: "stim_#{i}") }
+      report = engine.inhibition_report
+      expect(report[:total_stimuli]).to be <= max
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes stimuli and report keys' do
+      engine.expose_stimulus(label: 'test')
+      h = engine.to_h
+      expect(h).to have_key(:stimuli)
+      expect(h).to have_key(:report)
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/latent_inhibition/helpers/stimulus_record_spec.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::LatentInhibition::Helpers::StimulusRecord do
+  subject(:record) { described_class.new(label: 'test_stimulus') }
+
+  describe '#initialize' do
+    it 'assigns a UUID id' do
+      expect(record.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets label' do
+      expect(record.label).to eq('test_stimulus')
+    end
+
+    it 'starts with zero exposure_count' do
+      expect(record.exposure_count).to eq(0)
+    end
+
+    it 'starts with zero inhibition_score' do
+      expect(record.inhibition_score).to eq(0.0)
+    end
+
+    it 'starts with nil last_exposed_at' do
+      expect(record.last_exposed_at).to be_nil
+    end
+
+    it 'starts with empty associations' do
+      expect(record.associations).to be_empty
+    end
+  end
+
+  describe '#expose!' do
+    it 'increments exposure_count' do
+      record.expose!
+      expect(record.exposure_count).to eq(1)
+    end
+
+    it 'raises inhibition_score by INHIBITION_RATE' do
+      record.expose!
+      expect(record.inhibition_score).to be_within(0.0001).of(
+        Legion::Extensions::Agentic::Attention::LatentInhibition::Helpers::Constants::INHIBITION_RATE
+      )
+    end
+
+    it 'sets last_exposed_at' do
+      record.expose!
+      expect(record.last_exposed_at).to be_a(Time)
+    end
+
+    it 'returns self for chaining' do
+      expect(record.expose!).to eq(record)
+    end
+
+    it 'clamps inhibition_score at 1.0 after many exposures' do
+      50.times { record.expose! }
+      expect(record.inhibition_score).to be <= 1.0
+    end
+
+    it 'accumulates inhibition with multiple exposures' do
+      3.times { record.expose! }
+      expected = (Legion::Extensions::Agentic::Attention::LatentInhibition::Helpers::Constants::INHIBITION_RATE * 3).round(10)
+      expect(record.inhibition_score).to be_within(0.0001).of(expected)
+    end
+  end
+
+  describe '#associate!' do
+    it 'returns effectiveness of 1.0 for uninhibited stimulus' do
+      effectiveness = record.associate!(outcome: 'reward')
+      expect(effectiveness).to be_within(0.001).of(1.0)
+    end
+
+    it 'returns reduced effectiveness for inhibited stimulus' do
+      20.times { record.expose! }
+      effectiveness = record.associate!(outcome: 'reward')
+      expect(effectiveness).to be < 1.0
+    end
+
+    it 'appends to associations array' do
+      record.associate!(outcome: 'reward')
+      expect(record.associations.size).to eq(1)
+      expect(record.associations.first[:outcome]).to eq('reward')
+    end
+
+    it 'stores effectiveness in association record' do
+      eff = record.associate!(outcome: 'pain')
+      expect(record.associations.last[:effectiveness]).to eq(eff)
+    end
+
+    it 'stores recorded_at timestamp' do
+      record.associate!(outcome: 'neutral')
+      expect(record.associations.last[:recorded_at]).to be_a(Time)
+    end
+
+    it 'rounds effectiveness to 10 decimal places' do
+      20.times { record.expose! }
+      eff = record.associate!(outcome: 'test')
+      expect(eff.to_s.split('.').last.length).to be <= 10
+    end
+  end
+
+  describe '#disinhibit!' do
+    before { 10.times { record.expose! } }
+
+    it 'reduces inhibition_score' do
+      prior = record.inhibition_score
+      record.disinhibit!(intensity: 1.0)
+      expect(record.inhibition_score).to be < prior
+    end
+
+    it 'clamps score at 0.0 when reduction exceeds current score' do
+      # 3 exposures => score = 0.09, which is less than DISINHIBITION_RATE (0.2)
+      fresh = Legion::Extensions::Agentic::Attention::LatentInhibition::Helpers::StimulusRecord.new(label: 'tiny')
+      3.times { fresh.expose! }
+      fresh.disinhibit!(intensity: 1.0)
+      expect(fresh.inhibition_score).to eq(0.0)
+    end
+
+    it 'returns self for chaining' do
+      expect(record.disinhibit!(intensity: 0.5)).to eq(record)
+    end
+
+    it 'applies partial disinhibition proportionally to intensity' do
+      prior = record.inhibition_score
+      record.disinhibit!(intensity: 0.5)
+      expected_reduction = (Legion::Extensions::Agentic::Attention::LatentInhibition::Helpers::Constants::DISINHIBITION_RATE * 0.5).round(10)
+      expect(prior - record.inhibition_score).to be_within(0.0001).of(expected_reduction)
+    end
+
+    it 'clamps intensity to [0.0, 1.0] before applying' do
+      prior = record.inhibition_score
+      record.disinhibit!(intensity: 5.0)
+      max_reduction = Legion::Extensions::Agentic::Attention::LatentInhibition::Helpers::Constants::DISINHIBITION_RATE
+      expect(prior - record.inhibition_score).to be_within(0.0001).of(max_reduction)
+    end
+  end
+
+  describe '#novel?' do
+    it 'returns true when exposure_count < NOVELTY_THRESHOLD' do
+      expect(record.novel?).to be(true)
+    end
+
+    it 'returns false after NOVELTY_THRESHOLD or more exposures' do
+      Legion::Extensions::Agentic::Attention::LatentInhibition::Helpers::Constants::NOVELTY_THRESHOLD.times { record.expose! }
+      expect(record.novel?).to be(false)
+    end
+  end
+
+  describe '#inhibition_label' do
+    it 'returns :uninhibited for a new record' do
+      expect(record.inhibition_label).to eq(:uninhibited)
+    end
+
+    it 'returns :saturated after many exposures' do
+      50.times { record.expose! }
+      expect(record.inhibition_label).to eq(:saturated)
+    end
+  end
+
+  describe '#to_h' do
+    before { record.expose! }
+
+    it 'includes all expected keys' do
+      h = record.to_h
+      %i[id label exposure_count inhibition_score inhibition_label novel last_exposed_at associations].each do |key|
+        expect(h).to have_key(key)
+      end
+    end
+
+    it 'reflects current state' do
+      h = record.to_h
+      expect(h[:exposure_count]).to eq(1)
+      expect(h[:label]).to eq('test_stimulus')
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/latent_inhibition/runners/latent_inhibition_spec.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::LatentInhibition::Runners::LatentInhibition do
+  let(:engine) { Legion::Extensions::Agentic::Attention::LatentInhibition::Helpers::InhibitionEngine.new }
+  let(:client) { Legion::Extensions::Agentic::Attention::LatentInhibition::Client.new }
+
+  describe '#expose' do
+    it 'returns a hash with exposure data' do
+      result = client.expose(label: 'bell', engine: engine)
+      expect(result).to be_a(Hash)
+      expect(result[:label]).to eq('bell')
+      expect(result[:exposure_count]).to eq(1)
+    end
+
+    it 'increments exposure on repeated calls' do
+      client.expose(label: 'bell', engine: engine)
+      result = client.expose(label: 'bell', engine: engine)
+      expect(result[:exposure_count]).to eq(2)
+    end
+
+    it 'includes inhibition_score' do
+      result = client.expose(label: 'tone', engine: engine)
+      expect(result).to have_key(:inhibition_score)
+    end
+
+    it 'includes novel status' do
+      result = client.expose(label: 'new', engine: engine)
+      expect(result[:novel]).to be(true)
+    end
+
+    it 'uses default engine when none provided' do
+      result = client.expose(label: 'default_test')
+      expect(result[:label]).to eq('default_test')
+    end
+  end
+
+  describe '#associate' do
+    it 'returns a hash with effectiveness' do
+      result = client.associate(label: 'bell', outcome: 'food', engine: engine)
+      expect(result[:effectiveness]).to be_between(0.0, 1.0)
+    end
+
+    it 'returns full effectiveness for fresh stimulus' do
+      result = client.associate(label: 'fresh', outcome: 'reward', engine: engine)
+      expect(result[:effectiveness]).to be_within(0.001).of(1.0)
+    end
+
+    it 'returns reduced effectiveness after pre-exposure' do
+      20.times { engine.expose_stimulus(label: 'pre_exposed') }
+      result = client.associate(label: 'pre_exposed', outcome: 'reward', engine: engine)
+      expect(result[:effectiveness]).to be < 0.5
+    end
+
+    it 'includes blocked flag' do
+      result = client.associate(label: 'fresh', outcome: 'test', engine: engine)
+      expect(result).to have_key(:blocked)
+    end
+
+    it 'marks association as blocked after saturation' do
+      50.times { engine.expose_stimulus(label: 'saturated') }
+      result = client.associate(label: 'saturated', outcome: 'anything', engine: engine)
+      expect(result[:blocked]).to be(true)
+    end
+  end
+
+  describe '#disinhibit' do
+    it 'returns not_found for unknown stimulus' do
+      result = client.disinhibit(label: 'unknown', engine: engine)
+      expect(result[:status]).to eq(:not_found)
+    end
+
+    it 'reduces inhibition after significant event' do
+      10.times { engine.expose_stimulus(label: 'conditioned') }
+      result = client.disinhibit(label: 'conditioned', intensity: 1.0, engine: engine)
+      expect(result[:new_score]).to be < result[:prior_score]
+    end
+
+    it 'defaults intensity to 1.0' do
+      5.times { engine.expose_stimulus(label: 'cue') }
+      result = client.disinhibit(label: 'cue', engine: engine)
+      expect(result[:reduction]).to be > 0.0
+    end
+  end
+
+  describe '#novel_stimuli' do
+    it 'returns hash with stimuli and count' do
+      result = client.novel_stimuli(engine: engine)
+      expect(result).to have_key(:stimuli)
+      expect(result).to have_key(:count)
+    end
+
+    it 'returns novel stimuli list' do
+      engine.expose_stimulus(label: 'new_thing')
+      result = client.novel_stimuli(engine: engine)
+      expect(result[:count]).to eq(1)
+    end
+
+    it 'count matches stimuli array size' do
+      engine.expose_stimulus(label: 'a')
+      engine.expose_stimulus(label: 'b')
+      result = client.novel_stimuli(engine: engine)
+      expect(result[:count]).to eq(result[:stimuli].size)
+    end
+  end
+
+  describe '#most_inhibited' do
+    before do
+      5.times  { engine.expose_stimulus(label: 'mid') }
+      20.times { engine.expose_stimulus(label: 'top') }
+    end
+
+    it 'returns hash with stimuli and count' do
+      result = client.most_inhibited(engine: engine)
+      expect(result).to have_key(:stimuli)
+      expect(result).to have_key(:count)
+    end
+
+    it 'respects limit parameter' do
+      result = client.most_inhibited(limit: 1, engine: engine)
+      expect(result[:stimuli].size).to eq(1)
+    end
+
+    it 'returns most inhibited first' do
+      result = client.most_inhibited(limit: 2, engine: engine)
+      expect(result[:stimuli].first[:label]).to eq('top')
+    end
+  end
+
+  describe '#inhibition_report' do
+    it 'returns a report hash' do
+      result = client.inhibition_report(engine: engine)
+      expect(result[:total_stimuli]).to eq(0)
+    end
+
+    it 'reflects current engine state' do
+      engine.expose_stimulus(label: 'tracked')
+      result = client.inhibition_report(engine: engine)
+      expect(result[:total_stimuli]).to eq(1)
+    end
+
+    it 'includes all required report fields' do
+      result = client.inhibition_report(engine: engine)
+      %i[total_stimuli novel_count inhibited_count saturated_count mean_inhibition max_inhibition label_breakdown].each do |key|
+        expect(result).to have_key(key)
+      end
+    end
+  end
+end