lex-agentic-attention 0.1.0

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

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Spotlight::Helpers::Spotlight do
+  subject(:spotlight) { described_class.new }
+
+  describe '#initialize' do
+    it 'starts with nil center_target_id' do
+      expect(spotlight.center_target_id).to be_nil
+    end
+
+    it 'starts with default intensity' do
+      expect(spotlight.intensity).to eq(0.5)
+    end
+
+    it 'starts with default breadth' do
+      expect(spotlight.breadth).to eq(0.5)
+    end
+
+    it 'starts in idle mode' do
+      expect(spotlight.mode).to eq(:idle)
+    end
+  end
+
+  describe '#focus_on!' do
+    it 'sets center_target_id' do
+      spotlight.focus_on!('abc-123')
+      expect(spotlight.center_target_id).to eq('abc-123')
+    end
+
+    it 'sets mode to :focused' do
+      spotlight.focus_on!('abc-123')
+      expect(spotlight.mode).to eq(:focused)
+    end
+
+    it 'increases intensity by INTENSITY_GAIN' do
+      initial = spotlight.intensity
+      spotlight.focus_on!('abc-123')
+      expect(spotlight.intensity).to be > initial
+    end
+
+    it 'does not exceed 1.0 intensity when already high' do
+      spotlight.instance_variable_set(:@intensity, 0.95)
+      spotlight.focus_on!('abc-123')
+      expect(spotlight.intensity).to eq(1.0)
+    end
+  end
+
+  describe '#broaden!' do
+    it 'increases breadth by ZOOM_STEP' do
+      initial = spotlight.breadth
+      spotlight.broaden!
+      expect(spotlight.breadth).to be_within(0.001).of(initial + 0.1)
+    end
+
+    it 'decreases intensity by INTENSITY_LOSS' do
+      initial = spotlight.intensity
+      spotlight.broaden!
+      expect(spotlight.intensity).to be_within(0.001).of(initial - 0.1)
+    end
+
+    it 'does not exceed 1.0 breadth' do
+      spotlight.instance_variable_set(:@breadth, 0.95)
+      spotlight.broaden!
+      expect(spotlight.breadth).to eq(1.0)
+    end
+
+    it 'does not go below 0.0 intensity' do
+      spotlight.instance_variable_set(:@intensity, 0.05)
+      spotlight.broaden!
+      expect(spotlight.intensity).to eq(0.0)
+    end
+
+    it 'transitions focused mode to scanning' do
+      spotlight.focus_on!('abc-123')
+      spotlight.broaden!
+      expect(spotlight.mode).to eq(:scanning)
+    end
+  end
+
+  describe '#narrow!' do
+    it 'decreases breadth by ZOOM_STEP' do
+      spotlight.instance_variable_set(:@breadth, 0.5)
+      spotlight.narrow!
+      expect(spotlight.breadth).to be_within(0.001).of(0.4)
+    end
+
+    it 'increases intensity by INTENSITY_GAIN' do
+      initial = spotlight.intensity
+      spotlight.narrow!
+      expect(spotlight.intensity).to be > initial
+    end
+
+    it 'does not go below 0.0 breadth' do
+      spotlight.instance_variable_set(:@breadth, 0.05)
+      spotlight.narrow!
+      expect(spotlight.breadth).to eq(0.0)
+    end
+  end
+
+  describe '#capture!' do
+    it 'sets center_target_id to the captured target' do
+      spotlight.capture!('urgent-task')
+      expect(spotlight.center_target_id).to eq('urgent-task')
+    end
+
+    it 'sets mode to :captured' do
+      spotlight.capture!('urgent-task')
+      expect(spotlight.mode).to eq(:captured)
+    end
+
+    it 'sets intensity to 1.0' do
+      spotlight.capture!('urgent-task')
+      expect(spotlight.intensity).to eq(1.0)
+    end
+  end
+
+  describe '#release!' do
+    it 'clears center_target_id' do
+      spotlight.focus_on!('some-target')
+      spotlight.release!
+      expect(spotlight.center_target_id).to be_nil
+    end
+
+    it 'resets mode to :idle' do
+      spotlight.focus_on!('some-target')
+      spotlight.release!
+      expect(spotlight.mode).to eq(:idle)
+    end
+
+    it 'resets intensity to default' do
+      spotlight.focus_on!('some-target')
+      spotlight.release!
+      expect(spotlight.intensity).to eq(0.5)
+    end
+
+    it 'resets breadth to default' do
+      spotlight.broaden!
+      spotlight.release!
+      expect(spotlight.breadth).to eq(0.5)
+    end
+  end
+
+  describe '#zoom_level' do
+    it 'returns :laser for breadth 0.0' do
+      spotlight.instance_variable_set(:@breadth, 0.0)
+      expect(spotlight.zoom_level).to eq(:laser)
+    end
+
+    it 'returns :moderate for default breadth 0.5' do
+      expect(spotlight.zoom_level).to eq(:moderate)
+    end
+
+    it 'returns :diffuse for breadth 1.0' do
+      spotlight.instance_variable_set(:@breadth, 1.0)
+      expect(spotlight.zoom_level).to eq(:diffuse)
+    end
+
+    it 'returns :narrow for breadth 0.3' do
+      spotlight.instance_variable_set(:@breadth, 0.3)
+      expect(spotlight.zoom_level).to eq(:narrow)
+    end
+
+    it 'returns :wide for breadth 0.7' do
+      spotlight.instance_variable_set(:@breadth, 0.7)
+      expect(spotlight.zoom_level).to eq(:wide)
+    end
+  end
+
+  describe '#intensity_label' do
+    it 'returns :blazing for intensity 0.9' do
+      spotlight.instance_variable_set(:@intensity, 0.9)
+      expect(spotlight.intensity_label).to eq(:blazing)
+    end
+
+    it 'returns :dark for intensity 0.1' do
+      spotlight.instance_variable_set(:@intensity, 0.1)
+      expect(spotlight.intensity_label).to eq(:dark)
+    end
+
+    it 'returns :moderate for intensity 0.5' do
+      expect(spotlight.intensity_label).to eq(:moderate)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns all expected keys' do
+      h = spotlight.to_h
+      expect(h.keys).to include(:center_target_id, :intensity, :breadth, :mode, :zoom_level, :intensity_label)
+    end
+
+    it 'includes current mode' do
+      spotlight.focus_on!('x')
+      expect(spotlight.to_h[:mode]).to eq(:focused)
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/spotlight/runners/attention_spotlight_spec.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/attention/spotlight/client'
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Spotlight::Runners::AttentionSpotlight do
+  let(:client) { Legion::Extensions::Agentic::Attention::Spotlight::Client.new }
+
+  def reg(label: 'task', domain: :work, salience: 0.5, relevance: 0.5)
+    client.register_target(label: label, domain: domain, salience: salience, relevance: relevance)
+  end
+
+  describe '#register_target' do
+    it 'returns success true on valid registration' do
+      result = reg
+      expect(result[:success]).to be true
+    end
+
+    it 'returns a target_id uuid' do
+      result = reg
+      expect(result[:target_id]).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'includes label in result' do
+      result = reg(label: 'my task')
+      expect(result[:label]).to eq('my task')
+    end
+
+    it 'includes domain in result' do
+      result = reg(domain: :health)
+      expect(result[:domain]).to eq(:health)
+    end
+  end
+
+  describe '#focus_spotlight' do
+    it 'returns success true when focusing on a known target' do
+      id = reg[:target_id]
+      result = client.focus_spotlight(target_id: id)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns focused true' do
+      id = reg[:target_id]
+      result = client.focus_spotlight(target_id: id)
+      expect(result[:focused]).to be true
+    end
+
+    it 'returns success false for unknown target' do
+      result = client.focus_spotlight(target_id: 'unknown-id')
+      expect(result[:success]).to be false
+    end
+
+    it 'returns not_found reason for unknown target' do
+      result = client.focus_spotlight(target_id: 'unknown-id')
+      expect(result[:reason]).to eq(:not_found)
+    end
+
+    it 'sets spotlight mode to focused' do
+      id = reg[:target_id]
+      client.focus_spotlight(target_id: id)
+      result = client.spotlight_state
+      expect(result[:spotlight][:mode]).to eq(:focused)
+    end
+  end
+
+  describe '#broaden_spotlight' do
+    it 'returns success true' do
+      result = client.broaden_spotlight
+      expect(result[:success]).to be true
+    end
+
+    it 'returns broadened true' do
+      result = client.broaden_spotlight
+      expect(result[:broadened]).to be true
+    end
+
+    it 'increases breadth' do
+      initial = client.spotlight_state[:spotlight][:breadth]
+      client.broaden_spotlight
+      after = client.spotlight_state[:spotlight][:breadth]
+      expect(after).to be > initial
+    end
+  end
+
+  describe '#narrow_spotlight' do
+    it 'returns success true' do
+      result = client.narrow_spotlight
+      expect(result[:success]).to be true
+    end
+
+    it 'returns narrowed true' do
+      result = client.narrow_spotlight
+      expect(result[:narrowed]).to be true
+    end
+
+    it 'decreases breadth when already broadened' do
+      client.broaden_spotlight
+      before = client.spotlight_state[:spotlight][:breadth]
+      client.narrow_spotlight
+      after = client.spotlight_state[:spotlight][:breadth]
+      expect(after).to be < before
+    end
+  end
+
+  describe '#scan_targets' do
+    it 'returns success true' do
+      expect(client.scan_targets[:success]).to be true
+    end
+
+    it 'returns scanning true' do
+      expect(client.scan_targets[:scanning]).to be true
+    end
+
+    it 'returns correct targets_swept count' do
+      3.times { |i| reg(label: "t#{i}") }
+      result = client.scan_targets
+      expect(result[:targets_swept]).to eq(3)
+    end
+  end
+
+  describe '#check_peripheral' do
+    it 'returns success true' do
+      expect(client.check_peripheral[:success]).to be true
+    end
+
+    it 'returns detected count' do
+      reg(label: 'salient', salience: 0.7)
+      result = client.check_peripheral
+      expect(result[:detected]).to be >= 1
+    end
+
+    it 'detects no targets when salience is below threshold' do
+      reg(label: 'low', salience: 0.1)
+      result = client.check_peripheral
+      expect(result[:detected]).to eq(0)
+    end
+
+    it 'includes peripheral_ids array' do
+      result = client.check_peripheral
+      expect(result[:peripheral_ids]).to be_an(Array)
+    end
+  end
+
+  describe '#check_capture' do
+    it 'returns success true' do
+      expect(client.check_capture[:success]).to be true
+    end
+
+    it 'returns captured false when no compelling target' do
+      reg(label: 'low', salience: 0.3)
+      expect(client.check_capture[:captured]).to be false
+    end
+
+    it 'captures a compelling target' do
+      reg(label: 'urgent', salience: 0.9)
+      result = client.check_capture
+      expect(result[:captured]).to be true
+    end
+
+    it 'returns target_id of captured target' do
+      id = reg(label: 'urgent', salience: 0.9)[:target_id]
+      result = client.check_capture
+      expect(result[:target_id]).to eq(id)
+    end
+  end
+
+  describe '#release_focus' do
+    it 'returns success true' do
+      expect(client.release_focus[:success]).to be true
+    end
+
+    it 'returns released true' do
+      expect(client.release_focus[:released]).to be true
+    end
+
+    it 'sets mode back to idle' do
+      id = reg[:target_id]
+      client.focus_spotlight(target_id: id)
+      client.release_focus
+      expect(client.spotlight_state[:spotlight][:mode]).to eq(:idle)
+    end
+  end
+
+  describe '#spotlight_report' do
+    it 'returns success true' do
+      expect(client.spotlight_report[:success]).to be true
+    end
+
+    it 'includes total_targets count' do
+      3.times { |i| reg(label: "t#{i}") }
+      expect(client.spotlight_report[:total_targets]).to eq(3)
+    end
+
+    it 'includes spotlight hash' do
+      expect(client.spotlight_report[:spotlight]).to be_a(Hash)
+    end
+
+    it 'includes in_spotlight array' do
+      expect(client.spotlight_report[:in_spotlight]).to be_an(Array)
+    end
+
+    it 'includes most_salient array' do
+      expect(client.spotlight_report[:most_salient]).to be_an(Array)
+    end
+  end
+
+  describe '#most_salient' do
+    it 'returns success true' do
+      expect(client.most_salient[:success]).to be true
+    end
+
+    it 'returns ordered targets by salience' do
+      reg(label: 'low', salience: 0.2)
+      reg(label: 'high', salience: 0.9)
+      result = client.most_salient(limit: 2)
+      saliences = result[:targets].map { |t| t[:salience] }
+      expect(saliences.first).to be > saliences.last
+    end
+
+    it 'respects limit parameter' do
+      5.times { |i| reg(label: "t#{i}") }
+      expect(client.most_salient(limit: 3)[:count]).to eq(3)
+    end
+
+    it 'defaults to limit 5' do
+      7.times { |i| reg(label: "t#{i}") }
+      expect(client.most_salient[:count]).to eq(5)
+    end
+  end
+
+  describe '#spotlight_state' do
+    it 'returns success true' do
+      expect(client.spotlight_state[:success]).to be true
+    end
+
+    it 'includes spotlight hash' do
+      expect(client.spotlight_state[:spotlight]).to be_a(Hash)
+    end
+
+    it 'includes target_count' do
+      3.times { |i| reg(label: "t#{i}") }
+      expect(client.spotlight_state[:target_count]).to eq(3)
+    end
+
+    it 'reflects changes after focus' do
+      id = reg[:target_id]
+      client.focus_spotlight(target_id: id)
+      state = client.spotlight_state
+      expect(state[:spotlight][:center_target_id]).to eq(id)
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Subliminal::Client do
+  subject(:client) { described_class.new }
+
+  it 'responds to runner methods' do
+    expect(client).to respond_to(:create_subliminal_trace, :process_influences, :subliminal_status)
+  end
+
+  it 'runs a full subliminal lifecycle' do
+    result = client.create_subliminal_trace(content: 'danger signal', domain: :security)
+    trace_id = result[:trace][:id]
+
+    client.boost_trace(trace_id: trace_id)
+    client.process_influences
+    client.decay_all
+
+    status = client.subliminal_status
+    expect(status[:total_traces]).to be >= 1
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Subliminal::Helpers::InfluenceEvent do
+  subject(:event) do
+    described_class.new(trace_id: 'abc-123', target: :attention, magnitude: 0.08, domain: :security)
+  end
+
+  describe '#initialize' do
+    it 'assigns a UUID id' do
+      expect(event.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores trace_id' do
+      expect(event.trace_id).to eq('abc-123')
+    end
+
+    it 'stores target' do
+      expect(event.target).to eq(:attention)
+    end
+
+    it 'stores magnitude' do
+      expect(event.magnitude).to eq(0.08)
+    end
+
+    it 'stores domain' do
+      expect(event.domain).to eq(:security)
+    end
+  end
+
+  describe '#significant?' do
+    it 'is true for magnitude >= 0.05' do
+      expect(event.significant?).to be true
+    end
+
+    it 'is false for small magnitude' do
+      small = described_class.new(trace_id: 'x', target: :emotion, magnitude: 0.03)
+      expect(small.significant?).to be false
+    end
+  end
+
+  describe '#subtle?' do
+    it 'is true for small positive magnitude' do
+      small = described_class.new(trace_id: 'x', target: :emotion, magnitude: 0.03)
+      expect(small.subtle?).to be true
+    end
+
+    it 'is false for significant magnitude' do
+      expect(event.subtle?).to be false
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all fields' do
+      hash = event.to_h
+      expect(hash).to include(:id, :trace_id, :target, :magnitude, :domain, :created_at)
+    end
+  end
+end

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

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Subliminal::Helpers::SubliminalEngine do
+  subject(:engine) { described_class.new }
+
+  describe '#create_trace' do
+    it 'creates and stores a trace' do
+      trace = engine.create_trace(content: 'faint memory')
+      expect(trace.content).to eq('faint memory')
+    end
+  end
+
+  describe '#boost_trace' do
+    it 'boosts activation' do
+      trace = engine.create_trace(content: 'test')
+      original = trace.activation
+      engine.boost_trace(trace_id: trace.id)
+      expect(trace.activation).to be > original
+    end
+
+    it 'returns nil for unknown trace' do
+      expect(engine.boost_trace(trace_id: 'bad')).to be_nil
+    end
+  end
+
+  describe '#process_influences!' do
+    it 'generates influence events from active traces' do
+      engine.create_trace(content: 'a', activation: 0.3)
+      result = engine.process_influences!
+      expect(result[:influences_generated]).to be >= 1
+    end
+
+    it 'returns empty when no active traces' do
+      result = engine.process_influences!
+      expect(result[:influences_generated]).to eq(0)
+    end
+  end
+
+  describe '#decay_all!' do
+    it 'decays all traces' do
+      trace = engine.create_trace(content: 'test')
+      original = trace.activation
+      engine.decay_all!
+      expect(trace.activation).to be < original
+    end
+  end
+
+  describe '#active_traces' do
+    it 'returns non-extinct traces' do
+      engine.create_trace(content: 'active', activation: 0.2)
+      expect(engine.active_traces.size).to eq(1)
+    end
+  end
+
+  describe '#near_threshold_traces' do
+    it 'returns traces near conscious threshold' do
+      engine.create_trace(content: 'near', activation: 0.35)
+      engine.create_trace(content: 'far', activation: 0.1)
+      expect(engine.near_threshold_traces.size).to eq(1)
+    end
+  end
+
+  describe '#potent_traces' do
+    it 'returns traces with activation >= 0.2' do
+      engine.create_trace(content: 'potent', activation: 0.25)
+      engine.create_trace(content: 'weak', activation: 0.05)
+      expect(engine.potent_traces.size).to eq(1)
+    end
+  end
+
+  describe '#traces_by_domain' do
+    it 'filters by domain' do
+      engine.create_trace(content: 'a', domain: :security)
+      engine.create_trace(content: 'b', domain: :memory)
+      expect(engine.traces_by_domain(domain: :security).size).to eq(1)
+    end
+  end
+
+  describe '#traces_by_type' do
+    it 'filters by trace type' do
+      engine.create_trace(content: 'a', trace_type: :emotional)
+      engine.create_trace(content: 'b', trace_type: :procedural)
+      expect(engine.traces_by_type(trace_type: :emotional).size).to eq(1)
+    end
+  end
+
+  describe '#traces_by_target' do
+    it 'filters by influence target' do
+      engine.create_trace(content: 'a', influence_target: :emotion)
+      engine.create_trace(content: 'b', influence_target: :decision)
+      expect(engine.traces_by_target(target: :emotion).size).to eq(1)
+    end
+  end
+
+  describe '#influence_on' do
+    it 'returns 0.0 with no influences' do
+      expect(engine.influence_on(target: :attention)).to eq(0.0)
+    end
+
+    it 'returns accumulated influence after processing' do
+      engine.create_trace(content: 'a', activation: 0.3, influence_target: :attention)
+      engine.process_influences!
+      expect(engine.influence_on(target: :attention)).to be > 0.0
+    end
+  end
+
+  describe '#domain_saturation' do
+    it 'returns 0.0 for empty domain' do
+      expect(engine.domain_saturation(domain: :security)).to eq(0.0)
+    end
+
+    it 'returns positive for populated domain' do
+      engine.create_trace(content: 'a', domain: :security, activation: 0.3)
+      expect(engine.domain_saturation(domain: :security)).to be > 0.0
+    end
+  end
+
+  describe '#overall_subliminal_load' do
+    it 'returns 0.0 with no traces' do
+      expect(engine.overall_subliminal_load).to eq(0.0)
+    end
+
+    it 'returns positive with active traces' do
+      engine.create_trace(content: 'a', activation: 0.3)
+      expect(engine.overall_subliminal_load).to be > 0.0
+    end
+  end
+
+  describe '#strongest_traces' do
+    it 'returns sorted by activation descending' do
+      engine.create_trace(content: 'weak', activation: 0.1)
+      strong = engine.create_trace(content: 'strong', activation: 0.35)
+      expect(engine.strongest_traces(limit: 1).first.id).to eq(strong.id)
+    end
+  end
+
+  describe '#breached_traces' do
+    it 'returns empty when all below threshold' do
+      engine.create_trace(content: 'below', activation: 0.3)
+      expect(engine.breached_traces).to be_empty
+    end
+  end
+
+  describe '#subliminal_report' do
+    it 'includes all report fields' do
+      report = engine.subliminal_report
+      expect(report).to include(
+        :total_traces, :active_count, :near_threshold, :potent_count,
+        :total_influences, :subliminal_load, :saturation_label,
+        :breached_count, :strongest
+      )
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes summary fields' do
+      hash = engine.to_h
+      expect(hash).to include(:total_traces, :active, :subliminal_load, :total_influences)
+    end
+  end
+end