lex-agentic-attention 0.1.0

data/spec/legion/extensions/agentic/attention/prism/runners/cognitive_prism_spec.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Prism::Runners::CognitivePrism do
+  let(:engine) { Legion::Extensions::Agentic::Attention::Prism::Helpers::PrismEngine.new }
+
+  describe '#create_beam' do
+    it 'creates a beam via the provided engine' do
+      result = described_class.create_beam(domain: :science, content: 'relativity theory', engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:domain]).to eq(:science)
+    end
+
+    it 'returns beam_id' do
+      result = described_class.create_beam(domain: :art, content: 'impressionism', engine: engine)
+      expect(result[:beam_id]).to be_a(String)
+    end
+
+    it 'returns failure on ArgumentError (MAX_BEAMS)' do
+      stub_const('Legion::Extensions::Agentic::Attention::Prism::Helpers::Constants::MAX_BEAMS', 0)
+      result = described_class.create_beam(domain: :d, content: 'x', engine: engine)
+      expect(result[:success]).to be false
+      expect(result[:error]).to be_a(String)
+    end
+
+    it 'accepts extra kwargs via ** splat' do
+      result = described_class.create_beam(domain: :test, content: 'splat test', engine: engine, extra: :ignored)
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#decompose' do
+    let(:beam_id) { described_class.create_beam(domain: :physics, content: 'wave-particle duality', engine: engine)[:beam_id] }
+
+    it 'returns success with component count' do
+      result = described_class.decompose(beam_id: beam_id, engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:component_count]).to eq(8)
+    end
+
+    it 'returns failure for unknown beam_id' do
+      result = described_class.decompose(beam_id: 'ghost', engine: engine)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#recompose' do
+    let(:beam_id) do
+      id = described_class.create_beam(domain: :math, content: 'topology and manifolds', engine: engine)[:beam_id]
+      described_class.decompose(beam_id: id, engine: engine)
+      id
+    end
+
+    it 'returns success' do
+      result = described_class.recompose(component_ids: [], engine: engine)
+      expect(result[:success]).to be true
+    end
+
+    it 'accepts extra kwargs' do
+      result = described_class.recompose(component_ids: [], engine: engine, meta: :data)
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#attenuate_all' do
+    before do
+      id = described_class.create_beam(domain: :d, content: 'idea to attenuate', engine: engine)[:beam_id]
+      described_class.decompose(beam_id: id, engine: engine)
+    end
+
+    it 'returns success' do
+      result = described_class.attenuate_all(engine: engine)
+      expect(result[:success]).to be true
+    end
+
+    it 'reports attenuated count' do
+      result = described_class.attenuate_all(engine: engine)
+      expect(result[:attenuated]).to eq(8)
+    end
+
+    it 'accepts a custom rate' do
+      result = described_class.attenuate_all(rate: 0.2, engine: engine)
+      expect(result[:rate]).to eq(0.2)
+    end
+  end
+
+  describe '#dominant_bands' do
+    it 'returns success with bands hash' do
+      result = described_class.dominant_bands(engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:bands]).to be_a(Hash)
+    end
+
+    it 'bands hash has values after decomposition' do
+      id = described_class.create_beam(domain: :d, content: 'bright idea', engine: engine)[:beam_id]
+      described_class.decompose(beam_id: id, engine: engine)
+      result = described_class.dominant_bands(engine: engine)
+      expect(result[:bands]).not_to be_empty
+    end
+  end
+
+  describe '#most_intense' do
+    before do
+      id = described_class.create_beam(domain: :d, content: 'intense thought', engine: engine)[:beam_id]
+      described_class.decompose(beam_id: id, engine: engine)
+    end
+
+    it 'returns success with components array' do
+      result = described_class.most_intense(engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:components]).to be_an(Array)
+    end
+
+    it 'respects the limit parameter' do
+      result = described_class.most_intense(limit: 3, engine: engine)
+      expect(result[:components].size).to be <= 3
+    end
+  end
+
+  describe '#spectral_report' do
+    it 'returns success with report keys' do
+      result = described_class.spectral_report(engine: engine)
+      expect(result[:success]).to be true
+      expect(result).to have_key(:total_beams)
+      expect(result).to have_key(:decomposed_beams)
+    end
+
+    it 'includes avg_purity' do
+      result = described_class.spectral_report(engine: engine)
+      expect(result).to have_key(:avg_purity)
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Regulation::Client do
+  subject(:client) { described_class.new }
+
+  it 'full lifecycle: add targets, focus, zoom, scan, rest' do
+    a = client.add_attention_target(name: 'urgent email', domain: :work, salience: 0.8)
+    expect(a[:success]).to be true
+
+    b = client.add_attention_target(name: 'background music', domain: :ambient, salience: 0.2)
+    expect(b[:success]).to be true
+
+    focus_result = client.focus_attention(target_id: a[:target_id])
+    expect(focus_result[:success]).to be true
+    expect(focus_result[:mode]).to eq(:focused)
+
+    zoom_result = client.zoom_attention_in(amount: 0.2)
+    expect(zoom_result[:zoom]).to be > 0.5
+
+    current = client.current_attention_target
+    expect(current[:target][:name]).to eq('urgent email')
+
+    client.defocus_attention
+    client.rest_attention
+
+    stats = client.attention_regulation_stats
+    expect(stats[:mode]).to eq(:resting)
+    expect(stats[:target_count]).to eq(2)
+  end
+
+  it 'accepts an injected controller' do
+    ctrl = Legion::Extensions::Agentic::Attention::Regulation::Helpers::AttentionController.new
+    c = described_class.new(controller: ctrl)
+    c.add_attention_target(name: 'injected', salience: 0.5)
+    expect(ctrl.to_h[:target_count]).to eq(1)
+  end
+
+  it 'captures high-salience target during scan' do
+    client.add_attention_target(name: 'alarm', domain: :safety, salience: 0.9)
+    result = client.scan_attention
+    expect(result[:captured_target_id]).not_to be_nil
+  end
+
+  it 'resource drains when focused and recovers when resting' do
+    t = client.add_attention_target(name: 'work', salience: 0.5)
+    client.focus_attention(target_id: t[:target_id])
+    initial = client.attention_regulation_stats[:resource]
+
+    5.times { client.update_attention }
+    drained = client.attention_regulation_stats[:resource]
+    expect(drained).to be < initial
+
+    client.rest_attention
+    client.update_attention
+    recovered = client.attention_regulation_stats[:resource]
+    expect(recovered).to be > drained
+  end
+end

data/spec/legion/extensions/agentic/attention/regulation/helpers/attention_controller_spec.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Regulation::Helpers::AttentionController do
+  subject(:ctrl) { described_class.new }
+
+  describe '#initialize' do
+    it 'starts in :diffuse mode' do
+      expect(ctrl.to_h[:mode]).to eq(:diffuse)
+    end
+
+    it 'starts with full resource' do
+      expect(ctrl.to_h[:resource]).to eq(1.0)
+    end
+
+    it 'starts with default zoom' do
+      expect(ctrl.to_h[:zoom]).to eq(0.5)
+    end
+
+    it 'starts with zero targets' do
+      expect(ctrl.to_h[:target_count]).to eq(0)
+    end
+  end
+
+  describe '#add_target' do
+    it 'adds a target and returns it' do
+      target = ctrl.add_target(name: 'inbox', domain: :work, salience: 0.4)
+      expect(target).to be_a(Legion::Extensions::Agentic::Attention::Regulation::Helpers::AttentionTarget)
+      expect(target.name).to eq('inbox')
+    end
+
+    it 'increments target count' do
+      ctrl.add_target(name: 'first', salience: 0.3)
+      ctrl.add_target(name: 'second', salience: 0.5)
+      expect(ctrl.to_h[:target_count]).to eq(2)
+    end
+
+    it 'assigns unique ids' do
+      t1 = ctrl.add_target(name: 'a', salience: 0.3)
+      t2 = ctrl.add_target(name: 'b', salience: 0.4)
+      expect(t1.id).not_to eq(t2.id)
+    end
+
+    it 'returns nil when limit is reached' do
+      30.times { |i| ctrl.add_target(name: "target #{i}", salience: 0.3) }
+      result = ctrl.add_target(name: 'overflow', salience: 0.5)
+      expect(result).to be_nil
+    end
+  end
+
+  describe '#focus_on' do
+    let(:target) { ctrl.add_target(name: 'focus me', salience: 0.5) }
+
+    it 'sets mode to :focused' do
+      ctrl.focus_on(target_id: target.id)
+      expect(ctrl.to_h[:mode]).to eq(:focused)
+    end
+
+    it 'sets the current target' do
+      ctrl.focus_on(target_id: target.id)
+      expect(ctrl.current_target).to eq(target)
+    end
+
+    it 'marks the target as attended' do
+      ctrl.focus_on(target_id: target.id)
+      expect(target.state).to eq(:attended)
+    end
+
+    it 'returns nil for unknown target' do
+      result = ctrl.focus_on(target_id: :nonexistent)
+      expect(result).to be_nil
+    end
+
+    it 'marks previous target as peripheral when switching focus' do
+      t1 = ctrl.add_target(name: 'first', salience: 0.4)
+      t2 = ctrl.add_target(name: 'second', salience: 0.5)
+      ctrl.focus_on(target_id: t1.id)
+      ctrl.focus_on(target_id: t2.id)
+      expect(t1.state).to eq(:peripheral)
+      expect(t2.state).to eq(:attended)
+    end
+  end
+
+  describe '#defocus' do
+    it 'sets mode to :diffuse' do
+      target = ctrl.add_target(name: 'x', salience: 0.4)
+      ctrl.focus_on(target_id: target.id)
+      ctrl.defocus
+      expect(ctrl.to_h[:mode]).to eq(:diffuse)
+    end
+
+    it 'clears current target' do
+      target = ctrl.add_target(name: 'x', salience: 0.4)
+      ctrl.focus_on(target_id: target.id)
+      ctrl.defocus
+      expect(ctrl.current_target).to be_nil
+    end
+
+    it 'marks previously attended target as peripheral' do
+      target = ctrl.add_target(name: 'x', salience: 0.4)
+      ctrl.focus_on(target_id: target.id)
+      ctrl.defocus
+      expect(target.state).to eq(:peripheral)
+    end
+  end
+
+  describe '#scan' do
+    it 'sets mode to :scanning' do
+      ctrl.scan
+      expect(ctrl.to_h[:mode]).to eq(:scanning)
+    end
+
+    it 'captures a high-salience target automatically' do
+      ctrl.add_target(name: 'urgent', salience: 0.9)
+      ctrl.scan
+      expect(ctrl.to_h[:mode]).to eq(:captured)
+    end
+
+    it 'does not capture when no target meets threshold' do
+      ctrl.add_target(name: 'low', salience: 0.3)
+      ctrl.scan
+      expect(ctrl.to_h[:mode]).to eq(:scanning)
+    end
+  end
+
+  describe '#rest' do
+    it 'sets mode to :resting' do
+      ctrl.rest
+      expect(ctrl.to_h[:mode]).to eq(:resting)
+    end
+
+    it 'clears current target' do
+      t = ctrl.add_target(name: 'x', salience: 0.4)
+      ctrl.focus_on(target_id: t.id)
+      ctrl.rest
+      expect(ctrl.current_target).to be_nil
+    end
+  end
+
+  describe '#zoom_in' do
+    it 'increases zoom' do
+      original = ctrl.to_h[:zoom]
+      ctrl.zoom_in(amount: 0.2)
+      expect(ctrl.to_h[:zoom]).to be > original
+    end
+
+    it 'clamps zoom at ceiling' do
+      ctrl.zoom_in(amount: 2.0)
+      expect(ctrl.to_h[:zoom]).to eq(1.0)
+    end
+  end
+
+  describe '#zoom_out' do
+    it 'decreases zoom' do
+      original = ctrl.to_h[:zoom]
+      ctrl.zoom_out(amount: 0.2)
+      expect(ctrl.to_h[:zoom]).to be < original
+    end
+
+    it 'clamps zoom at floor' do
+      ctrl.zoom_out(amount: 2.0)
+      expect(ctrl.to_h[:zoom]).to eq(0.1)
+    end
+  end
+
+  describe '#check_capture' do
+    it 'captures the most salient unattended target above threshold' do
+      ctrl.add_target(name: 'medium', salience: 0.75)
+      ctrl.add_target(name: 'high', salience: 0.95)
+      result = ctrl.check_capture
+      expect(result).not_to be_nil
+      expect(result.salience).to eq(0.95)
+    end
+
+    it 'returns nil when no target is salient enough' do
+      ctrl.add_target(name: 'low', salience: 0.2)
+      expect(ctrl.check_capture).to be_nil
+    end
+
+    it 'returns nil when resource is too low' do
+      ctrl.add_target(name: 'urgent', salience: 0.9)
+      # set resource below the 0.3 capture threshold directly
+      ctrl.instance_variable_set(:@resource, 0.1)
+      expect(ctrl.check_capture).to be_nil
+    end
+
+    it 'does not capture an already attended target' do
+      t = ctrl.add_target(name: 'urgent', salience: 0.9)
+      ctrl.focus_on(target_id: t.id)
+      # attended target should not self-capture
+      result = ctrl.check_capture
+      expect(result).to be_nil
+    end
+  end
+
+  describe '#current_target' do
+    it 'returns nil when not focused' do
+      expect(ctrl.current_target).to be_nil
+    end
+
+    it 'returns the focused target' do
+      t = ctrl.add_target(name: 'active', salience: 0.5)
+      ctrl.focus_on(target_id: t.id)
+      expect(ctrl.current_target).to eq(t)
+    end
+  end
+
+  describe '#most_salient' do
+    it 'returns the target with highest salience' do
+      ctrl.add_target(name: 'low', salience: 0.2)
+      ctrl.add_target(name: 'high', salience: 0.8)
+      ctrl.add_target(name: 'mid', salience: 0.5)
+      expect(ctrl.most_salient.name).to eq('high')
+    end
+
+    it 'returns nil when no targets exist' do
+      expect(ctrl.most_salient).to be_nil
+    end
+  end
+
+  describe '#attended_targets' do
+    it 'returns only attended targets' do
+      t1 = ctrl.add_target(name: 'a', salience: 0.5)
+      ctrl.add_target(name: 'b', salience: 0.4)
+      ctrl.focus_on(target_id: t1.id)
+      expect(ctrl.attended_targets.size).to eq(1)
+      expect(ctrl.attended_targets.first).to eq(t1)
+    end
+  end
+
+  describe '#peripheral_targets' do
+    it 'returns targets in :peripheral state' do
+      ctrl.add_target(name: 'a', salience: 0.3)
+      ctrl.add_target(name: 'b', salience: 0.4)
+      expect(ctrl.peripheral_targets.size).to eq(2)
+    end
+  end
+
+  describe '#tick' do
+    it 'drains resource when focused' do
+      t = ctrl.add_target(name: 'x', salience: 0.4)
+      ctrl.focus_on(target_id: t.id)
+      original = ctrl.to_h[:resource]
+      ctrl.tick
+      expect(ctrl.to_h[:resource]).to be < original
+    end
+
+    it 'recovers resource when resting' do
+      # first drain a bit
+      t = ctrl.add_target(name: 'x', salience: 0.4)
+      ctrl.focus_on(target_id: t.id)
+      5.times { ctrl.tick }
+      ctrl.rest
+      before_rest = ctrl.to_h[:resource]
+      ctrl.tick
+      expect(ctrl.to_h[:resource]).to be > before_rest
+    end
+
+    it 'does not change resource in diffuse mode' do
+      original = ctrl.to_h[:resource]
+      ctrl.tick
+      expect(ctrl.to_h[:resource]).to eq(original)
+    end
+
+    it 'triggers capture during scan tick' do
+      ctrl.add_target(name: 'urgent', salience: 0.9)
+      ctrl.scan
+      # scan already triggered capture in #scan, let's reset and test tick-triggered
+      ctrl2 = described_class.new
+      ctrl2.add_target(name: 'urgent', salience: 0.9)
+      # put in scanning mode without triggering capture (no target above threshold yet)
+      ctrl2.instance_variable_set(:@mode, :scanning)
+      ctrl2.tick
+      expect(ctrl2.to_h[:mode]).to eq(:captured)
+    end
+  end
+
+  describe '#resource_label' do
+    it 'returns :abundant for full resource' do
+      expect(ctrl.resource_label).to eq(:abundant)
+    end
+
+    it 'returns a symbol' do
+      expect(ctrl.resource_label).to be_a(Symbol)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns expected keys' do
+      expect(ctrl.to_h).to include(
+        :mode, :zoom, :resource, :resource_label,
+        :current_target_id, :target_count, :attended_count, :peripheral_count
+      )
+    end
+  end
+end

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

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Regulation::Helpers::AttentionTarget do
+  subject(:target) do
+    described_class.new(id: :target_one, name: 'urgent task', domain: :work, salience: 0.6)
+  end
+
+  describe '#initialize' do
+    it 'sets id, name, domain, salience' do
+      expect(target.id).to eq(:target_one)
+      expect(target.name).to eq('urgent task')
+      expect(target.domain).to eq(:work)
+      expect(target.salience).to eq(0.6)
+    end
+
+    it 'starts in :peripheral state' do
+      expect(target.state).to eq(:peripheral)
+    end
+
+    it 'starts with nil attended_since' do
+      expect(target.attended_since).to be_nil
+    end
+
+    it 'clamps salience to 0..1' do
+      t = described_class.new(id: :x, name: 'x', salience: 2.5)
+      expect(t.salience).to eq(1.0)
+    end
+
+    it 'clamps salience floor to 0' do
+      t = described_class.new(id: :x, name: 'x', salience: -0.5)
+      expect(t.salience).to eq(0.0)
+    end
+  end
+
+  describe '#attend!' do
+    it 'sets state to :attended' do
+      target.attend!
+      expect(target.state).to eq(:attended)
+    end
+
+    it 'records attended_since timestamp' do
+      target.attend!
+      expect(target.attended_since).to be_a(Time)
+    end
+  end
+
+  describe '#ignore!' do
+    it 'sets state to :ignored' do
+      target.attend!
+      target.ignore!
+      expect(target.state).to eq(:ignored)
+    end
+
+    it 'clears attended_since' do
+      target.attend!
+      target.ignore!
+      expect(target.attended_since).to be_nil
+    end
+  end
+
+  describe '#peripheral!' do
+    it 'sets state to :peripheral' do
+      target.attend!
+      target.peripheral!
+      expect(target.state).to eq(:peripheral)
+    end
+
+    it 'clears attended_since' do
+      target.attend!
+      target.peripheral!
+      expect(target.attended_since).to be_nil
+    end
+  end
+
+  describe '#salient_enough_to_capture?' do
+    it 'returns false when salience is below threshold' do
+      t = described_class.new(id: :x, name: 'x', salience: 0.5)
+      expect(t.salient_enough_to_capture?).to be false
+    end
+
+    it 'returns true when salience meets threshold' do
+      t = described_class.new(id: :x, name: 'x', salience: 0.7)
+      expect(t.salient_enough_to_capture?).to be true
+    end
+
+    it 'returns true when salience exceeds threshold' do
+      t = described_class.new(id: :x, name: 'x', salience: 0.9)
+      expect(t.salient_enough_to_capture?).to be true
+    end
+  end
+
+  describe '#duration' do
+    it 'returns nil when not attended' do
+      expect(target.duration).to be_nil
+    end
+
+    it 'returns nil when ignored' do
+      target.attend!
+      target.ignore!
+      expect(target.duration).to be_nil
+    end
+
+    it 'returns elapsed time when attended' do
+      target.attend!
+      sleep(0.01)
+      expect(target.duration).to be_a(Float)
+      expect(target.duration).to be > 0
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with expected keys' do
+      h = target.to_h
+      expect(h).to include(:id, :name, :domain, :salience, :state, :attended_since)
+    end
+
+    it 'rounds salience to 4 decimal places' do
+      t = described_class.new(id: :x, name: 'x', salience: 0.123456789)
+      expect(t.to_h[:salience]).to eq(0.1235)
+    end
+  end
+end