lex-agentic-attention 0.1.0

data/spec/legion/extensions/agentic/attention/lens/helpers/lens_stack_spec.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Lens::Helpers::LensStack do
+  let(:lens_class) { Legion::Extensions::Agentic::Attention::Lens::Helpers::Lens }
+  let(:stack)      { described_class.new }
+
+  let(:magnifying)  { lens_class.new(lens_type: :magnifying, magnification: 2.0, clarity: 1.0, distortion: 0.1) }
+  let(:wide_angle)  { lens_class.new(lens_type: :wide_angle, magnification: 0.5, clarity: 0.9, distortion: 0.2) }
+  let(:polarized)   { lens_class.new(lens_type: :polarized,  magnification: 1.0, clarity: 0.8, distortion: 0.0) }
+
+  describe '#push_lens' do
+    it 'adds a lens to the stack' do
+      stack.push_lens(magnifying)
+      expect(stack.size).to eq(1)
+    end
+
+    it 'returns self for chaining' do
+      expect(stack.push_lens(magnifying)).to eq(stack)
+    end
+
+    it 'raises ArgumentError for non-Lens objects' do
+      expect { stack.push_lens('not_a_lens') }.to raise_error(ArgumentError, /expected a Lens/)
+    end
+
+    it 'raises ArgumentError when stack is full' do
+      lens_count = Legion::Extensions::Agentic::Attention::Lens::Helpers::Constants::MAX_LENSES
+      lens_count.times { stack.push_lens(lens_class.new(lens_type: :magnifying)) }
+      expect { stack.push_lens(lens_class.new(lens_type: :wide_angle)) }.to raise_error(ArgumentError, /stack is full/)
+    end
+  end
+
+  describe '#pop_lens' do
+    it 'removes and returns the last lens' do
+      stack.push_lens(magnifying)
+      stack.push_lens(wide_angle)
+      popped = stack.pop_lens
+      expect(popped).to eq(wide_angle)
+      expect(stack.size).to eq(1)
+    end
+
+    it 'returns nil when stack is empty' do
+      expect(stack.pop_lens).to be_nil
+    end
+  end
+
+  describe '#empty?' do
+    it 'returns true for new stack' do
+      expect(stack.empty?).to be true
+    end
+
+    it 'returns false after pushing a lens' do
+      stack.push_lens(magnifying)
+      expect(stack.empty?).to be false
+    end
+  end
+
+  describe '#combined_magnification' do
+    it 'returns 1.0 for empty stack' do
+      expect(stack.combined_magnification).to eq(1.0)
+    end
+
+    it 'applies sub-linear compounding for single lens' do
+      stack.push_lens(magnifying)
+      expected = (2.0**Legion::Extensions::Agentic::Attention::Lens::Helpers::Constants::STACK_MAGNIFICATION_EXPONENT)
+      expect(stack.combined_magnification).to be_within(0.001).of(expected)
+    end
+
+    it 'compounds magnification for multiple lenses' do
+      stack.push_lens(magnifying)
+      stack.push_lens(wide_angle)
+      expect(stack.combined_magnification).to be > 0.0
+    end
+  end
+
+  describe '#combined_distortion' do
+    it 'returns 0.0 for empty stack' do
+      expect(stack.combined_distortion).to eq(0.0)
+    end
+
+    it 'returns lens distortion for single lens' do
+      stack.push_lens(polarized)
+      expect(stack.combined_distortion).to eq(0.0)
+    end
+
+    it 'blends toward worst distortion for multiple lenses' do
+      stack.push_lens(magnifying)  # 0.1 distortion
+      stack.push_lens(wide_angle)  # 0.2 distortion
+      expect(stack.combined_distortion).to be_between(0.1, 0.2)
+    end
+
+    it 'is clamped between 0 and 1' do
+      stack.push_lens(lens_class.new(lens_type: :fish_eye))
+      expect(stack.combined_distortion).to be_between(0.0, 1.0)
+    end
+  end
+
+  describe '#stack_clarity' do
+    it 'returns 1.0 for empty stack' do
+      expect(stack.stack_clarity).to eq(1.0)
+    end
+
+    it 'returns lens clarity for single lens' do
+      stack.push_lens(polarized)
+      expect(stack.stack_clarity).to be <= polarized.clarity
+    end
+
+    it 'decays clarity with each additional lens' do
+      stack.push_lens(magnifying)
+      single_clarity = stack.stack_clarity
+
+      stack.push_lens(wide_angle)
+      expect(stack.stack_clarity).to be < single_clarity
+    end
+
+    it 'is clamped between 0 and 1' do
+      3.times { stack.push_lens(lens_class.new(lens_type: :magnifying, clarity: 0.5)) }
+      expect(stack.stack_clarity).to be_between(0.0, 1.0)
+    end
+  end
+
+  describe '#view_through' do
+    it 'returns original content when stack is empty' do
+      expect(stack.view_through(0.6)).to eq(0.6)
+    end
+
+    it 'returns a result hash with expected keys' do
+      stack.push_lens(magnifying)
+      result = stack.view_through(0.5)
+      expect(result.keys).to include(:original, :perceived, :combined_magnification,
+                                     :combined_distortion, :stack_clarity, :lens_count, :focus_active)
+    end
+
+    it 'preserves neutral value (0.5) through neutral magnification' do
+      lens = lens_class.new(lens_type: :polarized, magnification: 1.0, distortion: 0.0, clarity: 1.0)
+      stack.push_lens(lens)
+      result = stack.view_through(0.5)
+      expect(result[:perceived]).to be_within(0.05).of(0.5)
+    end
+
+    it 'magnifies values away from center' do
+      stack.push_lens(magnifying)
+      result = stack.view_through(0.8)
+      expect(result[:perceived]).to be > 0.5
+    end
+
+    it 'accepts hash content with :value key' do
+      stack.push_lens(magnifying)
+      result = stack.view_through({ value: 0.7 })
+      expect(result[:original]).to be_within(0.001).of(0.7)
+    end
+
+    it 'reports focus_active as true when a lens is focused' do
+      magnifying.focus!('target')
+      stack.push_lens(magnifying)
+      result = stack.view_through(0.5)
+      expect(result[:focus_active]).to be true
+    end
+
+    it 'reports focus_active as false when no lens is focused' do
+      stack.push_lens(magnifying)
+      result = stack.view_through(0.5)
+      expect(result[:focus_active]).to be false
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes stack summary fields' do
+      stack.push_lens(magnifying)
+      h = stack.to_h
+      expect(h.keys).to include(:lens_count, :combined_magnification, :combined_distortion,
+                                :stack_clarity, :lenses)
+    end
+
+    it 'includes lens details' do
+      stack.push_lens(magnifying)
+      expect(stack.to_h[:lenses].size).to eq(1)
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/lens/runners/cognitive_lens_spec.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/attention/lens/client'
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Lens::Runners::CognitiveLens do
+  let(:client) { Legion::Extensions::Agentic::Attention::Lens::Client.new }
+  let(:engine) { Legion::Extensions::Agentic::Attention::Lens::Helpers::LensEngine.new }
+
+  describe '#create_lens' do
+    it 'returns success: true' do
+      result = client.create_lens(lens_type: :magnifying)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns lens hash' do
+      result = client.create_lens(lens_type: :magnifying)
+      expect(result[:lens]).to include(:id, :lens_type, :magnification)
+    end
+
+    it 'creates all supported lens types' do
+      lens_types = Legion::Extensions::Agentic::Attention::Lens::Helpers::Constants::LENS_TYPES
+      lens_types.each do |lt|
+        result = client.create_lens(lens_type: lt)
+        expect(result[:success]).to be true
+      end
+    end
+
+    it 'returns success: false for invalid lens type' do
+      result = client.create_lens(lens_type: :quantum)
+      expect(result[:success]).to be false
+      expect(result[:error]).to match(/unknown lens_type/)
+    end
+
+    it 'forwards custom magnification' do
+      result = client.create_lens(lens_type: :magnifying, magnification: 3.0)
+      expect(result[:lens][:magnification]).to be_within(0.001).of(3.0)
+    end
+
+    it 'forwards custom clarity' do
+      result = client.create_lens(lens_type: :magnifying, clarity: 0.7)
+      expect(result[:lens][:clarity]).to be_within(0.001).of(0.7)
+    end
+
+    it 'accepts injected engine' do
+      result = client.create_lens(lens_type: :wide_angle, engine: engine)
+      expect(result[:success]).to be true
+      expect(engine.lenses.size).to eq(1)
+    end
+  end
+
+  describe '#stack_lenses' do
+    let(:lens1_result) { client.create_lens(lens_type: :magnifying) }
+    let(:lens2_result) { client.create_lens(lens_type: :wide_angle) }
+    let(:lens1_id) { lens1_result[:lens][:id] }
+    let(:lens2_id) { lens2_result[:lens][:id] }
+
+    it 'returns success: true' do
+      result = client.stack_lenses(lens_ids: [lens1_id, lens2_id])
+      expect(result[:success]).to be true
+    end
+
+    it 'returns a stack_id' do
+      result = client.stack_lenses(lens_ids: [lens1_id])
+      expect(result[:stack_id]).to be_a(String)
+    end
+
+    it 'returns stack details' do
+      result = client.stack_lenses(lens_ids: [lens1_id])
+      expect(result[:stack]).to include(:lens_count, :combined_magnification)
+    end
+
+    it 'returns success: false for unknown lens ids' do
+      result = client.stack_lenses(lens_ids: ['unknown'])
+      expect(result[:success]).to be false
+    end
+
+    it 'returns success: false when lens_ids is not an array' do
+      result = client.stack_lenses(lens_ids: 'bad')
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#view_through_stack' do
+    let(:lens_id) do
+      client.create_lens(lens_type: :magnifying)[:lens][:id]
+    end
+    let(:stack_id) do
+      client.stack_lenses(lens_ids: [lens_id])[:stack_id]
+    end
+
+    it 'returns success: true' do
+      result = client.view_through_stack(stack_id: stack_id, content: 0.6)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns perceived value' do
+      result = client.view_through_stack(stack_id: stack_id, content: 0.6)
+      expect(result[:perceived]).to be_between(0.0, 1.0)
+    end
+
+    it 'returns success: false for unknown stack_id' do
+      result = client.view_through_stack(stack_id: 'bad', content: 0.5)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#degrade_all' do
+    it 'returns success: true' do
+      result = client.degrade_all
+      expect(result[:success]).to be true
+    end
+
+    it 'reports number of degraded lenses' do
+      client.create_lens(lens_type: :magnifying)
+      client.create_lens(lens_type: :wide_angle)
+      result = client.degrade_all
+      expect(result[:degraded]).to eq(2)
+    end
+
+    it 'accepts custom rate' do
+      result = client.degrade_all(rate: 0.1)
+      expect(result[:rate]).to eq(0.1)
+    end
+  end
+
+  describe '#lens_report' do
+    it 'returns success: true' do
+      result = client.lens_report
+      expect(result[:success]).to be true
+    end
+
+    it 'includes lens_count' do
+      result = client.lens_report
+      expect(result).to have_key(:lens_count)
+    end
+
+    it 'counts created lenses' do
+      client.create_lens(lens_type: :magnifying)
+      client.create_lens(lens_type: :polarized)
+      result = client.lens_report
+      expect(result[:lens_count]).to eq(2)
+    end
+  end
+
+  describe '#clearest_lenses' do
+    it 'returns success: true' do
+      result = client.clearest_lenses
+      expect(result[:success]).to be true
+    end
+
+    it 'returns lenses array' do
+      client.create_lens(lens_type: :magnifying, clarity: 0.9)
+      result = client.clearest_lenses
+      expect(result[:lenses]).to be_an(Array)
+    end
+
+    it 'respects limit' do
+      5.times { client.create_lens(lens_type: :magnifying) }
+      result = client.clearest_lenses(limit: 2)
+      expect(result[:lenses].size).to be <= 2
+    end
+  end
+
+  describe '#most_distorted' do
+    it 'returns success: true' do
+      result = client.most_distorted
+      expect(result[:success]).to be true
+    end
+
+    it 'returns lenses array' do
+      client.create_lens(lens_type: :fish_eye)
+      result = client.most_distorted
+      expect(result[:lenses]).to be_an(Array)
+    end
+
+    it 'respects limit' do
+      5.times { client.create_lens(lens_type: :fish_eye) }
+      result = client.most_distorted(limit: 2)
+      expect(result[:lenses].size).to be <= 2
+    end
+  end
+end

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Lighthouse::Client do
+  subject(:client) { described_class.new }
+
+  describe '#initialize' do
+    it 'creates a client with default engine' do
+      expect(client).to be_a(described_class)
+    end
+
+    it 'accepts an injected engine' do
+      custom = Legion::Extensions::Agentic::Attention::Lighthouse::Helpers::LighthouseEngine.new
+      c = described_class.new(engine: custom)
+      expect(c).to be_a(described_class)
+    end
+  end
+
+  describe 'runner method delegation' do
+    it 'responds to light_beacon' do
+      expect(client).to respond_to(:light_beacon)
+    end
+
+    it 'responds to create_fog' do
+      expect(client).to respond_to(:create_fog)
+    end
+
+    it 'responds to sweep' do
+      expect(client).to respond_to(:sweep)
+    end
+
+    it 'responds to list_beacons' do
+      expect(client).to respond_to(:list_beacons)
+    end
+
+    it 'responds to navigation_status' do
+      expect(client).to respond_to(:navigation_status)
+    end
+  end
+
+  describe 'full lifecycle' do
+    it 'lights a beacon and checks status' do
+      result = client.light_beacon(beacon_type: :truth, domain: 'reasoning', content: 'seek truth')
+      expect(result[:success]).to be true
+
+      status = client.navigation_status
+      expect(status[:report][:total_beacons]).to eq(1)
+    end
+
+    it 'creates fog and sweeps with beacon' do
+      beacon_result = client.light_beacon(
+        beacon_type: :clarity, domain: 'planning', content: 'clear path', luminosity: 0.8
+      )
+      fog_result = client.create_fog(fog_type: :confusion, domain: 'planning', density: 0.7)
+
+      sweep_result = client.sweep(
+        beacon_id: beacon_result[:beacon][:id],
+        fog_id:    fog_result[:fog][:id]
+      )
+
+      expect(sweep_result[:success]).to be true
+      expect(sweep_result[:fog][:density]).to be < 0.7
+    end
+
+    it 'lists beacons after lighting multiple' do
+      client.light_beacon(beacon_type: :guidance, domain: 'alpha', content: 'first')
+      client.light_beacon(beacon_type: :hope, domain: 'beta', content: 'second')
+
+      result = client.list_beacons
+      expect(result[:count]).to eq(2)
+    end
+
+    it 'persists state across calls using its own engine' do
+      c1 = described_class.new
+      c1.light_beacon(beacon_type: :warning, domain: 'x', content: 'y')
+
+      c2 = described_class.new
+      expect(c1.navigation_status[:report][:total_beacons]).to eq(1)
+      expect(c2.navigation_status[:report][:total_beacons]).to eq(0)
+    end
+
+    it 'returns failure gracefully for invalid types' do
+      result = client.light_beacon(beacon_type: :phantom, domain: 'x', content: 'y')
+      expect(result[:success]).to be false
+      expect(result[:error]).to be_a(String)
+    end
+
+    it 'filters beacons by type' do
+      client.light_beacon(beacon_type: :truth, domain: 'a', content: 'first')
+      client.light_beacon(beacon_type: :hope, domain: 'b', content: 'second')
+      client.light_beacon(beacon_type: :truth, domain: 'c', content: 'third')
+
+      result = client.list_beacons(beacon_type: :truth)
+      expect(result[:count]).to eq(2)
+    end
+
+    it 'navigation_status shows fog metrics' do
+      client.create_fog(fog_type: :overwhelm, domain: 'x', density: 0.9)
+      report = client.navigation_status[:report]
+      expect(report[:total_fog_banks]).to eq(1)
+      expect(report[:avg_density]).to be > 0
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/lighthouse/helpers/beacon_spec.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Lighthouse::Helpers::Beacon do
+  subject(:beacon) { described_class.new(beacon_type: :truth, domain: 'reasoning', content: 'north star') }
+
+  describe '#initialize' do
+    it 'sets beacon_type as symbol' do
+      expect(beacon.beacon_type).to eq(:truth)
+    end
+
+    it 'sets domain as string' do
+      expect(beacon.domain).to eq('reasoning')
+    end
+
+    it 'sets content as string' do
+      expect(beacon.content).to eq('north star')
+    end
+
+    it 'defaults luminosity to 0.7' do
+      expect(beacon.luminosity).to be_within(0.001).of(0.7)
+    end
+
+    it 'defaults sweep_angle to 0.0' do
+      expect(beacon.sweep_angle).to be_within(0.001).of(0.0)
+    end
+
+    it 'assigns a UUID id' do
+      expect(beacon.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets lit_at timestamp' do
+      expect(beacon.lit_at).to be_a(Time)
+    end
+
+    it 'clamps luminosity to [0, 1]' do
+      b = described_class.new(beacon_type: :clarity, domain: 'x', content: 'y', luminosity: 2.0)
+      expect(b.luminosity).to eq(1.0)
+    end
+
+    it 'clamps sweep_angle to [0, 360]' do
+      b = described_class.new(beacon_type: :hope, domain: 'x', content: 'y', sweep_angle: 400.0)
+      expect(b.sweep_angle).to eq(360.0)
+    end
+
+    it 'raises for unknown beacon_type' do
+      expect do
+        described_class.new(beacon_type: :mirage, domain: 'x', content: 'y')
+      end.to raise_error(ArgumentError, /unknown beacon_type/)
+    end
+
+    it 'accepts all valid beacon types' do
+      Legion::Extensions::Agentic::Attention::Lighthouse::Helpers::Constants::BEACON_TYPES.each do |type|
+        expect do
+          described_class.new(beacon_type: type, domain: 'test', content: 'test')
+        end.not_to raise_error
+      end
+    end
+  end
+
+  describe '#brighten!' do
+    it 'increases luminosity by default rate' do
+      beacon.luminosity = 0.5
+      beacon.brighten!
+      expect(beacon.luminosity).to be_within(0.001).of(0.6)
+    end
+
+    it 'accepts custom rate' do
+      beacon.luminosity = 0.5
+      beacon.brighten!(rate: 0.2)
+      expect(beacon.luminosity).to be_within(0.001).of(0.7)
+    end
+
+    it 'clamps at 1.0' do
+      beacon.luminosity = 0.95
+      beacon.brighten!(rate: 0.1)
+      expect(beacon.luminosity).to eq(1.0)
+    end
+
+    it 'returns self for chaining' do
+      expect(beacon.brighten!).to eq(beacon)
+    end
+  end
+
+  describe '#dim!' do
+    it 'decreases luminosity by default rate' do
+      beacon.luminosity = 0.5
+      beacon.dim!
+      expect(beacon.luminosity).to be_within(0.001).of(0.4)
+    end
+
+    it 'accepts custom rate' do
+      beacon.luminosity = 0.5
+      beacon.dim!(rate: 0.3)
+      expect(beacon.luminosity).to be_within(0.001).of(0.2)
+    end
+
+    it 'clamps at 0.0' do
+      beacon.luminosity = 0.05
+      beacon.dim!(rate: 0.1)
+      expect(beacon.luminosity).to eq(0.0)
+    end
+
+    it 'returns self for chaining' do
+      expect(beacon.dim!).to eq(beacon)
+    end
+  end
+
+  describe '#extinguished?' do
+    it 'returns false when luminosity > 0' do
+      beacon.luminosity = 0.5
+      expect(beacon.extinguished?).to be false
+    end
+
+    it 'returns true when luminosity is 0' do
+      beacon.luminosity = 0.0
+      expect(beacon.extinguished?).to be true
+    end
+  end
+
+  describe '#blazing?' do
+    it 'returns false for moderate luminosity' do
+      beacon.luminosity = 0.5
+      expect(beacon.blazing?).to be false
+    end
+
+    it 'returns true when luminosity >= 0.9' do
+      beacon.luminosity = 0.9
+      expect(beacon.blazing?).to be true
+    end
+  end
+
+  describe '#luminosity_label' do
+    it 'returns a symbol' do
+      expect(beacon.luminosity_label).to be_a(Symbol)
+    end
+
+    it 'returns :blazing for luminosity 1.0' do
+      beacon.luminosity = 1.0
+      expect(beacon.luminosity_label).to eq(:blazing)
+    end
+
+    it 'returns :dark for luminosity 0.0' do
+      beacon.luminosity = 0.0
+      expect(beacon.luminosity_label).to eq(:dark)
+    end
+
+    it 'returns :steady for mid-range luminosity' do
+      beacon.luminosity = 0.6
+      expect(beacon.luminosity_label).to eq(:steady)
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes expected keys' do
+      h = beacon.to_h
+      %i[id beacon_type domain content luminosity sweep_angle
+         luminosity_label extinguished blazing lit_at].each do |k|
+        expect(h).to have_key(k)
+      end
+    end
+
+    it 'beacon_type matches' do
+      expect(beacon.to_h[:beacon_type]).to eq(:truth)
+    end
+
+    it 'extinguished is boolean' do
+      expect(beacon.to_h[:extinguished]).to be(false).or be(true)
+    end
+  end
+end