lex-agentic-attention 0.1.0

data/spec/legion/extensions/agentic/attention/subliminal/helpers/subliminal_trace_spec.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Subliminal::Helpers::SubliminalTrace do
+  subject(:trace) { described_class.new(content: 'faint memory of danger') }
+
+  describe '#initialize' do
+    it 'assigns a UUID id' do
+      expect(trace.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores content' do
+      expect(trace.content).to eq('faint memory of danger')
+    end
+
+    it 'defaults trace_type to :associative' do
+      expect(trace.trace_type).to eq(:associative)
+    end
+
+    it 'defaults domain to :general' do
+      expect(trace.domain).to eq(:general)
+    end
+
+    it 'defaults activation to DEFAULT_ACTIVATION' do
+      expect(trace.activation).to eq(0.2)
+    end
+
+    it 'clamps activation to subliminal ceiling' do
+      high = described_class.new(content: 'x', activation: 0.9)
+      expect(high.activation).to eq(0.39)
+    end
+
+    it 'clamps activation to subliminal floor' do
+      low = described_class.new(content: 'x', activation: 0.001)
+      expect(low.activation).to eq(0.02)
+    end
+
+    it 'defaults influence_target to :attention' do
+      expect(trace.influence_target).to eq(:attention)
+    end
+
+    it 'validates trace_type' do
+      bad = described_class.new(content: 'x', trace_type: :nonexistent)
+      expect(bad.trace_type).to eq(:associative)
+    end
+
+    it 'validates influence_target' do
+      bad = described_class.new(content: 'x', influence_target: :nonexistent)
+      expect(bad.influence_target).to eq(:attention)
+    end
+  end
+
+  describe '#boost!' do
+    it 'increases activation' do
+      original = trace.activation
+      trace.boost!
+      expect(trace.activation).to be > original
+    end
+
+    it 'clamps at subliminal ceiling' do
+      10.times { trace.boost! }
+      expect(trace.activation).to eq(0.39)
+    end
+  end
+
+  describe '#decay!' do
+    it 'decreases activation' do
+      original = trace.activation
+      trace.decay!
+      expect(trace.activation).to be < original
+    end
+
+    it 'clamps at 0.0' do
+      50.times { trace.decay! }
+      expect(trace.activation).to eq(0.0)
+    end
+  end
+
+  describe '#exert_influence!' do
+    it 'returns influence magnitude' do
+      mag = trace.exert_influence!
+      expect(mag).to be > 0.0
+    end
+
+    it 'increments influence_count' do
+      trace.exert_influence!
+      expect(trace.influence_count).to eq(1)
+    end
+
+    it 'slightly decreases activation' do
+      original = trace.activation
+      trace.exert_influence!
+      expect(trace.activation).to be < original
+    end
+  end
+
+  describe '#near_threshold?' do
+    it 'is false at default activation' do
+      expect(trace.near_threshold?).to be false
+    end
+
+    it 'is true when near conscious threshold' do
+      near = described_class.new(content: 'x', activation: 0.35)
+      expect(near.near_threshold?).to be true
+    end
+  end
+
+  describe '#active?' do
+    it 'is true at default activation' do
+      expect(trace.active?).to be true
+    end
+
+    it 'is false when fully decayed' do
+      50.times { trace.decay! }
+      expect(trace.active?).to be false
+    end
+  end
+
+  describe '#extinct?' do
+    it 'is false at default activation' do
+      expect(trace.extinct?).to be false
+    end
+
+    it 'is true when nearly zero' do
+      50.times { trace.decay! }
+      expect(trace.extinct?).to be true
+    end
+  end
+
+  describe '#potent?' do
+    it 'is true at default activation' do
+      expect(trace.potent?).to be true
+    end
+
+    it 'is false when low' do
+      faint = described_class.new(content: 'x', activation: 0.1)
+      expect(faint.potent?).to be false
+    end
+  end
+
+  describe '#breached_threshold?' do
+    it 'is false by default' do
+      expect(trace.breached_threshold?).to be false
+    end
+  end
+
+  describe '#persistence' do
+    it 'is 1.0 initially' do
+      expect(trace.persistence).to eq(1.0)
+    end
+
+    it 'decreases after decay' do
+      trace.decay!
+      expect(trace.persistence).to be < 1.0
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all fields' do
+      hash = trace.to_h
+      expect(hash).to include(
+        :id, :content, :trace_type, :domain, :activation,
+        :original_activation, :influence_target, :influence_count,
+        :influence_magnitude, :near_threshold, :active, :extinct,
+        :activation_label, :persistence, :created_at
+      )
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/subliminal/runners_spec.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Subliminal::Runners::Subliminal do
+  let(:engine) { Legion::Extensions::Agentic::Attention::Subliminal::Helpers::SubliminalEngine.new }
+  let(:runner) do
+    obj = Object.new
+    obj.extend(described_class)
+    obj.instance_variable_set(:@default_engine, engine)
+    obj
+  end
+
+  describe '#create_subliminal_trace' do
+    it 'returns success with trace hash' do
+      result = runner.create_subliminal_trace(content: 'test', engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:trace][:content]).to eq('test')
+    end
+  end
+
+  describe '#boost_trace' do
+    it 'returns success for known trace' do
+      trace = engine.create_trace(content: 'test')
+      result = runner.boost_trace(trace_id: trace.id, engine: engine)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns failure for unknown trace' do
+      result = runner.boost_trace(trace_id: 'bad', engine: engine)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#process_influences' do
+    it 'returns success' do
+      result = runner.process_influences(engine: engine)
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#decay_all' do
+    it 'returns success' do
+      result = runner.decay_all(engine: engine)
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#active_traces' do
+    it 'returns active list' do
+      engine.create_trace(content: 'test')
+      result = runner.active_traces(engine: engine)
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#near_threshold' do
+    it 'returns near-threshold list' do
+      engine.create_trace(content: 'near', activation: 0.35)
+      result = runner.near_threshold(engine: engine)
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#influence_on' do
+    it 'returns influence level' do
+      result = runner.influence_on(target: :attention, engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:influence]).to eq(0.0)
+    end
+  end
+
+  describe '#subliminal_status' do
+    it 'returns comprehensive status' do
+      result = runner.subliminal_status(engine: engine)
+      expect(result[:success]).to be true
+      expect(result).to include(:total_traces, :subliminal_load)
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/subliminal/subliminal_spec.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Subliminal do
+  it 'has a version number' do
+    expect(Legion::Extensions::Agentic::Attention::Subliminal::VERSION).to eq('0.1.0')
+  end
+end

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

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Surprise::Client do
+  subject(:client) { described_class.new }
+
+  describe '#initialize' do
+    it 'creates a default store' do
+      expect(client.store).to be_a(Legion::Extensions::Agentic::Attention::Surprise::Helpers::SurpriseStore)
+    end
+
+    it 'creates a default habituation_model' do
+      expect(client.habituation_model).to be_a(Legion::Extensions::Agentic::Attention::Surprise::Helpers::HabituationModel)
+    end
+
+    it 'accepts an injected store' do
+      custom = Legion::Extensions::Agentic::Attention::Surprise::Helpers::SurpriseStore.new
+      c = described_class.new(store: custom)
+      expect(c.store).to equal(custom)
+    end
+
+    it 'accepts an injected habituation_model' do
+      custom = Legion::Extensions::Agentic::Attention::Surprise::Helpers::HabituationModel.new
+      c = described_class.new(habituation_model: custom)
+      expect(c.habituation_model).to equal(custom)
+    end
+  end
+
+  describe 'full orienting response workflow' do
+    it 'detects surprise, habituates, and recovers sensitivity' do
+      # Phase 1: Fresh domain — max sensitivity
+      sens_before = client.domain_sensitivity(domain: :cpu_load)[:sensitivity]
+      expect(sens_before).to eq(1.0)
+
+      # Phase 2: Large unexpected event fires orienting response
+      first = client.evaluate_surprise(domain: :cpu_load, predicted: 0.2, actual: 0.95, valence: :negative)
+      expect(first[:success]).to be true
+      expect(first[:orienting_triggered]).to be true
+
+      # Phase 3: Sensitivity reduced (habituation)
+      sens_after = client.domain_sensitivity(domain: :cpu_load)[:sensitivity]
+      expect(sens_after).to be < sens_before
+
+      # Phase 4: Repeated surprises continue to habituate
+      5.times { client.evaluate_surprise(domain: :cpu_load, predicted: 0.2, actual: 0.95, valence: :negative) }
+      sens_habituated = client.domain_sensitivity(domain: :cpu_load)[:sensitivity]
+      expect(sens_habituated).to be < sens_after
+
+      # Phase 5: Tick decay slightly recovers sensitivity
+      client.update_surprise(tick_result: {})
+      sens_recovered = client.domain_sensitivity(domain: :cpu_load)[:sensitivity]
+      expect(sens_recovered).to be >= sens_habituated
+
+      # Phase 6: Stats reflect accumulated history (1 initial + 5 repeated = 6 events)
+      stats = client.surprise_stats
+      expect(stats[:total_events]).to be >= 6
+      expect(stats[:domain_count]).to be >= 1
+
+      # Phase 7: Manual reset restores full sensitivity
+      client.reset_habituation(domain: :cpu_load)
+      sens_reset = client.domain_sensitivity(domain: :cpu_load)[:sensitivity]
+      expect(sens_reset).to be > sens_habituated
+    end
+
+    it 'tracks multiple domains independently' do
+      client.evaluate_surprise(domain: :memory,   predicted: 0.0, actual: 1.0, valence: :negative)
+      client.evaluate_surprise(domain: :disk_io,  predicted: 0.0, actual: 1.0, valence: :negative)
+      client.evaluate_surprise(domain: :network,  predicted: 0.3, actual: 0.4, valence: :neutral)
+
+      stats = client.surprise_stats
+      expect(stats[:domain_count]).to eq(3)
+
+      # Memory and disk_io were strongly surprising; network was not
+      mem_sens  = client.domain_sensitivity(domain: :memory)[:sensitivity]
+      net_sens  = client.domain_sensitivity(domain: :network)[:sensitivity]
+      expect(mem_sens).to be < 1.0
+      expect(net_sens).to be < 1.0
+    end
+
+    it 'processes tick predictions end-to-end' do
+      tick = {
+        predictions: [
+          { domain: :error_rate, predicted: 0.01, actual: 0.45, valence: :negative },
+          { domain: :latency,    predicted: 0.1,  actual: 0.15, valence: :neutral  }
+        ]
+      }
+      result = client.update_surprise(tick_result: tick)
+      expect(result[:success]).to be true
+      expect(result[:evaluated]).to eq(2)
+
+      # Events should appear in recent surprises
+      recent = client.recent_surprises(count: 5)
+      domains = recent[:events].map { |e| e[:domain] }
+      expect(domains).to include(:error_rate, :latency)
+    end
+
+    it 'positive surprise is less alarming than negative surprise for the same delta' do
+      client.evaluate_surprise(domain: :pos_outcome, predicted: 0.5, actual: 1.0, valence: :positive)
+      client.evaluate_surprise(domain: :neg_outcome, predicted: 0.5, actual: 0.0, valence: :negative)
+
+      pos_event = client.recent_surprises(count: 2)[:events].find { |e| e[:domain] == :pos_outcome }
+      neg_event = client.recent_surprises(count: 2)[:events].find { |e| e[:domain] == :neg_outcome }
+
+      expect(neg_event[:magnitude]).to be > pos_event[:magnitude]
+    end
+
+    it 'cooldown prevents orienting spam from the same domain' do
+      domain = :noisy_sensor
+      results = 5.times.map { client.evaluate_surprise(domain: domain, predicted: 0.0, actual: 1.0, valence: :negative) }
+      orienting_count = results.count { |r| r[:orienting_triggered] }
+      # Only the first should fire (cooldown blocks subsequent)
+      expect(orienting_count).to eq(1)
+    end
+
+    it 'reports most surprising domain in stats' do
+      client.evaluate_surprise(domain: :low,  predicted: 0.4, actual: 0.5, valence: :neutral)
+      client.evaluate_surprise(domain: :high, predicted: 0.0, actual: 1.0, valence: :negative)
+      expect(client.surprise_stats[:most_surprising_domain]).to eq(:high)
+    end
+  end
+end

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

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Surprise::Helpers::Constants do
+  describe 'SURPRISE_THRESHOLD' do
+    it 'is a float between 0 and 1' do
+      expect(described_class::SURPRISE_THRESHOLD).to be_a(Float)
+      expect(described_class::SURPRISE_THRESHOLD).to be_between(0.0, 1.0).exclusive
+    end
+
+    it 'is 0.4' do
+      expect(described_class::SURPRISE_THRESHOLD).to eq(0.4)
+    end
+  end
+
+  describe 'HABITUATION_RATE' do
+    it 'is a positive float less than 1' do
+      expect(described_class::HABITUATION_RATE).to be_a(Float)
+      expect(described_class::HABITUATION_RATE).to be_between(0.0, 1.0).exclusive
+    end
+  end
+
+  describe 'SENSITIZATION_RATE' do
+    it 'is a positive float less than HABITUATION_RATE' do
+      expect(described_class::SENSITIZATION_RATE).to be < described_class::HABITUATION_RATE
+    end
+  end
+
+  describe 'SURPRISE_DECAY' do
+    it 'is a positive float between 0 and 1' do
+      expect(described_class::SURPRISE_DECAY).to be_a(Float)
+      expect(described_class::SURPRISE_DECAY).to be_between(0.0, 1.0).exclusive
+    end
+  end
+
+  describe 'MAX_SURPRISE_HISTORY' do
+    it 'is a positive integer' do
+      expect(described_class::MAX_SURPRISE_HISTORY).to be_a(Integer)
+      expect(described_class::MAX_SURPRISE_HISTORY).to be > 0
+    end
+
+    it 'is 200' do
+      expect(described_class::MAX_SURPRISE_HISTORY).to eq(200)
+    end
+  end
+
+  describe 'SURPRISE_ALPHA' do
+    it 'is an EMA alpha between 0 and 1' do
+      expect(described_class::SURPRISE_ALPHA).to be_a(Float)
+      expect(described_class::SURPRISE_ALPHA).to be_between(0.0, 1.0).exclusive
+    end
+  end
+
+  describe 'VALENCE_WEIGHTS' do
+    it 'contains positive, negative, and neutral keys' do
+      expect(described_class::VALENCE_WEIGHTS.keys).to contain_exactly(:positive, :negative, :neutral)
+    end
+
+    it 'weights negative surprise higher than positive' do
+      expect(described_class::VALENCE_WEIGHTS[:negative]).to be > described_class::VALENCE_WEIGHTS[:positive]
+    end
+
+    it 'weights negative surprise highest' do
+      expect(described_class::VALENCE_WEIGHTS[:negative]).to eq(described_class::VALENCE_WEIGHTS.values.max)
+    end
+
+    it 'is frozen' do
+      expect(described_class::VALENCE_WEIGHTS).to be_frozen
+    end
+
+    it 'has all positive float values' do
+      described_class::VALENCE_WEIGHTS.each_value do |v|
+        expect(v).to be_a(Float)
+        expect(v).to be > 0.0
+      end
+    end
+  end
+
+  describe 'DOMAIN_HABITUATION_FLOOR' do
+    it 'is a positive float less than 1' do
+      expect(described_class::DOMAIN_HABITUATION_FLOOR).to be_a(Float)
+      expect(described_class::DOMAIN_HABITUATION_FLOOR).to be_between(0.0, 1.0).exclusive
+    end
+
+    it 'is less than SURPRISE_THRESHOLD' do
+      expect(described_class::DOMAIN_HABITUATION_FLOOR).to be < described_class::SURPRISE_THRESHOLD
+    end
+  end
+
+  describe 'MAX_DOMAINS' do
+    it 'is a positive integer' do
+      expect(described_class::MAX_DOMAINS).to be_a(Integer)
+      expect(described_class::MAX_DOMAINS).to be > 0
+    end
+
+    it 'is 50' do
+      expect(described_class::MAX_DOMAINS).to eq(50)
+    end
+  end
+
+  describe 'ORIENTING_COOLDOWN' do
+    it 'is a positive integer' do
+      expect(described_class::ORIENTING_COOLDOWN).to be_a(Integer)
+      expect(described_class::ORIENTING_COOLDOWN).to be > 0
+    end
+
+    it 'is 3' do
+      expect(described_class::ORIENTING_COOLDOWN).to eq(3)
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/surprise/helpers/habituation_model_spec.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Surprise::Helpers::HabituationModel do
+  subject(:model) { described_class.new }
+
+  let(:floor) { Legion::Extensions::Agentic::Attention::Surprise::Helpers::Constants::DOMAIN_HABITUATION_FLOOR }
+  let(:habituation_rate) { Legion::Extensions::Agentic::Attention::Surprise::Helpers::Constants::HABITUATION_RATE }
+  let(:sensitization_rate) { Legion::Extensions::Agentic::Attention::Surprise::Helpers::Constants::SENSITIZATION_RATE }
+
+  describe '#sensitivity_for' do
+    it 'returns 1.0 for unknown domains (fully sensitive)' do
+      expect(model.sensitivity_for(:new_domain)).to eq(1.0)
+    end
+
+    it 'returns the stored sensitivity for a known domain' do
+      model.habituate(:known)
+      expect(model.sensitivity_for(:known)).to be < 1.0
+    end
+  end
+
+  describe '#habituate' do
+    it 'reduces sensitivity by HABITUATION_RATE' do
+      initial = model.sensitivity_for(:domain_a)
+      model.habituate(:domain_a)
+      expect(model.sensitivity_for(:domain_a)).to be_within(0.0001).of(initial - habituation_rate)
+    end
+
+    it 'never goes below DOMAIN_HABITUATION_FLOOR' do
+      100.times { model.habituate(:floor_domain) }
+      expect(model.sensitivity_for(:floor_domain)).to be >= floor
+    end
+
+    it 'returns the updated sensitivity' do
+      result = model.habituate(:returning_domain)
+      expect(result).to eq(model.sensitivity_for(:returning_domain))
+    end
+
+    it 'habituates different domains independently' do
+      model.habituate(:domain_x)
+      expect(model.sensitivity_for(:domain_y)).to eq(1.0)
+    end
+  end
+
+  describe '#sensitize' do
+    it 'increases sensitivity toward 1.0' do
+      model.habituate(:sens_domain)
+      before = model.sensitivity_for(:sens_domain)
+      model.sensitize(:sens_domain)
+      expect(model.sensitivity_for(:sens_domain)).to be > before
+    end
+
+    it 'never exceeds 1.0' do
+      100.times { model.sensitize(:fresh_domain) }
+      expect(model.sensitivity_for(:fresh_domain)).to be <= 1.0
+    end
+
+    it 'returns the updated sensitivity' do
+      model.habituate(:ret_domain)
+      result = model.sensitize(:ret_domain)
+      expect(result).to eq(model.sensitivity_for(:ret_domain))
+    end
+
+    it 'increases by SENSITIZATION_RATE when below 1.0' do
+      model.habituate(:rate_domain)
+      before = model.sensitivity_for(:rate_domain)
+      model.sensitize(:rate_domain)
+      expect(model.sensitivity_for(:rate_domain)).to be_within(0.0001).of(before + sensitization_rate)
+    end
+  end
+
+  describe '#decay_all' do
+    it 'slightly recovers sensitivity across all domains' do
+      model.habituate(:d1)
+      model.habituate(:d2)
+      before_d1 = model.sensitivity_for(:d1)
+      before_d2 = model.sensitivity_for(:d2)
+      model.decay_all
+      expect(model.sensitivity_for(:d1)).to be > before_d1
+      expect(model.sensitivity_for(:d2)).to be > before_d2
+    end
+
+    it 'does not push sensitivity above 1.0' do
+      model.decay_all
+      expect(model.sensitivity_for(:d1)).to be <= 1.0
+    end
+
+    it 'has no effect when no domains are tracked' do
+      expect { model.decay_all }.not_to raise_error
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with domains and sensitivities keys' do
+      model.habituate(:d1)
+      h = model.to_h
+      expect(h).to include(:domains, :sensitivities)
+    end
+
+    it 'reports correct domain count' do
+      model.habituate(:alpha)
+      model.habituate(:beta)
+      expect(model.to_h[:domains]).to eq(2)
+    end
+
+    it 'rounds sensitivity values to 4 decimal places' do
+      model.habituate(:precision_domain)
+      h = model.to_h
+      h[:sensitivities].each_value do |v|
+        expect(v.to_s.length).to be <= 7
+      end
+    end
+
+    it 'returns 0 domains when nothing tracked' do
+      expect(model.to_h[:domains]).to eq(0)
+    end
+  end
+
+  describe 'domain limit enforcement' do
+    it 'does not exceed MAX_DOMAINS tracked domains' do
+      max = Legion::Extensions::Agentic::Attention::Surprise::Helpers::Constants::MAX_DOMAINS
+      (max + 10).times { |i| model.habituate(:"domain_#{i}") }
+      expect(model.to_h[:domains]).to be <= max
+    end
+  end
+end