lex-agentic-attention 0.1.0

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/attention/lens/client'
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Lens::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to runner methods' do
+    expect(client).to respond_to(:create_lens)
+    expect(client).to respond_to(:stack_lenses)
+    expect(client).to respond_to(:view_through_stack)
+    expect(client).to respond_to(:degrade_all)
+    expect(client).to respond_to(:lens_report)
+    expect(client).to respond_to(:clearest_lenses)
+    expect(client).to respond_to(:most_distorted)
+  end
+
+  it 'maintains isolated engine state per instance' do
+    client2 = described_class.new
+    client.create_lens(lens_type: :magnifying)
+    expect(client.lens_report[:lens_count]).to eq(1)
+    expect(client2.lens_report[:lens_count]).to eq(0)
+  end
+
+  it 'round-trips a full lens lifecycle' do
+    # Create two lenses
+    l1 = client.create_lens(lens_type: :magnifying, clarity: 0.9)
+    l2 = client.create_lens(lens_type: :wide_angle, clarity: 0.8)
+    expect(l1[:success]).to be true
+    expect(l2[:success]).to be true
+
+    # Stack them
+    stack_result = client.stack_lenses(lens_ids: [l1[:lens][:id], l2[:lens][:id]])
+    expect(stack_result[:success]).to be true
+
+    # View through the stack
+    view = client.view_through_stack(stack_id: stack_result[:stack_id], content: 0.7)
+    expect(view[:success]).to be true
+    expect(view[:perceived]).to be_between(0.0, 1.0)
+
+    # Degrade and verify report
+    client.degrade_all(rate: 0.05)
+    report = client.lens_report
+    expect(report[:lens_count]).to eq(2)
+    expect(report[:avg_clarity]).to be < 0.9
+  end
+
+  it 'creates all 6 lens types without error' do
+    lens_types = Legion::Extensions::Agentic::Attention::Lens::Helpers::Constants::LENS_TYPES
+    results = lens_types.map { |lt| client.create_lens(lens_type: lt) }
+    expect(results.all? { |r| r[:success] }).to be true
+  end
+
+  it 'reports clearest and most distorted after creating lenses' do
+    client.create_lens(lens_type: :fish_eye)
+    client.create_lens(lens_type: :polarized)
+
+    clearest = client.clearest_lenses(limit: 1)
+    distorted = client.most_distorted(limit: 1)
+
+    expect(clearest[:lenses].size).to eq(1)
+    expect(distorted[:lenses].size).to eq(1)
+  end
+end

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Lens::Helpers::Constants do
+  describe 'LENS_TYPES' do
+    it 'contains 6 lens types' do
+      expect(described_class::LENS_TYPES.size).to eq(6)
+    end
+
+    it 'includes all expected types' do
+      expect(described_class::LENS_TYPES).to include(:magnifying, :wide_angle, :fish_eye, :polarized, :telescopic, :microscopic)
+    end
+
+    it 'is frozen' do
+      expect(described_class::LENS_TYPES).to be_frozen
+    end
+  end
+
+  describe 'DISTORTION_TYPES' do
+    it 'contains expected distortion modes' do
+      expect(described_class::DISTORTION_TYPES).to include(:none, :barrel, :pincushion)
+    end
+
+    it 'is frozen' do
+      expect(described_class::DISTORTION_TYPES).to be_frozen
+    end
+  end
+
+  describe 'MAX_LENSES' do
+    it 'is 8' do
+      expect(described_class::MAX_LENSES).to eq(8)
+    end
+  end
+
+  describe 'CLARITY_LABELS' do
+    it 'covers the full 0..1 range' do
+      all_values_covered = [0.0, 0.1, 0.3, 0.5, 0.7, 0.9, 1.0].all? do |v|
+        described_class::CLARITY_LABELS.any? { |range, _| range.cover?(v) }
+      end
+      expect(all_values_covered).to be true
+    end
+
+    it 'labels low clarity as opaque or foggy' do
+      label = described_class::CLARITY_LABELS.find { |range, _| range.cover?(0.1) }&.last
+      expect(label).to eq(:opaque)
+    end
+
+    it 'labels high clarity as crystal' do
+      label = described_class::CLARITY_LABELS.find { |range, _| range.cover?(0.95) }&.last
+      expect(label).to eq(:crystal)
+    end
+  end
+
+  describe 'MAGNIFICATION_LABELS' do
+    it 'labels 1.5x as zoom' do
+      label = described_class::MAGNIFICATION_LABELS.find { |range, _| range.cover?(1.5) }&.last
+      expect(label).to eq(:zoom)
+    end
+
+    it 'labels 0.7x as normal' do
+      label = described_class::MAGNIFICATION_LABELS.find { |range, _| range.cover?(0.7) }&.last
+      expect(label).to eq(:normal)
+    end
+
+    it 'labels 7.0x as extreme' do
+      label = described_class::MAGNIFICATION_LABELS.find { |range, _| range.cover?(7.0) }&.last
+      expect(label).to eq(:extreme)
+    end
+  end
+
+  describe 'LENS_DEFAULTS' do
+    it 'has defaults for every lens type' do
+      described_class::LENS_TYPES.each do |lt|
+        expect(described_class::LENS_DEFAULTS).to have_key(lt)
+      end
+    end
+
+    it 'fish_eye has maximum aperture' do
+      expect(described_class::LENS_DEFAULTS[:fish_eye][:aperture]).to eq(1.0)
+    end
+
+    it 'polarized has zero distortion' do
+      expect(described_class::LENS_DEFAULTS[:polarized][:distortion]).to eq(0.0)
+    end
+
+    it 'telescopic and microscopic have the highest default magnifications' do
+      mags = described_class::LENS_DEFAULTS.transform_values { |d| d[:magnification] }
+      high_mags = mags.values.sort.last(2)
+      expect(mags[:telescopic]).to be >= high_mags.first
+    end
+  end
+end

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

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Lens::Helpers::LensEngine do
+  let(:engine) { described_class.new }
+
+  describe '#create_lens' do
+    it 'creates and registers a lens' do
+      lens = engine.create_lens(lens_type: :magnifying)
+      expect(engine.lenses[lens.id]).to eq(lens)
+    end
+
+    it 'returns a Lens instance' do
+      lens = engine.create_lens(lens_type: :wide_angle)
+      expect(lens).to be_a(Legion::Extensions::Agentic::Attention::Lens::Helpers::Lens)
+    end
+
+    it 'passes custom magnification' do
+      lens = engine.create_lens(lens_type: :magnifying, magnification: 3.0)
+      expect(lens.magnification).to be_within(0.001).of(3.0)
+    end
+
+    it 'passes custom clarity' do
+      lens = engine.create_lens(lens_type: :magnifying, clarity: 0.6)
+      expect(lens.clarity).to be_within(0.001).of(0.6)
+    end
+
+    it 'creates multiple lenses with different ids' do
+      l1 = engine.create_lens(lens_type: :magnifying)
+      l2 = engine.create_lens(lens_type: :wide_angle)
+      expect(l1.id).not_to eq(l2.id)
+    end
+  end
+
+  describe '#stack_lenses' do
+    let(:lens1) { engine.create_lens(lens_type: :magnifying) }
+    let(:lens2) { engine.create_lens(lens_type: :wide_angle) }
+
+    it 'creates a stack from lens ids' do
+      result = engine.stack_lenses(lens_ids: [lens1.id, lens2.id])
+      expect(result[:stack]).to be_a(Legion::Extensions::Agentic::Attention::Lens::Helpers::LensStack)
+    end
+
+    it 'registers the stack with an auto-generated id' do
+      result = engine.stack_lenses(lens_ids: [lens1.id])
+      expect(engine.stacks[result[:stack_id]]).to be_a(Legion::Extensions::Agentic::Attention::Lens::Helpers::LensStack)
+    end
+
+    it 'uses provided stack_id' do
+      result = engine.stack_lenses(lens_ids: [lens1.id], stack_id: 'my-stack')
+      expect(result[:stack_id]).to eq('my-stack')
+    end
+
+    it 'raises ArgumentError for unknown lens id' do
+      expect { engine.stack_lenses(lens_ids: ['unknown-id']) }.to raise_error(ArgumentError, /lens not found/)
+    end
+  end
+
+  describe '#view_through_stack' do
+    let(:lens) { engine.create_lens(lens_type: :magnifying) }
+    let(:stack_result) { engine.stack_lenses(lens_ids: [lens.id]) }
+    let(:stack_id) { stack_result[:stack_id] }
+
+    it 'returns view result for existing stack' do
+      result = engine.view_through_stack(stack_id: stack_id, content: 0.6)
+      expect(result).to have_key(:perceived)
+    end
+
+    it 'raises ArgumentError for unknown stack id' do
+      expect { engine.view_through_stack(stack_id: 'bad-id', content: 0.5) }
+        .to raise_error(ArgumentError, /stack not found/)
+    end
+  end
+
+  describe '#degrade_all!' do
+    it 'reduces clarity on all lenses' do
+      l1 = engine.create_lens(lens_type: :magnifying, clarity: 1.0)
+      l2 = engine.create_lens(lens_type: :wide_angle, clarity: 1.0)
+      engine.degrade_all!
+      expect(l1.clarity).to be < 1.0
+      expect(l2.clarity).to be < 1.0
+    end
+
+    it 'returns degraded count and rate' do
+      engine.create_lens(lens_type: :magnifying)
+      result = engine.degrade_all!(rate: 0.05)
+      expect(result[:degraded]).to eq(1)
+      expect(result[:rate]).to eq(0.05)
+    end
+
+    it 'handles empty lens set gracefully' do
+      result = engine.degrade_all!
+      expect(result[:degraded]).to eq(0)
+    end
+  end
+
+  describe '#clearest_lenses' do
+    it 'returns lenses sorted by clarity descending' do
+      engine.create_lens(lens_type: :magnifying, clarity: 0.5)
+      engine.create_lens(lens_type: :wide_angle,  clarity: 0.9)
+      engine.create_lens(lens_type: :polarized,   clarity: 0.3)
+      result = engine.clearest_lenses(limit: 2)
+      expect(result.first[:clarity]).to be >= result.last[:clarity]
+    end
+
+    it 'respects the limit' do
+      5.times { engine.create_lens(lens_type: :magnifying) }
+      expect(engine.clearest_lenses(limit: 3).size).to eq(3)
+    end
+
+    it 'returns empty array when no lenses exist' do
+      expect(engine.clearest_lenses).to eq([])
+    end
+  end
+
+  describe '#most_distorted' do
+    it 'returns lenses sorted by distortion descending' do
+      engine.create_lens(lens_type: :fish_eye)
+      engine.create_lens(lens_type: :polarized)
+      result = engine.most_distorted(limit: 2)
+      expect(result.first[:distortion]).to be >= result.last[:distortion]
+    end
+
+    it 'respects the limit' do
+      5.times { engine.create_lens(lens_type: :magnifying) }
+      expect(engine.most_distorted(limit: 2).size).to eq(2)
+    end
+  end
+
+  describe '#lens_report' do
+    it 'returns empty report when no lenses exist' do
+      report = engine.lens_report
+      expect(report[:lens_count]).to eq(0)
+      expect(report[:lenses]).to eq([])
+    end
+
+    it 'includes lens and stack counts' do
+      engine.create_lens(lens_type: :magnifying)
+      report = engine.lens_report
+      expect(report[:lens_count]).to eq(1)
+      expect(report[:stack_count]).to eq(0)
+    end
+
+    it 'includes avg_clarity and avg_distortion' do
+      engine.create_lens(lens_type: :magnifying, clarity: 0.8)
+      report = engine.lens_report
+      expect(report[:avg_clarity]).to be_a(Float)
+      expect(report[:avg_distortion]).to be_a(Float)
+    end
+
+    it 'counts sharp and blurry lenses' do
+      engine.create_lens(lens_type: :magnifying, clarity: 0.9)
+      engine.create_lens(lens_type: :wide_angle, clarity: 0.2)
+      report = engine.lens_report
+      expect(report[:sharp_count]).to eq(1)
+      expect(report[:blurry_count]).to eq(1)
+    end
+  end
+end

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

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Lens::Helpers::Lens do
+  let(:magnifying)  { described_class.new(lens_type: :magnifying) }
+  let(:wide_angle)  { described_class.new(lens_type: :wide_angle) }
+  let(:fish_eye)    { described_class.new(lens_type: :fish_eye) }
+  let(:polarized)   { described_class.new(lens_type: :polarized) }
+  let(:telescopic)  { described_class.new(lens_type: :telescopic) }
+  let(:microscopic) { described_class.new(lens_type: :microscopic) }
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(magnifying.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets lens_type' do
+      expect(magnifying.lens_type).to eq(:magnifying)
+    end
+
+    it 'applies defaults from LENS_DEFAULTS for magnifying' do
+      defaults = Legion::Extensions::Agentic::Attention::Lens::Helpers::Constants::LENS_DEFAULTS[:magnifying]
+      expect(magnifying.magnification).to be_within(0.001).of(defaults[:magnification])
+      expect(magnifying.aperture).to be_within(0.001).of(defaults[:aperture])
+      expect(magnifying.distortion).to be_within(0.001).of(defaults[:distortion])
+    end
+
+    it 'allows overriding defaults' do
+      lens = described_class.new(lens_type: :magnifying, magnification: 3.5, clarity: 0.8)
+      expect(lens.magnification).to be_within(0.001).of(3.5)
+      expect(lens.clarity).to be_within(0.001).of(0.8)
+    end
+
+    it 'clamps magnification to [0.1, 10.0]' do
+      lens = described_class.new(lens_type: :magnifying, magnification: 50.0)
+      expect(lens.magnification).to eq(10.0)
+    end
+
+    it 'clamps clarity to [0.0, 1.0]' do
+      lens = described_class.new(lens_type: :magnifying, clarity: 1.5)
+      expect(lens.clarity).to eq(1.0)
+    end
+
+    it 'clamps distortion to [0.0, 1.0]' do
+      lens = described_class.new(lens_type: :magnifying, distortion: -0.3)
+      expect(lens.distortion).to eq(0.0)
+    end
+
+    it 'raises ArgumentError for unknown lens_type' do
+      expect { described_class.new(lens_type: :quantum) }.to raise_error(ArgumentError, /unknown lens_type/)
+    end
+
+    it 'starts with no focus target' do
+      expect(magnifying.focus_target).to be_nil
+    end
+
+    it 'records created_at timestamp' do
+      expect(magnifying.created_at).to be_a(Time)
+    end
+  end
+
+  describe '#focus!' do
+    it 'sets focus target' do
+      magnifying.focus!('threat_assessment')
+      expect(magnifying.focus_target).to eq('threat_assessment')
+    end
+
+    it 'returns self for chaining' do
+      expect(magnifying.focus!('target')).to eq(magnifying)
+    end
+
+    it 'marks lens as focused?' do
+      magnifying.focus!('something')
+      expect(magnifying.focused?).to be true
+    end
+  end
+
+  describe '#defocus!' do
+    it 'clears focus target' do
+      magnifying.focus!('target')
+      magnifying.defocus!
+      expect(magnifying.focus_target).to be_nil
+    end
+
+    it 'returns self for chaining' do
+      expect(magnifying.defocus!).to eq(magnifying)
+    end
+
+    it 'marks lens as not focused?' do
+      magnifying.focus!('target')
+      magnifying.defocus!
+      expect(magnifying.focused?).to be false
+    end
+  end
+
+  describe '#smudge!' do
+    it 'reduces clarity by the smudge rate' do
+      lens = described_class.new(lens_type: :magnifying, clarity: 0.8)
+      lens.smudge!(0.1)
+      expect(lens.clarity).to be_within(0.001).of(0.7)
+    end
+
+    it 'does not go below 0.0' do
+      lens = described_class.new(lens_type: :magnifying, clarity: 0.05)
+      lens.smudge!(0.5)
+      expect(lens.clarity).to eq(0.0)
+    end
+
+    it 'uses default rate when not specified' do
+      lens = described_class.new(lens_type: :magnifying, clarity: 1.0)
+      lens.smudge!
+      expect(lens.clarity).to be < 1.0
+    end
+
+    it 'returns self for chaining' do
+      expect(magnifying.smudge!).to eq(magnifying)
+    end
+  end
+
+  describe '#clean!' do
+    it 'increases clarity by the boost amount' do
+      lens = described_class.new(lens_type: :magnifying, clarity: 0.5)
+      lens.clean!(0.2)
+      expect(lens.clarity).to be_within(0.001).of(0.7)
+    end
+
+    it 'does not exceed 1.0' do
+      lens = described_class.new(lens_type: :magnifying, clarity: 0.95)
+      lens.clean!(0.5)
+      expect(lens.clarity).to eq(1.0)
+    end
+
+    it 'returns self for chaining' do
+      expect(magnifying.clean!).to eq(magnifying)
+    end
+  end
+
+  describe '#sharp?' do
+    it 'returns true when clarity is high' do
+      lens = described_class.new(lens_type: :magnifying, clarity: 0.9)
+      expect(lens.sharp?).to be true
+    end
+
+    it 'returns false when clarity is low' do
+      lens = described_class.new(lens_type: :magnifying, clarity: 0.5)
+      expect(lens.sharp?).to be false
+    end
+  end
+
+  describe '#blurry?' do
+    it 'returns true when clarity is very low' do
+      lens = described_class.new(lens_type: :magnifying, clarity: 0.2)
+      expect(lens.blurry?).to be true
+    end
+
+    it 'returns false when clarity is moderate' do
+      lens = described_class.new(lens_type: :magnifying, clarity: 0.6)
+      expect(lens.blurry?).to be false
+    end
+  end
+
+  describe '#clarity_label' do
+    it 'returns :opaque for very low clarity' do
+      lens = described_class.new(lens_type: :magnifying, clarity: 0.1)
+      expect(lens.clarity_label).to eq(:opaque)
+    end
+
+    it 'returns :crystal for high clarity' do
+      lens = described_class.new(lens_type: :magnifying, clarity: 0.9)
+      expect(lens.clarity_label).to eq(:crystal)
+    end
+  end
+
+  describe '#magnification_label' do
+    it 'returns :normal for 1x magnification (first matching range)' do
+      lens = described_class.new(lens_type: :magnifying, magnification: 1.0)
+      expect(lens.magnification_label).to eq(:normal)
+    end
+
+    it 'returns :zoom for 1.5x magnification' do
+      lens = described_class.new(lens_type: :magnifying, magnification: 1.5)
+      expect(lens.magnification_label).to eq(:zoom)
+    end
+
+    it 'returns :extreme for high magnification' do
+      lens = described_class.new(lens_type: :telescopic)
+      expect(lens.magnification_label).to eq(:extreme)
+    end
+  end
+
+  describe '#depth_of_field' do
+    it 'returns a value between 0 and 1' do
+      expect(magnifying.depth_of_field).to be_between(0.0, 1.0)
+    end
+
+    it 'fish_eye returns a value between 0 and 1' do
+      expect(fish_eye.depth_of_field).to be_between(0.0, 1.0)
+    end
+
+    it 'polarized returns a value between 0 and 1' do
+      expect(polarized.depth_of_field).to be_between(0.0, 1.0)
+    end
+
+    it 'high magnification lens has different depth than low magnification' do
+      high_mag = described_class.new(lens_type: :telescopic, magnification: 9.0, aperture: 0.5)
+      low_mag  = described_class.new(lens_type: :wide_angle, magnification: 0.5, aperture: 0.5)
+      expect(high_mag.depth_of_field).not_to eq(low_mag.depth_of_field)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with all expected keys' do
+      h = magnifying.to_h
+      expect(h.keys).to include(:id, :lens_type, :magnification, :clarity, :distortion,
+                                :aperture, :focus_target, :sharp, :blurry,
+                                :clarity_label, :magnification_label, :depth_of_field)
+    end
+
+    it 'includes correct lens_type' do
+      expect(wide_angle.to_h[:lens_type]).to eq(:wide_angle)
+    end
+  end
+end