lex-agentic-attention 0.1.0

data/spec/legion/extensions/agentic/attention/sensory_gating/helpers/sensory_filter_spec.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::SensoryGating::Helpers::SensoryFilter do
+  subject(:filter) { described_class.new(modality: :visual) }
+
+  describe '#initialize' do
+    it 'assigns a UUID id' do
+      expect(filter.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets modality' do
+      expect(filter.modality).to eq(:visual)
+    end
+
+    it 'defaults gate_threshold' do
+      default = Legion::Extensions::Agentic::Attention::SensoryGating::Helpers::Constants::DEFAULT_GATE_THRESHOLD
+      expect(filter.gate_threshold).to eq(default)
+    end
+
+    it 'starts with 0 habituation' do
+      expect(filter.habituation_level).to eq(0.0)
+    end
+
+    it 'starts with 0 passed and blocked' do
+      expect(filter.stimuli_passed).to eq(0)
+      expect(filter.stimuli_blocked).to eq(0)
+    end
+  end
+
+  describe '#process' do
+    it 'passes high-intensity stimuli' do
+      expect(filter.process(intensity: 0.9)).to eq(:passed)
+      expect(filter.stimuli_passed).to eq(1)
+    end
+
+    it 'blocks low-intensity stimuli' do
+      expect(filter.process(intensity: 0.1)).to eq(:blocked)
+      expect(filter.stimuli_blocked).to eq(1)
+    end
+
+    it 'habituates after passing stimuli' do
+      filter.process(intensity: 0.9)
+      expect(filter.habituation_level).to be > 0.0
+    end
+  end
+
+  describe '#open_gate!' do
+    it 'decreases gate threshold' do
+      original = filter.gate_threshold
+      filter.open_gate!
+      expect(filter.gate_threshold).to be < original
+    end
+
+    it 'clamps at 0.0' do
+      f = described_class.new(modality: :visual, gate_threshold: 0.01)
+      f.open_gate!(amount: 0.5)
+      expect(f.gate_threshold).to eq(0.0)
+    end
+  end
+
+  describe '#close_gate!' do
+    it 'increases gate threshold' do
+      original = filter.gate_threshold
+      filter.close_gate!
+      expect(filter.gate_threshold).to be > original
+    end
+  end
+
+  describe '#sensitize!' do
+    it 'decreases habituation level' do
+      filter.process(intensity: 0.9)
+      hab = filter.habituation_level
+      filter.sensitize!
+      expect(filter.habituation_level).to be < hab
+    end
+  end
+
+  describe '#reset_habituation!' do
+    it 'resets habituation to 0' do
+      filter.process(intensity: 0.9)
+      filter.reset_habituation!
+      expect(filter.habituation_level).to eq(0.0)
+    end
+  end
+
+  describe '#effective_threshold' do
+    it 'combines gate_threshold and habituation' do
+      filter.process(intensity: 0.9)
+      expect(filter.effective_threshold).to be > filter.gate_threshold
+    end
+  end
+
+  describe '#pass_rate' do
+    it 'returns 0.0 with no stimuli' do
+      expect(filter.pass_rate).to eq(0.0)
+    end
+
+    it 'calculates ratio' do
+      filter.process(intensity: 0.9)
+      filter.process(intensity: 0.1)
+      expect(filter.pass_rate).to eq(0.5)
+    end
+  end
+
+  describe '#gate_label' do
+    it 'returns a symbol' do
+      expect(filter.gate_label).to be_a(Symbol)
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all fields' do
+      hash = filter.to_h
+      expect(hash).to include(
+        :id, :modality, :gate_threshold, :effective_threshold,
+        :habituation_level, :gate_label, :stimuli_passed,
+        :stimuli_blocked, :pass_rate, :created_at
+      )
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/sensory_gating/runners/sensory_gating_spec.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::SensoryGating::Runners::SensoryGating do
+  let(:client) { Legion::Extensions::Agentic::Attention::SensoryGating::Client.new }
+
+  describe '#create_filter' do
+    it 'returns success with filter hash' do
+      result = client.create_filter(modality: :visual)
+      expect(result[:success]).to be true
+      expect(result[:filter]).to include(:id, :modality, :gate_threshold)
+    end
+  end
+
+  describe '#process_stimulus' do
+    it 'returns outcome' do
+      f = client.create_filter(modality: :visual)
+      result = client.process_stimulus(filter_id: f[:filter][:id], intensity: 0.9)
+      expect(result[:success]).to be true
+      expect(result[:outcome]).to eq(:passed)
+    end
+
+    it 'returns failure for unknown id' do
+      result = client.process_stimulus(filter_id: 'fake', intensity: 0.5)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#open_gate' do
+    it 'decreases threshold' do
+      f = client.create_filter(modality: :visual)
+      result = client.open_gate(filter_id: f[:filter][:id])
+      expect(result[:success]).to be true
+      expect(result[:filter][:gate_threshold]).to be < 0.5
+    end
+  end
+
+  describe '#close_gate' do
+    it 'increases threshold' do
+      f = client.create_filter(modality: :visual)
+      result = client.close_gate(filter_id: f[:filter][:id])
+      expect(result[:success]).to be true
+      expect(result[:filter][:gate_threshold]).to be > 0.5
+    end
+  end
+
+  describe '#average_pass_rate' do
+    it 'returns pass rate' do
+      result = client.average_pass_rate
+      expect(result[:success]).to be true
+      expect(result[:pass_rate]).to be_a(Numeric)
+    end
+  end
+
+  describe '#gating_report' do
+    it 'returns a full report' do
+      result = client.gating_report
+      expect(result[:success]).to be true
+      expect(result[:report]).to include(:total_filters, :average_pass_rate)
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/attention/signal_detection/client'
+
+RSpec.describe Legion::Extensions::Agentic::Attention::SignalDetection::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to all runner methods' do
+    expect(client).to respond_to(:create_detector)
+    expect(client).to respond_to(:record_detection_trial)
+    expect(client).to respond_to(:compute_detector_sensitivity)
+    expect(client).to respond_to(:adjust_detector_bias)
+    expect(client).to respond_to(:best_detectors)
+    expect(client).to respond_to(:domain_detectors)
+    expect(client).to respond_to(:optimal_detector_criterion)
+    expect(client).to respond_to(:detector_roc_point)
+    expect(client).to respond_to(:update_signal_detection)
+    expect(client).to respond_to(:signal_detection_stats)
+  end
+end

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::SignalDetection::Helpers::Constants do
+  describe '.sensitivity_label' do
+    it 'labels exceptional for d_prime >= 3.0' do
+      expect(described_class.sensitivity_label(3.5)).to eq(:exceptional)
+    end
+
+    it 'labels excellent for 2.0 <= d_prime < 3.0' do
+      expect(described_class.sensitivity_label(2.5)).to eq(:excellent)
+    end
+
+    it 'labels good for 1.0 <= d_prime < 2.0' do
+      expect(described_class.sensitivity_label(1.5)).to eq(:good)
+    end
+
+    it 'labels moderate for 0.5 <= d_prime < 1.0' do
+      expect(described_class.sensitivity_label(0.7)).to eq(:moderate)
+    end
+
+    it 'labels poor for d_prime < 0.5' do
+      expect(described_class.sensitivity_label(0.2)).to eq(:poor)
+    end
+  end
+
+  describe '.bias_label' do
+    it 'labels very_conservative for criterion >= 1.0' do
+      expect(described_class.bias_label(1.5)).to eq(:very_conservative)
+    end
+
+    it 'labels conservative for 0.3 <= criterion < 1.0' do
+      expect(described_class.bias_label(0.5)).to eq(:conservative)
+    end
+
+    it 'labels neutral for -0.3 <= criterion < 0.3' do
+      expect(described_class.bias_label(0.0)).to eq(:neutral)
+    end
+
+    it 'labels liberal for -1.0 <= criterion < -0.3' do
+      expect(described_class.bias_label(-0.5)).to eq(:liberal)
+    end
+
+    it 'labels very_liberal for criterion < -1.0' do
+      expect(described_class.bias_label(-1.5)).to eq(:very_liberal)
+    end
+  end
+
+  describe '.clamp_sensitivity' do
+    it 'clamps to floor' do
+      expect(described_class.clamp_sensitivity(-1.0)).to eq(0.0)
+    end
+
+    it 'clamps to ceiling' do
+      expect(described_class.clamp_sensitivity(10.0)).to eq(5.0)
+    end
+
+    it 'passes through valid values' do
+      expect(described_class.clamp_sensitivity(2.5)).to eq(2.5)
+    end
+  end
+
+  describe '.clamp_criterion' do
+    it 'clamps to floor' do
+      expect(described_class.clamp_criterion(-5.0)).to eq(-3.0)
+    end
+
+    it 'clamps to ceiling' do
+      expect(described_class.clamp_criterion(5.0)).to eq(3.0)
+    end
+
+    it 'passes through valid values' do
+      expect(described_class.clamp_criterion(1.0)).to eq(1.0)
+    end
+  end
+
+  describe 'TRIAL_OUTCOMES' do
+    it 'includes all four outcomes' do
+      expect(described_class::TRIAL_OUTCOMES).to include(:hit, :miss, :false_alarm, :correct_rejection)
+    end
+
+    it 'is frozen' do
+      expect(described_class::TRIAL_OUTCOMES).to be_frozen
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/signal_detection/helpers/detection_engine_spec.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::SignalDetection::Helpers::DetectionEngine do
+  subject(:engine) { described_class.new }
+
+  let(:detector_id) { engine.create_detector(domain: :vision).id }
+
+  describe '#create_detector' do
+    it 'creates a detector and returns it' do
+      detector = engine.create_detector(domain: :auditory)
+      expect(detector).to be_a(Legion::Extensions::Agentic::Attention::SignalDetection::Helpers::Detector)
+    end
+
+    it 'increments count' do
+      engine.create_detector(domain: :auditory)
+      engine.create_detector(domain: :visual)
+      expect(engine.count).to eq(2)
+    end
+
+    it 'raises when max detectors reached' do
+      stub_const('Legion::Extensions::Agentic::Attention::SignalDetection::Helpers::Constants::MAX_DETECTORS', 1)
+      engine.create_detector(domain: :test)
+      expect { engine.create_detector(domain: :overflow) }.to raise_error(ArgumentError, /max detectors/)
+    end
+  end
+
+  describe '#record_trial' do
+    it 'records a hit when signal present and responded present' do
+      result = engine.record_trial(detector_id: detector_id, signal_present: true, responded_present: true)
+      expect(result[:outcome]).to eq(:hit)
+    end
+
+    it 'records a miss when signal present and not responded' do
+      result = engine.record_trial(detector_id: detector_id, signal_present: true, responded_present: false)
+      expect(result[:outcome]).to eq(:miss)
+    end
+
+    it 'records a false alarm when no signal and responded present' do
+      result = engine.record_trial(detector_id: detector_id, signal_present: false, responded_present: true)
+      expect(result[:outcome]).to eq(:false_alarm)
+    end
+
+    it 'records a correct rejection when no signal and not responded' do
+      result = engine.record_trial(detector_id: detector_id, signal_present: false, responded_present: false)
+      expect(result[:outcome]).to eq(:correct_rejection)
+    end
+
+    it 'raises KeyError for unknown detector' do
+      expect do
+        engine.record_trial(detector_id: 'bogus', signal_present: true, responded_present: true)
+      end.to raise_error(KeyError)
+    end
+  end
+
+  describe '#compute_sensitivity' do
+    it 'returns d_prime, criterion, accuracy' do
+      5.times { engine.record_trial(detector_id: detector_id, signal_present: true, responded_present: true) }
+      2.times { engine.record_trial(detector_id: detector_id, signal_present: false, responded_present: false) }
+      result = engine.compute_sensitivity(detector_id: detector_id)
+      expect(result).to include(:d_prime, :criterion, :accuracy, :hit_rate, :false_alarm_rate)
+    end
+
+    it 'raises KeyError for unknown detector' do
+      expect { engine.compute_sensitivity(detector_id: 'unknown') }.to raise_error(KeyError)
+    end
+  end
+
+  describe '#adjust_bias' do
+    it 'shifts the criterion' do
+      before = engine.get(detector_id).criterion
+      engine.adjust_bias(detector_id: detector_id, amount: 0.5)
+      expect(engine.get(detector_id).criterion).to be > before
+    end
+  end
+
+  describe '#best_detectors' do
+    it 'returns detectors sorted by sensitivity' do
+      id1 = engine.create_detector(domain: :A).id
+      id2 = engine.create_detector(domain: :B).id
+      10.times { engine.record_trial(detector_id: id1, signal_present: true, responded_present: true) }
+      engine.record_trial(detector_id: id1, signal_present: false, responded_present: true)
+      2.times  { engine.record_trial(detector_id: id2, signal_present: true, responded_present: true) }
+      10.times { engine.record_trial(detector_id: id2, signal_present: false, responded_present: true) }
+      result = engine.best_detectors(limit: 2)
+      expect(result.first[:sensitivity]).to be >= result.last[:sensitivity]
+    end
+
+    it 'respects limit' do
+      3.times { |i| engine.create_detector(domain: :"d#{i}") }
+      expect(engine.best_detectors(limit: 2).size).to eq(2)
+    end
+  end
+
+  describe '#by_domain' do
+    it 'filters by domain' do
+      engine.create_detector(domain: :audio)
+      engine.create_detector(domain: :audio)
+      engine.create_detector(domain: :visual)
+      result = engine.by_domain(domain: :audio)
+      expect(result.size).to eq(2)
+      expect(result.all? { |d| d[:domain] == :audio }).to be true
+    end
+  end
+
+  describe '#optimal_criterion' do
+    it 'returns optimal criterion for balanced prior' do
+      result = engine.optimal_criterion(detector_id: detector_id, signal_probability: 0.5)
+      expect(result[:optimal_criterion]).to be_within(0.001).of(0.0)
+    end
+
+    it 'returns positive criterion for low signal probability' do
+      result = engine.optimal_criterion(detector_id: detector_id, signal_probability: 0.2)
+      expect(result[:optimal_criterion]).to be > 0
+    end
+  end
+
+  describe '#roc_point' do
+    it 'returns hit_rate and false_alarm_rate' do
+      result = engine.roc_point(detector_id: detector_id)
+      expect(result).to include(:hit_rate, :false_alarm_rate, :d_prime)
+    end
+  end
+
+  describe '#decay_all' do
+    it 'returns count of detectors updated' do
+      engine.record_trial(detector_id: detector_id, signal_present: true, responded_present: true)
+      count = engine.decay_all
+      expect(count).to eq(1)
+    end
+
+    it 'skips detectors with no trials' do
+      count = engine.decay_all
+      expect(count).to eq(0)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns detector count and map' do
+      result = engine.to_h
+      expect(result).to include(:detector_count, :detectors)
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/signal_detection/helpers/detector_spec.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::SignalDetection::Helpers::Detector do
+  subject(:detector) { described_class.new(domain: :threat) }
+
+  describe '#initialize' do
+    it 'assigns an id' do
+      expect(detector.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets domain' do
+      expect(detector.domain).to eq(:threat)
+    end
+
+    it 'starts with default sensitivity' do
+      expect(detector.sensitivity).to eq(Legion::Extensions::Agentic::Attention::SignalDetection::Helpers::Constants::DEFAULT_SENSITIVITY)
+    end
+
+    it 'starts with default criterion' do
+      expect(detector.criterion).to eq(Legion::Extensions::Agentic::Attention::SignalDetection::Helpers::Constants::DEFAULT_CRITERION)
+    end
+
+    it 'starts with zero counts' do
+      expect(detector.hits).to eq(0)
+      expect(detector.misses).to eq(0)
+      expect(detector.false_alarms).to eq(0)
+      expect(detector.correct_rejections).to eq(0)
+      expect(detector.trial_count).to eq(0)
+    end
+  end
+
+  describe '#record_trial' do
+    it 'increments hits on :hit' do
+      detector.record_trial(outcome: :hit)
+      expect(detector.hits).to eq(1)
+      expect(detector.trial_count).to eq(1)
+    end
+
+    it 'increments misses on :miss' do
+      detector.record_trial(outcome: :miss)
+      expect(detector.misses).to eq(1)
+    end
+
+    it 'increments false_alarms on :false_alarm' do
+      detector.record_trial(outcome: :false_alarm)
+      expect(detector.false_alarms).to eq(1)
+    end
+
+    it 'increments correct_rejections on :correct_rejection' do
+      detector.record_trial(outcome: :correct_rejection)
+      expect(detector.correct_rejections).to eq(1)
+    end
+
+    it 'raises on invalid outcome' do
+      expect { detector.record_trial(outcome: :bogus) }.to raise_error(ArgumentError, /invalid outcome/)
+    end
+
+    it 'updates last_trial_at' do
+      expect(detector.last_trial_at).to be_nil
+      detector.record_trial(outcome: :hit)
+      expect(detector.last_trial_at).to be_a(Time)
+    end
+  end
+
+  describe '#hit_rate' do
+    it 'applies Hautus correction' do
+      expect(detector.hit_rate).to be_between(0.0, 1.0)
+    end
+
+    it 'increases as hits accumulate' do
+      before = detector.hit_rate
+      5.times { detector.record_trial(outcome: :hit) }
+      expect(detector.hit_rate).to be > before
+    end
+  end
+
+  describe '#false_alarm_rate' do
+    it 'applies Hautus correction' do
+      expect(detector.false_alarm_rate).to be_between(0.0, 1.0)
+    end
+
+    it 'increases as false alarms accumulate' do
+      before = detector.false_alarm_rate
+      5.times { detector.record_trial(outcome: :false_alarm) }
+      expect(detector.false_alarm_rate).to be > before
+    end
+  end
+
+  describe '#compute_dprime' do
+    it 'returns a float within sensitivity bounds' do
+      5.times { detector.record_trial(outcome: :hit) }
+      2.times { detector.record_trial(outcome: :miss) }
+      2.times { detector.record_trial(outcome: :false_alarm) }
+      3.times { detector.record_trial(outcome: :correct_rejection) }
+      expect(detector.compute_dprime).to be_between(
+        Legion::Extensions::Agentic::Attention::SignalDetection::Helpers::Constants::SENSITIVITY_FLOOR,
+        Legion::Extensions::Agentic::Attention::SignalDetection::Helpers::Constants::SENSITIVITY_CEILING
+      )
+    end
+
+    it 'is positive when hit_rate > false_alarm_rate' do
+      10.times { detector.record_trial(outcome: :hit) }
+      detector.record_trial(outcome: :false_alarm)
+      expect(detector.compute_dprime).to be > 0
+    end
+  end
+
+  describe '#compute_criterion' do
+    it 'returns a float within criterion bounds' do
+      5.times { detector.record_trial(outcome: :hit) }
+      5.times { detector.record_trial(outcome: :miss) }
+      result = detector.compute_criterion
+      expect(result).to be_between(
+        Legion::Extensions::Agentic::Attention::SignalDetection::Helpers::Constants::CRITERION_FLOOR,
+        Legion::Extensions::Agentic::Attention::SignalDetection::Helpers::Constants::CRITERION_CEILING
+      )
+    end
+  end
+
+  describe '#accuracy' do
+    it 'returns 0.0 with no trials' do
+      expect(detector.accuracy).to eq(0.0)
+    end
+
+    it 'computes correctly' do
+      3.times { detector.record_trial(outcome: :hit) }
+      2.times { detector.record_trial(outcome: :correct_rejection) }
+      expect(detector.accuracy).to eq(1.0)
+    end
+
+    it 'decreases with errors' do
+      2.times { detector.record_trial(outcome: :hit) }
+      2.times { detector.record_trial(outcome: :miss) }
+      2.times { detector.record_trial(outcome: :false_alarm) }
+      2.times { detector.record_trial(outcome: :correct_rejection) }
+      expect(detector.accuracy).to eq(0.5)
+    end
+  end
+
+  describe '#sensitivity_label' do
+    it 'returns a symbol' do
+      expect(detector.sensitivity_label).to be_a(Symbol)
+    end
+  end
+
+  describe '#bias_label' do
+    it 'returns a symbol' do
+      expect(detector.bias_label).to be_a(Symbol)
+    end
+  end
+
+  describe '#adjust_criterion' do
+    it 'shifts criterion by amount' do
+      initial = detector.criterion
+      detector.adjust_criterion(amount: 0.5)
+      expect(detector.criterion).to eq(initial + 0.5)
+    end
+
+    it 'clamps at ceiling' do
+      detector.adjust_criterion(amount: 10.0)
+      expect(detector.criterion).to eq(Legion::Extensions::Agentic::Attention::SignalDetection::Helpers::Constants::CRITERION_CEILING)
+    end
+
+    it 'clamps at floor' do
+      detector.adjust_criterion(amount: -10.0)
+      expect(detector.criterion).to eq(Legion::Extensions::Agentic::Attention::SignalDetection::Helpers::Constants::CRITERION_FLOOR)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with expected keys' do
+      result = detector.to_h
+      expect(result).to include(:id, :domain, :sensitivity, :criterion, :hits, :misses,
+                                :false_alarms, :correct_rejections, :trial_count,
+                                :hit_rate, :false_alarm_rate, :accuracy,
+                                :sensitivity_label, :bias_label, :created_at)
+    end
+  end
+end