lex-agentic-attention 0.1.0

data/spec/legion/extensions/agentic/attention/signal_detection/runners/signal_detection_spec.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/attention/signal_detection/client'
+
+RSpec.describe Legion::Extensions::Agentic::Attention::SignalDetection::Runners::SignalDetection do
+  let(:client) { Legion::Extensions::Agentic::Attention::SignalDetection::Client.new }
+
+  describe '#create_detector' do
+    it 'creates a detector and returns id' do
+      result = client.create_detector(domain: :threat)
+      expect(result[:created]).to be true
+      expect(result[:detector_id]).to match(/\A[0-9a-f-]{36}\z/)
+      expect(result[:domain]).to eq(:threat)
+    end
+  end
+
+  describe '#record_detection_trial' do
+    it 'records a hit' do
+      id = client.create_detector(domain: :test)[:detector_id]
+      result = client.record_detection_trial(detector_id: id, signal_present: true, responded_present: true)
+      expect(result[:outcome]).to eq(:hit)
+      expect(result[:trial_count]).to eq(1)
+    end
+
+    it 'records a miss' do
+      id = client.create_detector(domain: :test)[:detector_id]
+      result = client.record_detection_trial(detector_id: id, signal_present: true, responded_present: false)
+      expect(result[:outcome]).to eq(:miss)
+    end
+
+    it 'records a false alarm' do
+      id = client.create_detector(domain: :test)[:detector_id]
+      result = client.record_detection_trial(detector_id: id, signal_present: false, responded_present: true)
+      expect(result[:outcome]).to eq(:false_alarm)
+    end
+
+    it 'records a correct rejection' do
+      id = client.create_detector(domain: :test)[:detector_id]
+      result = client.record_detection_trial(detector_id: id, signal_present: false, responded_present: false)
+      expect(result[:outcome]).to eq(:correct_rejection)
+    end
+
+    it 'returns not_found for unknown detector' do
+      result = client.record_detection_trial(detector_id: 'nonexistent', signal_present: true, responded_present: true)
+      expect(result[:reason]).to eq(:not_found)
+    end
+  end
+
+  describe '#compute_detector_sensitivity' do
+    let(:detector_id) do
+      id = client.create_detector(domain: :test)[:detector_id]
+      8.times { client.record_detection_trial(detector_id: id, signal_present: true, responded_present: true) }
+      2.times { client.record_detection_trial(detector_id: id, signal_present: false, responded_present: true) }
+      id
+    end
+
+    it 'returns d_prime and criterion' do
+      result = client.compute_detector_sensitivity(detector_id: detector_id)
+      expect(result).to include(:d_prime, :criterion, :accuracy)
+    end
+
+    it 'returns sensitivity_label' do
+      result = client.compute_detector_sensitivity(detector_id: detector_id)
+      expect(result[:sensitivity_label]).to be_a(Symbol)
+    end
+
+    it 'returns not_found for unknown detector' do
+      result = client.compute_detector_sensitivity(detector_id: 'unknown')
+      expect(result[:found]).to be false
+    end
+  end
+
+  describe '#adjust_detector_bias' do
+    it 'shifts the criterion' do
+      id = client.create_detector(domain: :test)[:detector_id]
+      result = client.adjust_detector_bias(detector_id: id, amount: 0.5)
+      expect(result[:criterion]).to be > 0.0
+      expect(result[:bias_label]).to be_a(Symbol)
+    end
+
+    it 'returns not_found for unknown detector' do
+      result = client.adjust_detector_bias(detector_id: 'none', amount: 0.1)
+      expect(result[:adjusted]).to be false
+    end
+  end
+
+  describe '#best_detectors' do
+    it 'returns list sorted by sensitivity' do
+      client.create_detector(domain: :A)
+      client.create_detector(domain: :B)
+      result = client.best_detectors(limit: 2)
+      expect(result[:count]).to eq(2)
+      expect(result[:detectors]).to be_an(Array)
+    end
+  end
+
+  describe '#domain_detectors' do
+    it 'filters by domain' do
+      client.create_detector(domain: :audio)
+      client.create_detector(domain: :audio)
+      client.create_detector(domain: :visual)
+      result = client.domain_detectors(domain: :audio)
+      expect(result[:count]).to eq(2)
+      expect(result[:domain]).to eq(:audio)
+    end
+  end
+
+  describe '#optimal_detector_criterion' do
+    it 'returns optimal criterion for balanced prior' do
+      id = client.create_detector(domain: :test)[:detector_id]
+      result = client.optimal_detector_criterion(detector_id: id, signal_probability: 0.5)
+      expect(result[:optimal_criterion]).to be_within(0.001).of(0.0)
+    end
+
+    it 'returns not_found for unknown detector' do
+      result = client.optimal_detector_criterion(detector_id: 'none')
+      expect(result[:found]).to be false
+    end
+  end
+
+  describe '#detector_roc_point' do
+    it 'returns hit_rate and false_alarm_rate' do
+      id = client.create_detector(domain: :test)[:detector_id]
+      result = client.detector_roc_point(detector_id: id)
+      expect(result).to include(:hit_rate, :false_alarm_rate, :d_prime)
+    end
+
+    it 'returns not_found for unknown detector' do
+      result = client.detector_roc_point(detector_id: 'none')
+      expect(result[:found]).to be false
+    end
+  end
+
+  describe '#update_signal_detection' do
+    it 'runs decay cycle' do
+      id = client.create_detector(domain: :test)[:detector_id]
+      client.record_detection_trial(detector_id: id, signal_present: true, responded_present: true)
+      result = client.update_signal_detection
+      expect(result).to include(:decayed)
+    end
+  end
+
+  describe '#signal_detection_stats' do
+    it 'returns total_detectors and top_detectors' do
+      2.times { |i| client.create_detector(domain: :"d#{i}") }
+      result = client.signal_detection_stats
+      expect(result[:total_detectors]).to eq(2)
+      expect(result[:top_detectors]).to be_an(Array)
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/attention/spotlight/client'
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Spotlight::Client do
+  it 'responds to all runner methods' do
+    client = described_class.new
+    expect(client).to respond_to(:register_target)
+    expect(client).to respond_to(:focus_spotlight)
+    expect(client).to respond_to(:broaden_spotlight)
+    expect(client).to respond_to(:narrow_spotlight)
+    expect(client).to respond_to(:scan_targets)
+    expect(client).to respond_to(:check_peripheral)
+    expect(client).to respond_to(:check_capture)
+    expect(client).to respond_to(:release_focus)
+    expect(client).to respond_to(:spotlight_report)
+    expect(client).to respond_to(:most_salient)
+    expect(client).to respond_to(:spotlight_state)
+  end
+
+  it 'accepts an injected engine' do
+    engine = Legion::Extensions::Agentic::Attention::Spotlight::Helpers::SpotlightEngine.new
+    client = described_class.new(engine: engine)
+    expect(client.spotlight_state[:success]).to be true
+  end
+
+  it 'uses an internal engine when none injected' do
+    client = described_class.new
+    expect(client.spotlight_state[:success]).to be true
+  end
+end

data/spec/legion/extensions/agentic/attention/spotlight/helpers/attention_target_spec.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Spotlight::Helpers::AttentionTarget do
+  subject(:target) { described_class.new(label: 'test task', domain: :work) }
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(target.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets label' do
+      expect(target.label).to eq('test task')
+    end
+
+    it 'sets domain' do
+      expect(target.domain).to eq(:work)
+    end
+
+    it 'defaults salience to 0.5' do
+      expect(target.salience).to eq(0.5)
+    end
+
+    it 'defaults relevance to 0.5' do
+      expect(target.relevance).to eq(0.5)
+    end
+
+    it 'starts with in_spotlight false' do
+      expect(target.in_spotlight).to be false
+    end
+
+    it 'starts with in_periphery false' do
+      expect(target.in_periphery).to be false
+    end
+
+    it 'starts with capture_count 0' do
+      expect(target.capture_count).to eq(0)
+    end
+
+    it 'sets created_at' do
+      expect(target.created_at).to be_a(Time)
+    end
+
+    it 'starts with last_attended_at nil' do
+      expect(target.last_attended_at).to be_nil
+    end
+
+    it 'clamps salience above 1.0' do
+      t = described_class.new(label: 'x', domain: :test, salience: 2.5)
+      expect(t.salience).to eq(1.0)
+    end
+
+    it 'clamps salience below 0.0' do
+      t = described_class.new(label: 'x', domain: :test, salience: -0.5)
+      expect(t.salience).to eq(0.0)
+    end
+
+    it 'clamps relevance to valid range' do
+      t = described_class.new(label: 'x', domain: :test, relevance: 1.5)
+      expect(t.relevance).to eq(1.0)
+    end
+  end
+
+  describe '#compelling?' do
+    it 'returns false when salience is below capture threshold' do
+      target.salience = 0.7
+      expect(target.compelling?).to be false
+    end
+
+    it 'returns true when salience meets capture threshold' do
+      target.salience = 0.8
+      expect(target.compelling?).to be true
+    end
+
+    it 'returns true when salience exceeds capture threshold' do
+      target.salience = 0.95
+      expect(target.compelling?).to be true
+    end
+  end
+
+  describe '#salient?' do
+    it 'returns false when salience is below peripheral detection threshold' do
+      target.salience = 0.2
+      expect(target.salient?).to be false
+    end
+
+    it 'returns true when salience meets peripheral detection threshold' do
+      target.salience = 0.3
+      expect(target.salient?).to be true
+    end
+
+    it 'returns true when salience exceeds threshold' do
+      target.salience = 0.6
+      expect(target.salient?).to be true
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with all expected keys' do
+      h = target.to_h
+      expect(h.keys).to include(:id, :label, :domain, :salience, :relevance,
+                                :in_spotlight, :in_periphery, :capture_count,
+                                :compelling, :salient, :created_at, :last_attended_at)
+    end
+
+    it 'rounds salience to 10 decimal places' do
+      target.salience = 1.0 / 3.0
+      h = target.to_h
+      expect(h[:salience]).to eq((1.0 / 3.0).round(10))
+    end
+
+    it 'includes computed compelling value' do
+      target.salience = 0.9
+      expect(target.to_h[:compelling]).to be true
+    end
+
+    it 'includes computed salient value' do
+      target.salience = 0.05
+      expect(target.to_h[:salient]).to be false
+    end
+  end
+end

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Spotlight::Helpers::Constants do
+  subject(:mod) { described_class }
+
+  describe 'numeric constants' do
+    it 'has MAX_TARGETS = 200' do
+      expect(mod::MAX_TARGETS).to eq(200)
+    end
+
+    it 'has MAX_PERIPHERAL = 100' do
+      expect(mod::MAX_PERIPHERAL).to eq(100)
+    end
+
+    it 'has DEFAULT_INTENSITY = 0.5' do
+      expect(mod::DEFAULT_INTENSITY).to eq(0.5)
+    end
+
+    it 'has DEFAULT_BREADTH = 0.5' do
+      expect(mod::DEFAULT_BREADTH).to eq(0.5)
+    end
+
+    it 'has ZOOM_STEP = 0.1' do
+      expect(mod::ZOOM_STEP).to eq(0.1)
+    end
+
+    it 'has INTENSITY_GAIN = 0.15' do
+      expect(mod::INTENSITY_GAIN).to eq(0.15)
+    end
+
+    it 'has INTENSITY_LOSS = 0.1' do
+      expect(mod::INTENSITY_LOSS).to eq(0.1)
+    end
+
+    it 'has PERIPHERAL_DETECTION_THRESHOLD = 0.3' do
+      expect(mod::PERIPHERAL_DETECTION_THRESHOLD).to eq(0.3)
+    end
+
+    it 'has CAPTURE_THRESHOLD = 0.8' do
+      expect(mod::CAPTURE_THRESHOLD).to eq(0.8)
+    end
+  end
+
+  describe 'array constants' do
+    it 'has 5 ZOOM_LEVELS' do
+      expect(mod::ZOOM_LEVELS).to eq(%i[laser narrow moderate wide diffuse])
+    end
+
+    it 'has 4 MODE_LABELS' do
+      expect(mod::MODE_LABELS).to eq(%i[focused scanning captured idle])
+    end
+  end
+
+  describe 'ZOOM_RANGES' do
+    it 'covers 0.0 with :laser' do
+      entry = mod::ZOOM_RANGES.find { |z| z[:range].cover?(0.0) }
+      expect(entry[:level]).to eq(:laser)
+    end
+
+    it 'covers 0.5 with :moderate' do
+      entry = mod::ZOOM_RANGES.find { |z| z[:range].cover?(0.5) }
+      expect(entry[:level]).to eq(:moderate)
+    end
+
+    it 'covers 1.0 with :diffuse' do
+      entry = mod::ZOOM_RANGES.find { |z| z[:range].cover?(1.0) }
+      expect(entry[:level]).to eq(:diffuse)
+    end
+  end
+
+  describe 'INTENSITY_LABELS' do
+    it 'covers 0.9 with :blazing' do
+      entry = mod::INTENSITY_LABELS.find { |il| il[:range].cover?(0.9) }
+      expect(entry[:label]).to eq(:blazing)
+    end
+
+    it 'covers 0.1 with :dark' do
+      entry = mod::INTENSITY_LABELS.find { |il| il[:range].cover?(0.1) }
+      expect(entry[:label]).to eq(:dark)
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/spotlight/helpers/spotlight_engine_spec.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Spotlight::Helpers::SpotlightEngine do
+  subject(:engine) { described_class.new }
+
+  def register(label: 'task', domain: :work, salience: 0.5, relevance: 0.5)
+    engine.register_target(label: label, domain: domain, salience: salience, relevance: relevance)
+  end
+
+  describe '#initialize' do
+    it 'starts with empty targets' do
+      expect(engine.targets).to be_empty
+    end
+
+    it 'starts with a Spotlight instance' do
+      expect(engine.spotlight).to be_a(Legion::Extensions::Agentic::Attention::Spotlight::Helpers::Spotlight)
+    end
+
+    it 'starts with empty peripheral' do
+      expect(engine.peripheral).to be_empty
+    end
+  end
+
+  describe '#register_target' do
+    it 'registers a target and returns a target_id' do
+      result = register
+      expect(result[:registered]).to be true
+      expect(result[:target_id]).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores the target in @targets' do
+      result = register
+      expect(engine.targets).to have_key(result[:target_id])
+    end
+
+    it 'respects MAX_TARGETS limit' do
+      stub_const('Legion::Extensions::Agentic::Attention::Spotlight::Helpers::Constants::MAX_TARGETS', 2)
+      register(label: 'a')
+      register(label: 'b')
+      result = register(label: 'c')
+      expect(result[:registered]).to be false
+      expect(result[:reason]).to eq(:max_targets_reached)
+    end
+
+    it 'returns the label and domain' do
+      result = register(label: 'my task', domain: :health)
+      expect(result[:label]).to eq('my task')
+      expect(result[:domain]).to eq(:health)
+    end
+  end
+
+  describe '#focus' do
+    it 'focuses on a registered target' do
+      id = register[:target_id]
+      result = engine.focus(target_id: id)
+      expect(result[:focused]).to be true
+      expect(result[:mode]).to eq(:focused)
+    end
+
+    it 'marks the target as in_spotlight' do
+      id = register[:target_id]
+      engine.focus(target_id: id)
+      expect(engine.targets[id].in_spotlight).to be true
+    end
+
+    it 'returns not_found for unknown target_id' do
+      result = engine.focus(target_id: 'nonexistent')
+      expect(result[:focused]).to be false
+      expect(result[:reason]).to eq(:not_found)
+    end
+
+    it 'sets last_attended_at on the target' do
+      id = register[:target_id]
+      engine.focus(target_id: id)
+      expect(engine.targets[id].last_attended_at).to be_a(Time)
+    end
+
+    it 'clears previous spotlight focus when refocusing' do
+      id1 = register(label: 'first')[:target_id]
+      id2 = register(label: 'second')[:target_id]
+      engine.focus(target_id: id1)
+      engine.focus(target_id: id2)
+      expect(engine.targets[id1].in_spotlight).to be false
+    end
+  end
+
+  describe '#broaden' do
+    it 'increases spotlight breadth' do
+      initial = engine.spotlight.breadth
+      engine.broaden
+      expect(engine.spotlight.breadth).to be > initial
+    end
+
+    it 'returns broadened true with zoom_level' do
+      result = engine.broaden
+      expect(result[:broadened]).to be true
+      expect(result).to have_key(:zoom_level)
+    end
+  end
+
+  describe '#narrow' do
+    it 'decreases spotlight breadth' do
+      engine.broaden
+      before = engine.spotlight.breadth
+      engine.narrow
+      expect(engine.spotlight.breadth).to be < before
+    end
+
+    it 'returns narrowed true with zoom_level' do
+      result = engine.narrow
+      expect(result[:narrowed]).to be true
+      expect(result).to have_key(:zoom_level)
+    end
+  end
+
+  describe '#scan' do
+    it 'sets spotlight mode to scanning' do
+      3.times { |i| register(label: "task #{i}") }
+      engine.scan
+      expect(engine.spotlight.mode).to eq(:scanning)
+    end
+
+    it 'returns targets_swept count' do
+      3.times { |i| register(label: "task #{i}") }
+      result = engine.scan
+      expect(result[:targets_swept]).to eq(3)
+    end
+
+    it 'marks all targets as attended' do
+      ids = 3.times.map { |i| register(label: "task #{i}")[:target_id] }
+      engine.scan
+      ids.each do |id|
+        expect(engine.targets[id].last_attended_at).to be_a(Time)
+      end
+    end
+  end
+
+  describe '#check_peripheral' do
+    it 'detects salient targets outside spotlight' do
+      register(label: 'salient', salience: 0.6)
+      engine.check_peripheral
+      expect(engine.peripheral).not_to be_empty
+    end
+
+    it 'does not detect targets below threshold' do
+      register(label: 'low', salience: 0.1)
+      engine.check_peripheral
+      expect(engine.peripheral).to be_empty
+    end
+
+    it 'marks detected targets as in_periphery' do
+      id = register(label: 'salient', salience: 0.6)[:target_id]
+      engine.check_peripheral
+      expect(engine.targets[id].in_periphery).to be true
+    end
+
+    it 'respects MAX_PERIPHERAL limit' do
+      stub_const('Legion::Extensions::Agentic::Attention::Spotlight::Helpers::Constants::MAX_PERIPHERAL', 2)
+      5.times { |i| register(label: "t#{i}", salience: 0.8) }
+      result = engine.check_peripheral
+      expect(result[:detected]).to be <= 2
+    end
+  end
+
+  describe '#check_capture' do
+    it 'returns captured false when no compelling target exists' do
+      register(label: 'low', salience: 0.3)
+      result = engine.check_capture
+      expect(result[:captured]).to be false
+    end
+
+    it 'captures the most salient compelling target' do
+      register(label: 'high', salience: 0.9)
+      result = engine.check_capture
+      expect(result[:captured]).to be true
+      expect(result[:salience]).to eq(0.9)
+    end
+
+    it 'sets spotlight mode to captured' do
+      register(label: 'urgent', salience: 0.85)
+      engine.check_capture
+      expect(engine.spotlight.mode).to eq(:captured)
+    end
+
+    it 'increments capture_count on the captured target' do
+      id = register(label: 'urgent', salience: 0.85)[:target_id]
+      engine.check_capture
+      expect(engine.targets[id].capture_count).to eq(1)
+    end
+
+    it 'does not capture the currently spotlighted target' do
+      id = register(label: 'current', salience: 0.9)[:target_id]
+      engine.focus(target_id: id)
+      register(label: 'other', salience: 0.85)
+      result = engine.check_capture
+      expect(result[:target_id]).not_to eq(id)
+    end
+  end
+
+  describe '#release_focus' do
+    it 'returns released true' do
+      result = engine.release_focus
+      expect(result[:released]).to be true
+    end
+
+    it 'clears all spotlight flags' do
+      id = register(label: 'focused')[:target_id]
+      engine.focus(target_id: id)
+      engine.release_focus
+      expect(engine.targets[id].in_spotlight).to be false
+    end
+
+    it 'sets spotlight mode to idle' do
+      engine.release_focus
+      expect(engine.spotlight.mode).to eq(:idle)
+    end
+  end
+
+  describe '#targets_in_spotlight' do
+    it 'returns empty when no focus is set' do
+      register(label: 'x')
+      expect(engine.targets_in_spotlight).to be_empty
+    end
+
+    it 'returns the focused target' do
+      id = register(label: 'focused task')[:target_id]
+      engine.focus(target_id: id)
+      result = engine.targets_in_spotlight
+      ids = result.map(&:id)
+      expect(ids).to include(id)
+    end
+  end
+
+  describe '#most_salient' do
+    it 'returns targets ordered by salience descending' do
+      register(label: 'low', salience: 0.2)
+      register(label: 'high', salience: 0.9)
+      register(label: 'mid', salience: 0.5)
+      result = engine.most_salient(limit: 3)
+      expect(result.map(&:salience)).to eq([0.9, 0.5, 0.2])
+    end
+
+    it 'respects the limit parameter' do
+      5.times { |i| register(label: "t#{i}", salience: i * 0.1) }
+      expect(engine.most_salient(limit: 2).size).to eq(2)
+    end
+  end
+
+  describe '#spotlight_report' do
+    it 'includes spotlight, in_spotlight, in_periphery, most_salient, total_targets' do
+      register(label: 'x', salience: 0.6)
+      report = engine.spotlight_report
+      expect(report.keys).to include(:spotlight, :in_spotlight, :in_periphery, :most_salient, :total_targets)
+    end
+
+    it 'includes peripheral_count' do
+      register(label: 'p', salience: 0.6)
+      engine.check_peripheral
+      report = engine.spotlight_report
+      expect(report).to have_key(:peripheral_count)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with spotlight and target_count' do
+      h = engine.to_h
+      expect(h.keys).to include(:spotlight, :target_count, :peripheral_count, :spotlight_targets)
+    end
+
+    it 'reflects correct target_count' do
+      3.times { |i| register(label: "t#{i}") }
+      expect(engine.to_h[:target_count]).to eq(3)
+    end
+  end
+end