lex-agentic-attention 0.1.0

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

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Surprise::Helpers::SurpriseEvent do
+  let(:event) do
+    described_class.new(
+      domain:    :sensor,
+      predicted: 0.5,
+      actual:    0.9,
+      magnitude: 0.6,
+      valence:   :negative
+    )
+  end
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(event.id).to be_a(String)
+      expect(event.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'assigns domain' do
+      expect(event.domain).to eq(:sensor)
+    end
+
+    it 'assigns predicted value' do
+      expect(event.predicted).to eq(0.5)
+    end
+
+    it 'assigns actual value' do
+      expect(event.actual).to eq(0.9)
+    end
+
+    it 'clamps magnitude to [0.0, 1.0]' do
+      expect(event.magnitude).to be_between(0.0, 1.0)
+    end
+
+    it 'assigns valence' do
+      expect(event.valence).to eq(:negative)
+    end
+
+    it 'defaults orienting to false' do
+      expect(event.orienting).to be false
+    end
+
+    it 'sets timestamp to current UTC time' do
+      expect(event.timestamp).to be_a(Time)
+    end
+
+    it 'clamps magnitude above 1.0 down to 1.0' do
+      e = described_class.new(domain: :x, predicted: 0.0, actual: 0.0, magnitude: 5.0, valence: :neutral)
+      expect(e.magnitude).to eq(1.0)
+    end
+
+    it 'clamps magnitude below 0.0 up to 0.0' do
+      e = described_class.new(domain: :x, predicted: 0.0, actual: 0.0, magnitude: -1.0, valence: :neutral)
+      expect(e.magnitude).to eq(0.0)
+    end
+
+    it 'accepts orienting: true' do
+      e = described_class.new(domain: :x, predicted: 0.1, actual: 0.9, magnitude: 0.8, valence: :negative, orienting: true)
+      expect(e.orienting).to be true
+    end
+  end
+
+  describe '#to_h' do
+    subject(:hash) { event.to_h }
+
+    it 'includes all required keys' do
+      expect(hash.keys).to contain_exactly(:id, :domain, :predicted, :actual, :magnitude, :valence, :orienting, :timestamp)
+    end
+
+    it 'rounds magnitude to 4 decimal places' do
+      e = described_class.new(domain: :d, predicted: 0.1, actual: 0.2, magnitude: 0.123456789, valence: :neutral)
+      expect(e.to_h[:magnitude]).to eq(0.1235)
+    end
+
+    it 'preserves domain as-is' do
+      expect(hash[:domain]).to eq(:sensor)
+    end
+
+    it 'preserves valence as symbol' do
+      expect(hash[:valence]).to eq(:negative)
+    end
+
+    it 'returns false for orienting when not set' do
+      expect(hash[:orienting]).to be false
+    end
+
+    it 'each call produces the same id' do
+      expect(event.to_h[:id]).to eq(event.to_h[:id])
+    end
+  end
+
+  describe 'unique ids' do
+    it 'generates unique ids for different events' do
+      e1 = described_class.new(domain: :d, predicted: 0.0, actual: 1.0, magnitude: 1.0, valence: :negative)
+      e2 = described_class.new(domain: :d, predicted: 0.0, actual: 1.0, magnitude: 1.0, valence: :negative)
+      expect(e1.id).not_to eq(e2.id)
+    end
+  end
+end

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

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Surprise::Helpers::SurpriseStore do
+  subject(:store) { described_class.new }
+
+  def make_event(domain: :test, magnitude: 0.5, valence: :neutral, orienting: false)
+    Legion::Extensions::Agentic::Attention::Surprise::Helpers::SurpriseEvent.new(
+      domain:    domain,
+      predicted: 0.5,
+      actual:    0.8,
+      magnitude: magnitude,
+      valence:   valence,
+      orienting: orienting
+    )
+  end
+
+  describe '#record' do
+    it 'adds the event to the store' do
+      event = make_event
+      store.record(event)
+      expect(store.events.size).to eq(1)
+    end
+
+    it 'returns the recorded event' do
+      event = make_event
+      result = store.record(event)
+      expect(result).to equal(event)
+    end
+
+    it 'updates the EMA baseline for the domain' do
+      event = make_event(domain: :ema_domain, magnitude: 0.8)
+      expect { store.record(event) }.to change { store.baseline_for(:ema_domain) }.from(0.0)
+    end
+  end
+
+  describe '#recent' do
+    it 'returns the last N events' do
+      5.times { |i| store.record(make_event(domain: :"d#{i}")) }
+      expect(store.recent(3).size).to eq(3)
+    end
+
+    it 'returns all events when N exceeds store size' do
+      2.times { store.record(make_event) }
+      expect(store.recent(10).size).to eq(2)
+    end
+
+    it 'defaults to 10 most recent' do
+      15.times { store.record(make_event) }
+      expect(store.recent.size).to eq(10)
+    end
+
+    it 'returns events in insertion order (oldest first in the slice)' do
+      e1 = make_event(domain: :first)
+      e2 = make_event(domain: :second)
+      store.record(e1)
+      store.record(e2)
+      recent = store.recent(2)
+      expect(recent.first.domain).to eq(:first)
+      expect(recent.last.domain).to eq(:second)
+    end
+  end
+
+  describe '#by_domain' do
+    it 'returns only events matching the domain' do
+      store.record(make_event(domain: :alpha))
+      store.record(make_event(domain: :beta))
+      store.record(make_event(domain: :alpha))
+      expect(store.by_domain(:alpha).size).to eq(2)
+    end
+
+    it 'returns empty array for unknown domain' do
+      expect(store.by_domain(:unknown)).to eq([])
+    end
+  end
+
+  describe '#most_surprising' do
+    it 'returns events sorted by magnitude descending' do
+      store.record(make_event(magnitude: 0.3))
+      store.record(make_event(magnitude: 0.9))
+      store.record(make_event(magnitude: 0.5))
+      top = store.most_surprising(2)
+      expect(top.map(&:magnitude)).to eq([0.9, 0.5])
+    end
+
+    it 'returns at most N events' do
+      3.times { store.record(make_event) }
+      expect(store.most_surprising(2).size).to eq(2)
+    end
+
+    it 'returns all when N exceeds store size' do
+      2.times { store.record(make_event) }
+      expect(store.most_surprising(10).size).to eq(2)
+    end
+  end
+
+  describe '#baseline_for' do
+    it 'returns 0.0 for unknown domains' do
+      expect(store.baseline_for(:never_seen)).to eq(0.0)
+    end
+
+    it 'converges toward recent magnitudes via EMA' do
+      5.times { store.record(make_event(domain: :conv, magnitude: 0.8)) }
+      baseline = store.baseline_for(:conv)
+      expect(baseline).to be > 0.0
+      expect(baseline).to be <= 0.8
+    end
+
+    it 'updates separately per domain' do
+      store.record(make_event(domain: :d1, magnitude: 0.9))
+      store.record(make_event(domain: :d2, magnitude: 0.1))
+      expect(store.baseline_for(:d1)).to be > store.baseline_for(:d2)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with expected keys' do
+      h = store.to_h
+      expect(h.keys).to include(:total_events, :domain_count, :average_magnitude, :most_surprising_domain, :baselines)
+    end
+
+    it 'reports 0 total events when empty' do
+      expect(store.to_h[:total_events]).to eq(0)
+    end
+
+    it 'reports correct total_events' do
+      3.times { store.record(make_event) }
+      expect(store.to_h[:total_events]).to eq(3)
+    end
+
+    it 'reports correct domain_count' do
+      store.record(make_event(domain: :a))
+      store.record(make_event(domain: :b))
+      store.record(make_event(domain: :a))
+      expect(store.to_h[:domain_count]).to eq(2)
+    end
+
+    it 'computes a sensible average_magnitude' do
+      store.record(make_event(magnitude: 0.4))
+      store.record(make_event(magnitude: 0.6))
+      expect(store.to_h[:average_magnitude]).to eq(0.5)
+    end
+
+    it 'returns nil most_surprising_domain when empty' do
+      expect(store.to_h[:most_surprising_domain]).to be_nil
+    end
+
+    it 'reports the domain of the highest magnitude event' do
+      store.record(make_event(domain: :low,  magnitude: 0.1))
+      store.record(make_event(domain: :high, magnitude: 0.9))
+      expect(store.to_h[:most_surprising_domain]).to eq(:high)
+    end
+  end
+
+  describe 'history trimming' do
+    it 'keeps at most MAX_SURPRISE_HISTORY events' do
+      max = Legion::Extensions::Agentic::Attention::Surprise::Helpers::Constants::MAX_SURPRISE_HISTORY
+      (max + 20).times { store.record(make_event) }
+      expect(store.events.size).to eq(max)
+    end
+
+    it 'removes oldest events first when trimming' do
+      max = Legion::Extensions::Agentic::Attention::Surprise::Helpers::Constants::MAX_SURPRISE_HISTORY
+      first = make_event(domain: :first_in)
+      store.record(first)
+      (max + 5).times { store.record(make_event) }
+      expect(store.events.map(&:id)).not_to include(first.id)
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/surprise/runners/surprise_spec.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Surprise::Runners::Surprise do
+  let(:runner) do
+    obj = Object.new
+    obj.extend(described_class)
+    obj
+  end
+
+  describe '#evaluate_surprise' do
+    it 'returns success with a surprise_event hash' do
+      result = runner.evaluate_surprise(domain: :memory, predicted: 0.5, actual: 0.9)
+      expect(result[:success]).to be true
+      expect(result[:surprise_event]).to be_a(Hash)
+      expect(result[:surprise_event][:domain]).to eq(:memory)
+    end
+
+    it 'includes orienting_triggered in the result' do
+      result = runner.evaluate_surprise(domain: :memory, predicted: 0.0, actual: 1.0, valence: :negative)
+      expect(result).to include(:orienting_triggered)
+    end
+
+    it 'triggers orienting when magnitude exceeds threshold' do
+      # With predicted=0.0, actual=1.0 and negative valence (weight=1.0), magnitude = 1.0 * 1.0 * 1.0 = 1.0
+      result = runner.evaluate_surprise(domain: :shock, predicted: 0.0, actual: 1.0, valence: :negative)
+      expect(result[:orienting_triggered]).to be true
+    end
+
+    it 'does not trigger orienting when magnitude is below threshold' do
+      # With predicted=0.5, actual=0.52 and neutral valence (weight=0.3), magnitude is tiny
+      result = runner.evaluate_surprise(domain: :calm, predicted: 0.5, actual: 0.52, valence: :neutral)
+      expect(result[:orienting_triggered]).to be false
+    end
+
+    it 'applies negative valence weight (1.0) for stronger response' do
+      neg = runner.evaluate_surprise(domain: :neg_d, predicted: 0.0, actual: 0.5, valence: :negative)
+      pos = runner.evaluate_surprise(domain: :pos_d, predicted: 0.0, actual: 0.5, valence: :positive)
+      expect(neg[:surprise_event][:magnitude]).to be > pos[:surprise_event][:magnitude]
+    end
+
+    it 'applies positive valence weight (0.6) correctly' do
+      result = runner.evaluate_surprise(domain: :pos_check, predicted: 0.0, actual: 1.0, valence: :positive)
+      expect(result[:surprise_event][:magnitude]).to be_within(0.001).of(0.6)
+    end
+
+    it 'applies neutral valence weight (0.3) correctly' do
+      result = runner.evaluate_surprise(domain: :neu_check, predicted: 0.0, actual: 1.0, valence: :neutral)
+      expect(result[:surprise_event][:magnitude]).to be_within(0.001).of(0.3)
+    end
+
+    it 'records the event in the store' do
+      runner.evaluate_surprise(domain: :store_test, predicted: 0.5, actual: 0.9, valence: :negative)
+      result = runner.recent_surprises(count: 1)
+      expect(result[:count]).to eq(1)
+      expect(result[:events].first[:domain]).to eq(:store_test)
+    end
+
+    it 'habituates the domain after evaluation' do
+      domain = :habituate_me
+      # Evaluate once to create a habituation entry
+      runner.evaluate_surprise(domain: domain, predicted: 0.0, actual: 1.0, valence: :negative)
+      sens = runner.domain_sensitivity(domain: domain)
+      expect(sens[:sensitivity]).to be < 1.0
+    end
+
+    it 'does not trigger orienting on the same domain during cooldown' do
+      domain = :cooldown_domain
+      # First evaluation should trigger (large surprise, negative valence)
+      first = runner.evaluate_surprise(domain: domain, predicted: 0.0, actual: 1.0, valence: :negative)
+      expect(first[:orienting_triggered]).to be true
+      # Second immediately after should be blocked by cooldown
+      second = runner.evaluate_surprise(domain: domain, predicted: 0.0, actual: 1.0, valence: :negative)
+      expect(second[:orienting_triggered]).to be false
+    end
+
+    it 'defaults valence to :neutral' do
+      result = runner.evaluate_surprise(domain: :default_val, predicted: 0.0, actual: 1.0)
+      expect(result[:surprise_event][:valence]).to eq(:neutral)
+    end
+  end
+
+  describe '#update_surprise' do
+    it 'returns success with evaluation counts' do
+      result = runner.update_surprise
+      expect(result[:success]).to be true
+      expect(result).to include(:evaluated, :orienting_count, :events)
+    end
+
+    it 'evaluates zero predictions when tick_result is empty' do
+      result = runner.update_surprise(tick_result: {})
+      expect(result[:evaluated]).to eq(0)
+    end
+
+    it 'evaluates predictions extracted from tick_result' do
+      tick_result = {
+        predictions: [
+          { domain: :cpu, predicted: 0.3, actual: 0.9, valence: :negative },
+          { domain: :mem, predicted: 0.5, actual: 0.6, valence: :neutral  }
+        ]
+      }
+      result = runner.update_surprise(tick_result: tick_result)
+      expect(result[:evaluated]).to eq(2)
+    end
+
+    it 'counts orienting events correctly' do
+      tick_result = {
+        predictions: [
+          { domain: :spike, predicted: 0.0, actual: 1.0, valence: :negative }
+        ]
+      }
+      result = runner.update_surprise(tick_result: tick_result)
+      expect(result[:orienting_count]).to be >= 0
+    end
+
+    it 'skips predictions missing required fields' do
+      tick_result = {
+        predictions: [
+          { domain: :incomplete },
+          { domain: :also_bad, predicted: 0.5 }
+        ]
+      }
+      result = runner.update_surprise(tick_result: tick_result)
+      expect(result[:evaluated]).to eq(0)
+    end
+
+    it 'handles non-hash tick_result gracefully' do
+      result = runner.update_surprise(tick_result: nil)
+      expect(result[:success]).to be true
+      expect(result[:evaluated]).to eq(0)
+    end
+
+    it 'calls decay_all on habituation model each tick' do
+      runner.evaluate_surprise(domain: :decay_test, predicted: 0.0, actual: 1.0, valence: :negative)
+      before = runner.domain_sensitivity(domain: :decay_test)[:sensitivity]
+      runner.update_surprise(tick_result: {})
+      after = runner.domain_sensitivity(domain: :decay_test)[:sensitivity]
+      expect(after).to be >= before
+    end
+  end
+
+  describe '#surprise_stats' do
+    it 'returns success' do
+      result = runner.surprise_stats
+      expect(result[:success]).to be true
+    end
+
+    it 'includes all stat keys' do
+      result = runner.surprise_stats
+      expect(result.keys).to include(
+        :total_events,
+        :domain_count,
+        :average_magnitude,
+        :most_surprising_domain,
+        :top_surprise_magnitude
+      )
+    end
+
+    it 'reports 0 total_events initially' do
+      expect(runner.surprise_stats[:total_events]).to eq(0)
+    end
+
+    it 'reports correct total after recording events' do
+      3.times { runner.evaluate_surprise(domain: :stats_d, predicted: 0.0, actual: 0.5, valence: :neutral) }
+      expect(runner.surprise_stats[:total_events]).to eq(3)
+    end
+
+    it 'returns nil top_surprise_magnitude when no events' do
+      expect(runner.surprise_stats[:top_surprise_magnitude]).to be_nil
+    end
+
+    it 'returns the magnitude of the most surprising event' do
+      runner.evaluate_surprise(domain: :low_s,  predicted: 0.4, actual: 0.5, valence: :neutral)
+      runner.evaluate_surprise(domain: :high_s, predicted: 0.0, actual: 1.0, valence: :negative)
+      top = runner.surprise_stats[:top_surprise_magnitude]
+      expect(top).to be > 0.5
+    end
+  end
+
+  describe '#domain_sensitivity' do
+    it 'returns success with domain info' do
+      result = runner.domain_sensitivity(domain: :test_domain)
+      expect(result[:success]).to be true
+      expect(result[:domain]).to eq(:test_domain)
+      expect(result).to include(:sensitivity, :baseline, :event_count)
+    end
+
+    it 'reports 1.0 sensitivity for a fresh domain' do
+      result = runner.domain_sensitivity(domain: :fresh_ds)
+      expect(result[:sensitivity]).to eq(1.0)
+    end
+
+    it 'reports reduced sensitivity after habituation' do
+      runner.evaluate_surprise(domain: :hab_ds, predicted: 0.0, actual: 1.0, valence: :negative)
+      result = runner.domain_sensitivity(domain: :hab_ds)
+      expect(result[:sensitivity]).to be < 1.0
+    end
+
+    it 'reports event_count for the domain' do
+      runner.evaluate_surprise(domain: :count_ds, predicted: 0.3, actual: 0.7, valence: :neutral)
+      runner.evaluate_surprise(domain: :count_ds, predicted: 0.3, actual: 0.7, valence: :neutral)
+      result = runner.domain_sensitivity(domain: :count_ds)
+      expect(result[:event_count]).to eq(2)
+    end
+  end
+
+  describe '#recent_surprises' do
+    it 'returns success with events array' do
+      result = runner.recent_surprises
+      expect(result[:success]).to be true
+      expect(result[:events]).to be_an(Array)
+    end
+
+    it 'returns the requested number of recent events' do
+      5.times { runner.evaluate_surprise(domain: :rs_d, predicted: 0.0, actual: 0.5, valence: :neutral) }
+      result = runner.recent_surprises(count: 3)
+      expect(result[:count]).to eq(3)
+    end
+
+    it 'returns all events when count exceeds store size' do
+      2.times { runner.evaluate_surprise(domain: :rs_small, predicted: 0.0, actual: 0.5, valence: :neutral) }
+      result = runner.recent_surprises(count: 100)
+      expect(result[:count]).to eq(2)
+    end
+
+    it 'defaults to 10 most recent' do
+      15.times { runner.evaluate_surprise(domain: :rs_many, predicted: 0.0, actual: 0.5, valence: :neutral) }
+      result = runner.recent_surprises
+      expect(result[:count]).to eq(10)
+    end
+  end
+
+  describe '#reset_habituation' do
+    it 'returns success with domain and sensitivity info' do
+      result = runner.reset_habituation(domain: :reset_d)
+      expect(result[:success]).to be true
+      expect(result[:domain]).to eq(:reset_d)
+      expect(result).to include(:old_sensitivity, :new_sensitivity)
+    end
+
+    it 'increases sensitivity after habituation' do
+      domain = :reset_test
+      10.times { runner.evaluate_surprise(domain: domain, predicted: 0.0, actual: 1.0, valence: :negative) }
+      habituated = runner.domain_sensitivity(domain: domain)[:sensitivity]
+      runner.reset_habituation(domain: domain)
+      reset = runner.domain_sensitivity(domain: domain)[:sensitivity]
+      expect(reset).to be > habituated
+    end
+
+    it 'sets sensitivity close to 1.0' do
+      domain = :full_reset
+      10.times { runner.evaluate_surprise(domain: domain, predicted: 0.0, actual: 1.0, valence: :negative) }
+      runner.reset_habituation(domain: domain)
+      expect(runner.domain_sensitivity(domain: domain)[:sensitivity]).to be_within(0.05).of(1.0)
+    end
+
+    it 'reports old_sensitivity accurately' do
+      domain = :old_sens
+      runner.evaluate_surprise(domain: domain, predicted: 0.0, actual: 1.0, valence: :negative)
+      before = runner.domain_sensitivity(domain: domain)[:sensitivity]
+      result = runner.reset_habituation(domain: domain)
+      expect(result[:old_sensitivity]).to eq(before)
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/switching/attention_switching_spec.rb

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

data/spec/legion/extensions/agentic/attention/switching/helpers/switch_event_spec.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Switching::Helpers::SwitchEvent do
+  subject(:event) do
+    described_class.new(
+      from_task_id:          'task-a',
+      to_task_id:            'task-b',
+      switch_cost:           0.4,
+      residual_interference: 0.3,
+      warmup_needed:         0.2
+    )
+  end
+
+  describe '#initialize' do
+    it 'assigns a UUID id' do
+      expect(event.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets task ids' do
+      expect(event.from_task_id).to eq('task-a')
+      expect(event.to_task_id).to eq('task-b')
+    end
+
+    it 'sets switch cost' do
+      expect(event.switch_cost).to eq(0.4)
+    end
+
+    it 'clamps cost values' do
+      high = described_class.new(from_task_id: 'a', to_task_id: 'b',
+                                 switch_cost: 5.0, residual_interference: 0.0, warmup_needed: 0.0)
+      expect(high.switch_cost).to eq(1.0)
+    end
+  end
+
+  describe '#costly?' do
+    it 'is false for moderate cost' do
+      expect(event.costly?).to be false
+    end
+
+    it 'is true for high cost' do
+      high = described_class.new(from_task_id: 'a', to_task_id: 'b',
+                                 switch_cost: 0.8, residual_interference: 0.0, warmup_needed: 0.0)
+      expect(high.costly?).to be true
+    end
+  end
+
+  describe '#cheap?' do
+    it 'is false for moderate cost' do
+      expect(event.cheap?).to be false
+    end
+
+    it 'is true for low cost' do
+      low = described_class.new(from_task_id: 'a', to_task_id: 'b',
+                                switch_cost: 0.1, residual_interference: 0.0, warmup_needed: 0.0)
+      expect(low.cheap?).to be true
+    end
+  end
+
+  describe '#cost_label' do
+    it 'returns a symbol' do
+      expect(event.cost_label).to be_a(Symbol)
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all fields' do
+      hash = event.to_h
+      expect(hash).to include(
+        :id, :from_task_id, :to_task_id, :switch_cost, :cost_label,
+        :costly, :cheap, :residual_interference, :warmup_needed, :created_at
+      )
+    end
+  end
+end