lex-agentic-attention 0.1.0

data/spec/legion/extensions/agentic/attention/telescope/helpers/observation_spec.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Telescope::Helpers::Observation do
+  let(:telescope_id) { SecureRandom.uuid }
+
+  subject(:observation) do
+    described_class.new(
+      telescope_id:            telescope_id,
+      target:                  'Alpha Centauri',
+      distance:                0.5,
+      telescope_magnification: 50.0
+    )
+  end
+
+  describe '#initialize' do
+    it 'generates a uuid id' do
+      expect(observation.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores the telescope_id' do
+      expect(observation.telescope_id).to eq(telescope_id)
+    end
+
+    it 'stores the target as string' do
+      expect(observation.target).to eq('Alpha Centauri')
+    end
+
+    it 'stores the clamped distance' do
+      expect(observation.distance).to eq(0.5)
+    end
+
+    it 'clamps distance above 1.0' do
+      obs = described_class.new(telescope_id: telescope_id, target: 'x',
+                                distance: 5.0, telescope_magnification: 10.0)
+      expect(obs.distance).to eq(1.0)
+    end
+
+    it 'clamps distance below 0.0' do
+      obs = described_class.new(telescope_id: telescope_id, target: 'x',
+                                distance: -1.0, telescope_magnification: 10.0)
+      expect(obs.distance).to eq(0.0)
+    end
+
+    it 'sets recorded_at' do
+      expect(observation.recorded_at).to be_a(Time)
+    end
+
+    it 'computes a detail_level between 0 and 1' do
+      expect(observation.detail_level).to be_between(0.0, 1.0)
+    end
+  end
+
+  describe '#detail_level' do
+    it 'is higher with greater magnification' do
+      low_mag  = described_class.new(telescope_id: telescope_id, target: 'x',
+                                     distance: 0.2, telescope_magnification: 10.0)
+      high_mag = described_class.new(telescope_id: telescope_id, target: 'x',
+                                     distance: 0.2, telescope_magnification: 90.0)
+      expect(high_mag.detail_level).to be > low_mag.detail_level
+    end
+
+    it 'is higher for closer targets' do
+      far   = described_class.new(telescope_id: telescope_id, target: 'x',
+                                  distance: 0.9, telescope_magnification: 50.0)
+      near  = described_class.new(telescope_id: telescope_id, target: 'x',
+                                  distance: 0.1, telescope_magnification: 50.0)
+      expect(near.detail_level).to be > far.detail_level
+    end
+
+    it 'is zero when at max distance with min magnification' do
+      obs = described_class.new(telescope_id: telescope_id, target: 'x',
+                                distance: 1.0, telescope_magnification: 1.0)
+      expect(obs.detail_level).to eq(0.0)
+    end
+  end
+
+  describe '#significant?' do
+    it 'returns true when detail_level >= 0.7' do
+      obs = described_class.new(telescope_id: telescope_id, target: 'x',
+                                distance: 0.1, telescope_magnification: 100.0)
+      expect(obs.significant?).to be true
+    end
+
+    it 'returns false when detail_level < 0.7' do
+      obs = described_class.new(telescope_id: telescope_id, target: 'x',
+                                distance: 0.9, telescope_magnification: 1.0)
+      expect(obs.significant?).to be false
+    end
+  end
+
+  describe '#faint?' do
+    it 'returns true when detail_level < 0.3' do
+      obs = described_class.new(telescope_id: telescope_id, target: 'x',
+                                distance: 0.9, telescope_magnification: 1.0)
+      expect(obs.faint?).to be true
+    end
+
+    it 'returns false for a well-resolved observation' do
+      # high magnification + very close distance = high detail (not faint)
+      obs = described_class.new(telescope_id: telescope_id, target: 'nearby',
+                                distance: 0.05, telescope_magnification: 100.0)
+      expect(obs.faint?).to be false
+    end
+  end
+
+  describe '#distance_label' do
+    it 'returns a symbol' do
+      expect(observation.distance_label).to be_a(Symbol)
+    end
+
+    it 'returns :cosmic for very distant targets' do
+      obs = described_class.new(telescope_id: telescope_id, target: 'x',
+                                distance: 0.95, telescope_magnification: 10.0)
+      expect(obs.distance_label).to eq(:cosmic)
+    end
+
+    it 'returns :myopic for very close targets' do
+      obs = described_class.new(telescope_id: telescope_id, target: 'x',
+                                distance: 0.05, telescope_magnification: 10.0)
+      expect(obs.distance_label).to eq(:myopic)
+    end
+  end
+
+  describe '#to_h' do
+    it 'contains all expected keys' do
+      h = observation.to_h
+      %i[id telescope_id target distance distance_label
+         detail_level significant faint recorded_at].each do |key|
+        expect(h).to have_key(key)
+      end
+    end
+
+    it 'serializes significant correctly' do
+      h = observation.to_h
+      expect(h[:significant]).to eq(observation.significant?)
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/telescope/helpers/observatory_engine_spec.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Telescope::Helpers::ObservatoryEngine do
+  subject(:engine) { described_class.new }
+
+  let(:telescope) { engine.create_telescope(lens_type: :refractor) }
+
+  describe '#create_telescope' do
+    it 'returns a Telescope instance' do
+      expect(telescope).to be_a(Legion::Extensions::Agentic::Attention::Telescope::Helpers::Telescope)
+    end
+
+    it 'stores the telescope' do
+      id = telescope.id
+      expect(engine.all_telescopes.map(&:id)).to include(id)
+    end
+
+    it 'raises when observatory is full' do
+      stub_const('Legion::Extensions::Agentic::Attention::Telescope::Helpers::Constants::MAX_TELESCOPES', 1)
+      engine.create_telescope(lens_type: :radio)
+      expect { engine.create_telescope(lens_type: :adaptive) }
+        .to raise_error(ArgumentError, /observatory full/)
+    end
+
+    it 'creates with custom aperture and magnification' do
+      t = engine.create_telescope(lens_type: :reflector, aperture: 0.9, magnification: 20.0)
+      expect(t.aperture).to eq(0.9)
+      expect(t.magnification).to eq(20.0)
+    end
+  end
+
+  describe '#zoom_in' do
+    it 'increases telescope magnification' do
+      old = telescope.magnification
+      engine.zoom_in(telescope_id: telescope.id, factor: 3.0)
+      expect(telescope.magnification).to be > old
+    end
+
+    it 'raises for unknown telescope' do
+      expect { engine.zoom_in(telescope_id: 'nope', factor: 2.0) }
+        .to raise_error(ArgumentError, /telescope not found/)
+    end
+  end
+
+  describe '#zoom_out' do
+    it 'decreases magnification after zoom_in' do
+      engine.zoom_in(telescope_id: telescope.id, factor: 10.0)
+      old = telescope.magnification
+      engine.zoom_out(telescope_id: telescope.id, factor: 2.0)
+      expect(telescope.magnification).to be < old
+    end
+
+    it 'raises for unknown telescope' do
+      expect { engine.zoom_out(telescope_id: 'nope', factor: 2.0) }
+        .to raise_error(ArgumentError, /telescope not found/)
+    end
+  end
+
+  describe '#focus_telescope' do
+    it 'sets focal_distance on the telescope' do
+      engine.focus_telescope(telescope_id: telescope.id, target_distance: 0.6)
+      expect(telescope.focal_distance).to eq(0.6)
+    end
+
+    it 'raises for unknown telescope' do
+      expect { engine.focus_telescope(telescope_id: 'x', target_distance: 0.5) }
+        .to raise_error(ArgumentError, /telescope not found/)
+    end
+  end
+
+  describe '#observe' do
+    it 'returns an Observation' do
+      obs = engine.observe(telescope_id: telescope.id, target: 'Mars', distance: 0.4)
+      expect(obs).to be_a(Legion::Extensions::Agentic::Attention::Telescope::Helpers::Observation)
+    end
+
+    it 'stores the observation' do
+      engine.observe(telescope_id: telescope.id, target: 'Venus', distance: 0.3)
+      expect(engine.all_observations.size).to eq(1)
+    end
+
+    it 'records target and distance' do
+      obs = engine.observe(telescope_id: telescope.id, target: 'Jupiter', distance: 0.7)
+      expect(obs.target).to eq('Jupiter')
+      expect(obs.distance).to eq(0.7)
+    end
+
+    it 'raises for unknown telescope' do
+      expect { engine.observe(telescope_id: 'nope', target: 'x', distance: 0.5) }
+        .to raise_error(ArgumentError, /telescope not found/)
+    end
+
+    it 'raises when observation log is full' do
+      stub_const('Legion::Extensions::Agentic::Attention::Telescope::Helpers::Constants::MAX_OBSERVATIONS', 1)
+      engine.observe(telescope_id: telescope.id, target: 'a', distance: 0.1)
+      expect { engine.observe(telescope_id: telescope.id, target: 'b', distance: 0.2) }
+        .to raise_error(ArgumentError, /observation log full/)
+    end
+  end
+
+  describe '#survey_mode!' do
+    it 'resets telescope to wide-field (magnification == 1.0)' do
+      engine.zoom_in(telescope_id: telescope.id, factor: 20.0)
+      engine.survey_mode!(telescope_id: telescope.id)
+      expect(telescope.magnification).to eq(1.0)
+    end
+
+    it 'raises for unknown telescope' do
+      expect { engine.survey_mode!(telescope_id: 'x') }
+        .to raise_error(ArgumentError, /telescope not found/)
+    end
+  end
+
+  describe '#deep_focus!' do
+    it 'zooms telescope to MAX_MAGNIFICATION' do
+      engine.deep_focus!(telescope_id: telescope.id)
+      expect(telescope.magnification).to eq(100.0)
+    end
+
+    it 'sets deep_field? to true' do
+      engine.deep_focus!(telescope_id: telescope.id)
+      expect(telescope.deep_field?).to be true
+    end
+
+    it 'raises for unknown telescope' do
+      expect { engine.deep_focus!(telescope_id: 'x') }
+        .to raise_error(ArgumentError, /telescope not found/)
+    end
+  end
+
+  describe '#all_telescopes' do
+    it 'returns all created telescopes' do
+      engine.create_telescope(lens_type: :radio)
+      engine.create_telescope(lens_type: :adaptive)
+      expect(engine.all_telescopes.size).to eq(2)
+    end
+  end
+
+  describe '#all_observations' do
+    it 'returns a copy of all observations' do
+      engine.observe(telescope_id: telescope.id, target: 'a', distance: 0.1)
+      engine.observe(telescope_id: telescope.id, target: 'b', distance: 0.2)
+      expect(engine.all_observations.size).to eq(2)
+    end
+  end
+
+  describe '#significant_observations' do
+    it 'returns only significant observations' do
+      # significant: high magnification + low distance
+      engine.zoom_in(telescope_id: telescope.id, factor: 100.0)
+      engine.observe(telescope_id: telescope.id, target: 'near', distance: 0.05)
+      # faint: low magnification + far distance
+      t2 = engine.create_telescope(lens_type: :radio, magnification: 1.0)
+      engine.observe(telescope_id: t2.id, target: 'far', distance: 0.99)
+      sig = engine.significant_observations
+      expect(sig.all?(&:significant?)).to be true
+    end
+  end
+
+  describe '#observatory_report' do
+    it 'returns a hash with all expected keys' do
+      telescope
+      engine.observe(telescope_id: telescope.id, target: 'x', distance: 0.5)
+      report = engine.observatory_report
+      %i[total_telescopes total_observations significant_count faint_count
+         avg_detail deepest_observation widest_telescope].each do |k|
+        expect(report).to have_key(k)
+      end
+    end
+
+    it 'counts telescopes and observations correctly' do
+      telescope
+      engine.observe(telescope_id: telescope.id, target: 'a', distance: 0.3)
+      engine.observe(telescope_id: telescope.id, target: 'b', distance: 0.6)
+      report = engine.observatory_report
+      expect(report[:total_telescopes]).to eq(1)
+      expect(report[:total_observations]).to eq(2)
+    end
+
+    it 'returns nil deepest_observation when no observations exist' do
+      telescope
+      report = engine.observatory_report
+      expect(report[:deepest_observation]).to be_nil
+    end
+
+    it 'returns nil widest_telescope when no telescopes exist' do
+      report = engine.observatory_report
+      expect(report[:widest_telescope]).to be_nil
+    end
+
+    it 'reports avg_detail as 0.0 when no observations' do
+      telescope
+      report = engine.observatory_report
+      expect(report[:avg_detail]).to eq(0.0)
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/telescope/helpers/telescope_spec.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Telescope::Helpers::Telescope do
+  subject(:telescope) { described_class.new(lens_type: :refractor) }
+
+  describe '#initialize' do
+    it 'generates a uuid id' do
+      expect(telescope.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores the lens_type as symbol' do
+      expect(telescope.lens_type).to eq(:refractor)
+    end
+
+    it 'defaults aperture to 0.5' do
+      expect(telescope.aperture).to eq(0.5)
+    end
+
+    it 'defaults magnification to 1.0' do
+      expect(telescope.magnification).to eq(1.0)
+    end
+
+    it 'defaults tracking to false' do
+      expect(telescope.tracking).to be false
+    end
+
+    it 'starts with nil focal_distance' do
+      expect(telescope.focal_distance).to be_nil
+    end
+
+    it 'sets created_at' do
+      expect(telescope.created_at).to be_a(Time)
+    end
+
+    it 'accepts custom aperture' do
+      t = described_class.new(lens_type: :reflector, aperture: 0.8)
+      expect(t.aperture).to eq(0.8)
+    end
+
+    it 'clamps aperture to 0.1 minimum' do
+      t = described_class.new(lens_type: :radio, aperture: 0.0)
+      expect(t.aperture).to eq(0.1)
+    end
+
+    it 'clamps aperture to 1.0 maximum' do
+      t = described_class.new(lens_type: :adaptive, aperture: 5.0)
+      expect(t.aperture).to eq(1.0)
+    end
+
+    it 'clamps magnification to BASE_MAGNIFICATION minimum' do
+      t = described_class.new(lens_type: :catadioptric, magnification: 0.0)
+      expect(t.magnification).to eq(1.0)
+    end
+
+    it 'clamps magnification to MAX_MAGNIFICATION maximum' do
+      t = described_class.new(lens_type: :reflector, magnification: 999.0)
+      expect(t.magnification).to eq(100.0)
+    end
+
+    it 'rejects unknown lens types' do
+      expect { described_class.new(lens_type: :laser) }
+        .to raise_error(ArgumentError, /unknown lens type/)
+    end
+
+    it 'accepts tracking: true' do
+      t = described_class.new(lens_type: :radio, tracking: true)
+      expect(t.tracking).to be true
+    end
+  end
+
+  describe '#zoom_in!' do
+    it 'increases magnification' do
+      old = telescope.magnification
+      telescope.zoom_in!(2.0)
+      expect(telescope.magnification).to be > old
+    end
+
+    it 'doubles magnification with factor 2' do
+      telescope.zoom_in!(2.0)
+      expect(telescope.magnification).to eq(2.0)
+    end
+
+    it 'does not exceed MAX_MAGNIFICATION' do
+      telescope.zoom_in!(1000.0)
+      expect(telescope.magnification).to eq(100.0)
+    end
+
+    it 'returns self for chaining' do
+      expect(telescope.zoom_in!(2.0)).to eq(telescope)
+    end
+  end
+
+  describe '#zoom_out!' do
+    it 'decreases magnification' do
+      telescope.zoom_in!(10.0)
+      old = telescope.magnification
+      telescope.zoom_out!(2.0)
+      expect(telescope.magnification).to be < old
+    end
+
+    it 'does not go below BASE_MAGNIFICATION' do
+      telescope.zoom_out!(1000.0)
+      expect(telescope.magnification).to eq(1.0)
+    end
+
+    it 'returns self for chaining' do
+      expect(telescope.zoom_out!(2.0)).to eq(telescope)
+    end
+  end
+
+  describe '#field_of_view' do
+    it 'is 1.0 at BASE_MAGNIFICATION with aperture 1.0' do
+      t = described_class.new(lens_type: :refractor, aperture: 1.0)
+      expect(t.field_of_view).to eq(1.0)
+    end
+
+    it 'decreases when magnification increases' do
+      wide = telescope.field_of_view
+      telescope.zoom_in!(10.0)
+      expect(telescope.field_of_view).to be < wide
+    end
+
+    it 'is larger with higher aperture at same magnification' do
+      t1 = described_class.new(lens_type: :refractor, aperture: 0.3)
+      t2 = described_class.new(lens_type: :refractor, aperture: 0.9)
+      expect(t2.field_of_view).to be > t1.field_of_view
+    end
+  end
+
+  describe '#clarity' do
+    it 'returns a float between 0 and 1' do
+      expect(telescope.clarity).to be_between(0.0, 1.0)
+    end
+
+    it 'is higher with larger aperture' do
+      t1 = described_class.new(lens_type: :reflector, aperture: 0.2)
+      t2 = described_class.new(lens_type: :reflector, aperture: 0.9)
+      expect(t2.clarity).to be > t1.clarity
+    end
+  end
+
+  describe '#focus!' do
+    it 'sets focal_distance' do
+      telescope.focus!(0.7)
+      expect(telescope.focal_distance).to eq(0.7)
+    end
+
+    it 'clamps focal_distance to 0..1' do
+      telescope.focus!(5.0)
+      expect(telescope.focal_distance).to eq(1.0)
+    end
+
+    it 'returns self for chaining' do
+      expect(telescope.focus!(0.5)).to eq(telescope)
+    end
+  end
+
+  describe '#enable_tracking! / #disable_tracking!' do
+    it 'enables tracking' do
+      telescope.enable_tracking!
+      expect(telescope.tracking).to be true
+    end
+
+    it 'disables tracking' do
+      telescope.enable_tracking!
+      telescope.disable_tracking!
+      expect(telescope.tracking).to be false
+    end
+
+    it 'enable_tracking! returns self' do
+      expect(telescope.enable_tracking!).to eq(telescope)
+    end
+
+    it 'disable_tracking! returns self' do
+      expect(telescope.disable_tracking!).to eq(telescope)
+    end
+  end
+
+  describe '#deep_field?' do
+    it 'returns false at low magnification' do
+      expect(telescope.deep_field?).to be false
+    end
+
+    it 'returns true when magnification >= 50' do
+      telescope.zoom_in!(50.0)
+      expect(telescope.deep_field?).to be true
+    end
+  end
+
+  describe '#wide_field?' do
+    it 'returns true at base magnification' do
+      expect(telescope.wide_field?).to be true
+    end
+
+    it 'returns false at high magnification' do
+      telescope.zoom_in!(10.0)
+      expect(telescope.wide_field?).to be false
+    end
+  end
+
+  describe '#sharp?' do
+    it 'returns true for large aperture telescope' do
+      t = described_class.new(lens_type: :adaptive, aperture: 1.0)
+      expect(t.sharp?).to be true
+    end
+
+    it 'returns false for small aperture telescope' do
+      t = described_class.new(lens_type: :radio, aperture: 0.1)
+      expect(t.sharp?).to be false
+    end
+  end
+
+  describe '#blurry?' do
+    it 'returns false for normal aperture' do
+      expect(telescope.blurry?).to be false
+    end
+
+    it 'returns true for very small aperture' do
+      t = described_class.new(lens_type: :refractor, aperture: 0.1)
+      expect(t.blurry?).to be true
+    end
+  end
+
+  describe '#clarity_label' do
+    it 'returns a symbol' do
+      expect(telescope.clarity_label).to be_a(Symbol)
+    end
+
+    it 'returns :crystal for a large-aperture telescope' do
+      t = described_class.new(lens_type: :adaptive, aperture: 1.0)
+      expect(t.clarity_label).to eq(:crystal)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with all expected keys' do
+      h = telescope.to_h
+      %i[id lens_type aperture magnification tracking focal_distance
+         field_of_view clarity clarity_label deep_field wide_field
+         sharp blurry created_at].each do |key|
+        expect(h).to have_key(key)
+      end
+    end
+
+    it 'reflects current state' do
+      telescope.zoom_in!(10.0)
+      h = telescope.to_h
+      expect(h[:magnification]).to eq(10.0)
+    end
+  end
+end