lex-agentic-attention 0.1.0

data/spec/legion/extensions/agentic/attention/schema/helpers/attention_schema_model_spec.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Schema::Helpers::AttentionSchemaModel do
+  subject(:model) { described_class.new }
+
+  let(:constants) { Legion::Extensions::Agentic::Attention::Schema::Helpers::Constants }
+
+  describe '#focus_on' do
+    it 'adds an item to the schema' do
+      item = model.focus_on(target: :task, domain: :work, reason: 'priority', source: :external)
+      expect(item.target).to eq('task')
+      expect(model.schema_size).to eq(1)
+    end
+
+    it 'boosts existing items on re-focus' do
+      model.focus_on(target: :task, domain: :work, reason: 'init', source: :external)
+      first_level = model.schema_items['task'].awareness_level
+      model.focus_on(target: :task, domain: :work, reason: 'again', source: :external)
+      expect(model.schema_items['task'].awareness_level).to be > first_level
+      expect(model.schema_size).to eq(1)
+    end
+
+    it 'prunes to capacity when full' do
+      constants::MAX_SCHEMA_ITEMS.times do |i|
+        model.focus_on(target: "item_#{i}", domain: :d, reason: :r, source: :s)
+      end
+      expect(model.schema_size).to eq(constants::MAX_SCHEMA_ITEMS)
+      model.focus_on(target: :overflow, domain: :d, reason: :r, source: :s)
+      expect(model.schema_size).to eq(constants::MAX_SCHEMA_ITEMS)
+    end
+
+    it 'records focus event in history' do
+      model.focus_on(target: :task, domain: :work, reason: 'test', source: :external)
+      expect(model.attention_history.size).to eq(1)
+      expect(model.attention_history.first[:event]).to eq(:focused)
+    end
+
+    it 'records refocused event on re-focus' do
+      model.focus_on(target: :task, domain: :work, reason: 'init', source: :external)
+      model.focus_on(target: :task, domain: :work, reason: 'again', source: :external)
+      expect(model.attention_history.last[:event]).to eq(:refocused)
+    end
+  end
+
+  describe '#defocus' do
+    it 'removes an item from the schema' do
+      model.focus_on(target: :task, domain: :work, reason: 'r', source: :s)
+      removed = model.defocus(target: :task)
+      expect(removed).to be true
+      expect(model.schema_size).to eq(0)
+    end
+
+    it 'returns false for unknown target' do
+      expect(model.defocus(target: :missing)).to be false
+    end
+  end
+
+  describe '#am_i_aware_of' do
+    it 'returns aware: true for focused items' do
+      model.focus_on(target: :task, domain: :work, reason: 'r', source: :s)
+      result = model.am_i_aware_of(target: :task)
+      expect(result[:aware]).to be true
+      expect(result[:awareness_level]).to be > 0
+    end
+
+    it 'returns aware: false for unknown targets' do
+      result = model.am_i_aware_of(target: :unknown)
+      expect(result[:aware]).to be false
+      expect(result[:awareness_level]).to eq(0.0)
+      expect(result[:label]).to eq(:unconscious)
+    end
+  end
+
+  describe '#attention_state' do
+    it 'returns :distracted when empty' do
+      expect(model.attention_state).to eq(:distracted)
+    end
+
+    it 'returns :focused with a moderate item' do
+      model.focus_on(target: :task, domain: :work, reason: 'r', source: :s)
+      model.schema_items['task'].awareness_level = 0.7
+      expect(model.attention_state).to eq(:focused)
+    end
+
+    it 'returns :hyperfocused with high awareness' do
+      model.focus_on(target: :task, domain: :work, reason: 'r', source: :s)
+      model.schema_items['task'].awareness_level = 0.9
+      expect(model.attention_state).to eq(:hyperfocused)
+    end
+
+    it 'returns :drifting when average is low with few items' do
+      model.focus_on(target: :task, domain: :work, reason: 'r', source: :s)
+      model.schema_items['task'].awareness_level = 0.15
+      expect(model.attention_state).to eq(:drifting)
+    end
+
+    it 'returns :distracted with many low-awareness items' do
+      5.times { |i| model.focus_on(target: "t_#{i}", domain: :d, reason: :r, source: :s) }
+      model.schema_items.each_value { |v| v.awareness_level = 0.15 }
+      expect(model.attention_state).to eq(:distracted)
+    end
+  end
+
+  describe '#report_awareness' do
+    it 'reports no items when empty' do
+      report = model.report_awareness
+      expect(report[:state]).to eq(:distracted)
+      expect(report[:items]).to be_empty
+      expect(report[:report]).to include('No active')
+    end
+
+    it 'generates summary with items' do
+      model.focus_on(target: :task, domain: :work, reason: 'priority', source: :external)
+      report = model.report_awareness
+      expect(report[:report]).to include('task')
+      expect(report[:items].size).to eq(1)
+    end
+
+    it 'includes secondary items in report' do
+      model.focus_on(target: :a, domain: :work, reason: 'r', source: :s)
+      model.focus_on(target: :b, domain: :play, reason: 'r', source: :s)
+      report = model.report_awareness
+      expect(report[:items].size).to eq(2)
+      expect(report[:report]).to include('Also attending to')
+    end
+  end
+
+  describe '#model_other_attention' do
+    it 'records another agent attention model' do
+      model.model_other_attention(agent_id: :agent_a, target: :task, awareness: 0.8)
+      result = model.query_other_attention(agent_id: :agent_a)
+      expect(result[:target]).to eq('task')
+      expect(result[:awareness]).to eq(0.8)
+    end
+
+    it 'clamps awareness' do
+      model.model_other_attention(agent_id: :agent_a, target: :task, awareness: 1.5)
+      result = model.query_other_attention(agent_id: :agent_a)
+      expect(result[:awareness]).to eq(1.0)
+    end
+
+    it 'returns nil for unknown agent' do
+      expect(model.query_other_attention(agent_id: :unknown)).to be_nil
+    end
+
+    it 'prunes oldest social model when full' do
+      constants::MAX_SOCIAL_MODELS.times do |i|
+        model.model_other_attention(agent_id: "agent_#{i}", target: :t, awareness: 0.5)
+      end
+      model.model_other_attention(agent_id: :overflow, target: :t, awareness: 0.5)
+      expect(model.social_models.size).to eq(constants::MAX_SOCIAL_MODELS)
+    end
+  end
+
+  describe '#meta_check' do
+    it 'returns meta-attention state' do
+      result = model.meta_check
+      expect(result).to include(:state, :signals, :top_awareness, :avg_awareness, :schema_size, :meta_accuracy)
+    end
+
+    it 'includes :drifting signal when distracted' do
+      result = model.meta_check
+      expect(result[:signals]).to include(:drifting)
+    end
+
+    it 'includes :hyperfocus signal when hyperfocused' do
+      model.focus_on(target: :task, domain: :work, reason: 'r', source: :s)
+      model.schema_items['task'].awareness_level = 0.9
+      result = model.meta_check
+      expect(result[:signals]).to include(:hyperfocus)
+    end
+
+    it 'includes :normal when state is normal' do
+      model.focus_on(target: :task, domain: :work, reason: 'r', source: :s)
+      model.schema_items['task'].awareness_level = 0.5
+      result = model.meta_check
+      expect(result[:signals]).to include(:normal)
+    end
+  end
+
+  describe '#update_meta_accuracy' do
+    it 'increases accuracy when correct' do
+      before = model.meta_accuracy
+      model.update_meta_accuracy(was_correct: true)
+      expect(model.meta_accuracy).to be > before
+    end
+
+    it 'decreases accuracy when incorrect' do
+      before = model.meta_accuracy
+      model.update_meta_accuracy(was_correct: false)
+      expect(model.meta_accuracy).to be < before
+    end
+  end
+
+  describe '#decay_all' do
+    it 'decays all items' do
+      model.focus_on(target: :task, domain: :work, reason: 'r', source: :s)
+      before = model.schema_items['task'].awareness_level
+      model.decay_all
+      expect(model.schema_items['task']&.awareness_level || 0).to be < before
+    end
+
+    it 'prunes faded items' do
+      model.focus_on(target: :task, domain: :work, reason: 'r', source: :s)
+      model.schema_items['task'].awareness_level = constants::AWARENESS_FLOOR + 0.01
+      model.decay_all
+      expect(model.schema_size).to eq(0)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns stats hash' do
+      model.focus_on(target: :task, domain: :work, reason: 'r', source: :s)
+      h = model.to_h
+      expect(h).to include(:state, :state_label, :schema_size, :meta_accuracy, :top_awareness, :avg_awareness, :social_models, :items)
+      expect(h[:schema_size]).to eq(1)
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/schema/helpers/schema_item_spec.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Schema::Helpers::SchemaItem do
+  subject(:item) do
+    described_class.new(target: 'task_queue', domain: :work, reason: 'priority', source: :external)
+  end
+
+  let(:constants) { Legion::Extensions::Agentic::Attention::Schema::Helpers::Constants }
+
+  describe '#initialize' do
+    it 'sets attributes' do
+      expect(item.target).to eq('task_queue')
+      expect(item.domain).to eq(:work)
+      expect(item.reason).to eq('priority')
+      expect(item.source).to eq(:external)
+    end
+
+    it 'uses default awareness level' do
+      expect(item.awareness_level).to eq(constants::DEFAULT_AWARENESS)
+    end
+
+    it 'clamps awareness to 0..1' do
+      high = described_class.new(target: :x, domain: :d, reason: :r, source: :s, awareness_level: 1.5)
+      low  = described_class.new(target: :y, domain: :d, reason: :r, source: :s, awareness_level: -0.5)
+      expect(high.awareness_level).to eq(1.0)
+      expect(low.awareness_level).to eq(0.0)
+    end
+
+    it 'records created_at' do
+      expect(item.created_at).to be_a(Time)
+    end
+  end
+
+  describe '#duration' do
+    it 'returns elapsed time' do
+      expect(item.duration).to be >= 0.0
+    end
+  end
+
+  describe '#boost' do
+    it 'increases awareness by AWARENESS_BOOST' do
+      before = item.awareness_level
+      item.boost
+      expect(item.awareness_level).to eq(before + constants::AWARENESS_BOOST)
+    end
+
+    it 'caps at 1.0' do
+      item.awareness_level = 0.95
+      item.boost
+      expect(item.awareness_level).to eq(1.0)
+    end
+  end
+
+  describe '#decay' do
+    it 'decreases awareness by AWARENESS_DECAY' do
+      item.awareness_level = 0.5
+      item.decay
+      expect(item.awareness_level).to eq(0.5 - constants::AWARENESS_DECAY)
+    end
+
+    it 'does not drop below AWARENESS_FLOOR' do
+      item.awareness_level = constants::AWARENESS_FLOOR + 0.001
+      item.decay
+      expect(item.awareness_level).to eq(constants::AWARENESS_FLOOR)
+    end
+  end
+
+  describe '#faded?' do
+    it 'returns true at floor' do
+      item.awareness_level = constants::AWARENESS_FLOOR
+      expect(item.faded?).to be true
+    end
+
+    it 'returns false above floor' do
+      item.awareness_level = constants::AWARENESS_FLOOR + 0.01
+      expect(item.faded?).to be false
+    end
+  end
+
+  describe '#label' do
+    it 'returns :vivid for high awareness' do
+      item.awareness_level = 0.9
+      expect(item.label).to eq(:vivid)
+    end
+
+    it 'returns :unconscious for very low awareness' do
+      item.awareness_level = 0.1
+      expect(item.label).to eq(:unconscious)
+    end
+
+    it 'returns :clear for mid-high awareness' do
+      item.awareness_level = 0.7
+      expect(item.label).to eq(:clear)
+    end
+
+    it 'returns :dim for mid awareness' do
+      item.awareness_level = 0.5
+      expect(item.label).to eq(:dim)
+    end
+
+    it 'returns :peripheral for low awareness' do
+      item.awareness_level = 0.25
+      expect(item.label).to eq(:peripheral)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns hash with all fields' do
+      h = item.to_h
+      expect(h).to include(:target, :domain, :awareness_level, :label, :reason, :source, :duration, :created_at)
+      expect(h[:target]).to eq('task_queue')
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/schema/runners/attention_schema_spec.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Schema::Runners::AttentionSchema do
+  let(:client) { Legion::Extensions::Agentic::Attention::Schema::Client.new }
+
+  describe '#focus_on' do
+    it 'focuses on a target' do
+      result = client.focus_on(target: :task, domain: :work, reason: 'priority', source: :external)
+      expect(result[:success]).to be true
+      expect(result[:target]).to eq('task')
+      expect(result[:awareness_level]).to be > 0
+      expect(result[:label]).to be_a(Symbol)
+    end
+
+    it 'boosts on re-focus' do
+      first = client.focus_on(target: :task, domain: :work, reason: 'r', source: :s)
+      second = client.focus_on(target: :task, domain: :work, reason: 'r', source: :s)
+      expect(second[:awareness_level]).to be > first[:awareness_level]
+    end
+  end
+
+  describe '#defocus' do
+    it 'removes a target' do
+      client.focus_on(target: :task, domain: :work, reason: 'r', source: :s)
+      result = client.defocus(target: :task)
+      expect(result[:success]).to be true
+      expect(result[:removed]).to be true
+    end
+
+    it 'returns removed: false for unknown' do
+      result = client.defocus(target: :missing)
+      expect(result[:removed]).to be false
+    end
+  end
+
+  describe '#am_i_aware_of' do
+    it 'returns aware: true for focused target' do
+      client.focus_on(target: :task, domain: :work, reason: 'r', source: :s)
+      result = client.am_i_aware_of(target: :task)
+      expect(result[:success]).to be true
+      expect(result[:aware]).to be true
+    end
+
+    it 'returns aware: false for unknown target' do
+      result = client.am_i_aware_of(target: :unknown)
+      expect(result[:aware]).to be false
+    end
+  end
+
+  describe '#report_awareness' do
+    it 'returns awareness report' do
+      client.focus_on(target: :task, domain: :work, reason: 'priority', source: :external)
+      result = client.report_awareness
+      expect(result[:success]).to be true
+      expect(result[:report]).to be_a(String)
+      expect(result[:items]).to be_an(Array)
+    end
+  end
+
+  describe '#attention_state' do
+    it 'returns current state' do
+      result = client.attention_state
+      expect(result[:success]).to be true
+      expect(result[:state]).to be_a(Symbol)
+      expect(result[:label]).to be_a(String)
+    end
+  end
+
+  describe '#model_other_attention' do
+    it 'records other agent attention' do
+      result = client.model_other_attention(agent_id: :agent_a, target: :task, awareness: 0.8)
+      expect(result[:success]).to be true
+      expect(result[:agent_id]).to eq(:agent_a)
+    end
+  end
+
+  describe '#query_other_attention' do
+    it 'queries modeled attention' do
+      client.model_other_attention(agent_id: :agent_a, target: :task, awareness: 0.8)
+      result = client.query_other_attention(agent_id: :agent_a)
+      expect(result[:success]).to be true
+      expect(result[:model]).not_to be_nil
+    end
+
+    it 'returns nil model for unknown agent' do
+      result = client.query_other_attention(agent_id: :unknown)
+      expect(result[:model]).to be_nil
+    end
+  end
+
+  describe '#meta_check' do
+    it 'returns meta-attention signals' do
+      result = client.meta_check
+      expect(result[:success]).to be true
+      expect(result[:state]).to be_a(Symbol)
+      expect(result[:signals]).to be_an(Array)
+    end
+  end
+
+  describe '#update_meta_accuracy' do
+    it 'updates meta-accuracy with feedback' do
+      result = client.update_meta_accuracy(was_correct: true)
+      expect(result[:success]).to be true
+      expect(result[:meta_accuracy]).to be > 0.5
+    end
+  end
+
+  describe '#decay_schema' do
+    it 'decays and reports' do
+      client.focus_on(target: :task, domain: :work, reason: 'r', source: :s)
+      result = client.decay_schema
+      expect(result[:success]).to be true
+      expect(result[:before]).to eq(1)
+      expect(result).to have_key(:after)
+      expect(result).to have_key(:pruned)
+    end
+  end
+
+  describe '#schema_stats' do
+    it 'returns stats hash' do
+      result = client.schema_stats
+      expect(result[:success]).to be true
+      expect(result[:stats]).to include(:state, :schema_size, :meta_accuracy)
+    end
+
+    it 'reports zero schema_size when empty' do
+      result = client.schema_stats
+      expect(result[:stats][:schema_size]).to eq(0)
+    end
+
+    it 'includes items array in stats' do
+      client.focus_on(target: :task, domain: :work, reason: 'r', source: :s)
+      result = client.schema_stats
+      expect(result[:stats][:items]).to be_an(Array)
+      expect(result[:stats][:items].size).to eq(1)
+    end
+  end
+
+  describe '#focus_on schema_size tracking' do
+    it 'tracks schema_size correctly through multiple targets' do
+      client.focus_on(target: :a, domain: :d, reason: 'r', source: :s)
+      r2 = client.focus_on(target: :b, domain: :d, reason: 'r', source: :s)
+      r3 = client.focus_on(target: :c, domain: :d, reason: 'r', source: :s)
+      expect(r2[:schema_size]).to eq(2)
+      expect(r3[:schema_size]).to eq(3)
+    end
+  end
+
+  describe '#report_awareness empty state' do
+    it 'returns empty items when nothing focused' do
+      result = client.report_awareness
+      expect(result[:items]).to be_empty
+    end
+
+    it 'includes state_label string' do
+      result = client.report_awareness
+      expect(result[:state_label]).to be_a(String)
+    end
+  end
+
+  describe '#meta_check state labeling' do
+    it 'returns :distracted state with empty schema' do
+      result = client.meta_check
+      expect(result[:state]).to eq(:distracted)
+    end
+
+    it 'returns numeric top_awareness and avg_awareness' do
+      result = client.meta_check
+      expect(result[:top_awareness]).to be_a(Float)
+      expect(result[:avg_awareness]).to be_a(Float)
+    end
+  end
+
+  describe '#update_meta_accuracy boundary behavior' do
+    it 'correct=false reduces meta_accuracy below initial' do
+      result = client.update_meta_accuracy(was_correct: false)
+      expect(result[:meta_accuracy]).to be < 0.5
+    end
+
+    it 'returns the was_correct value echoed back' do
+      result = client.update_meta_accuracy(was_correct: false)
+      expect(result[:was_correct]).to be false
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/sensory_gating/helpers/gating_engine_spec.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::SensoryGating::Helpers::GatingEngine do
+  subject(:engine) { described_class.new }
+
+  let(:filter) { engine.create_filter(modality: :visual) }
+
+  describe '#create_filter' do
+    it 'returns a SensoryFilter' do
+      expect(filter).to be_a(Legion::Extensions::Agentic::Attention::SensoryGating::Helpers::SensoryFilter)
+    end
+
+    it 'stores the filter' do
+      filter
+      expect(engine.to_h[:total_filters]).to eq(1)
+    end
+  end
+
+  describe '#process_stimulus' do
+    it 'returns outcome and filter' do
+      result = engine.process_stimulus(filter_id: filter.id, intensity: 0.9)
+      expect(result[:outcome]).to eq(:passed)
+    end
+
+    it 'returns nil for unknown id' do
+      expect(engine.process_stimulus(filter_id: 'fake', intensity: 0.5)).to be_nil
+    end
+  end
+
+  describe '#open_gate' do
+    it 'decreases filter threshold' do
+      original = filter.gate_threshold
+      engine.open_gate(filter_id: filter.id)
+      expect(filter.gate_threshold).to be < original
+    end
+  end
+
+  describe '#close_gate' do
+    it 'increases filter threshold' do
+      original = filter.gate_threshold
+      engine.close_gate(filter_id: filter.id)
+      expect(filter.gate_threshold).to be > original
+    end
+  end
+
+  describe '#sensitize' do
+    it 'returns the filter' do
+      result = engine.sensitize(filter_id: filter.id)
+      expect(result).to eq(filter)
+    end
+  end
+
+  describe '#reset_habituation' do
+    it 'resets habituation' do
+      engine.process_stimulus(filter_id: filter.id, intensity: 0.9)
+      engine.reset_habituation(filter_id: filter.id)
+      expect(filter.habituation_level).to eq(0.0)
+    end
+  end
+
+  describe '#filters_by_modality' do
+    it 'filters by modality' do
+      engine.create_filter(modality: :auditory)
+      filter
+      result = engine.filters_by_modality(modality: :auditory)
+      expect(result.size).to eq(1)
+    end
+  end
+
+  describe '#average_pass_rate' do
+    it 'returns 0.0 with no filters' do
+      fresh = described_class.new
+      expect(fresh.average_pass_rate).to eq(0.0)
+    end
+  end
+
+  describe '#most_restrictive' do
+    it 'returns filters sorted by threshold descending' do
+      engine.create_filter(modality: :visual, gate_threshold: 0.3)
+      engine.create_filter(modality: :auditory, gate_threshold: 0.8)
+      restrictive = engine.most_restrictive(limit: 1)
+      expect(restrictive.first.gate_threshold).to eq(0.8)
+    end
+  end
+
+  describe '#gating_report' do
+    it 'includes all report fields' do
+      filter
+      report = engine.gating_report
+      expect(report).to include(
+        :total_filters, :average_pass_rate,
+        :most_restrictive, :most_permissive
+      )
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes summary fields' do
+      hash = engine.to_h
+      expect(hash).to include(:total_filters, :average_pass_rate)
+    end
+  end
+
+  describe 'pruning' do
+    it 'prunes oldest filter when limit reached' do
+      stub_const('Legion::Extensions::Agentic::Attention::SensoryGating::Helpers::Constants::MAX_FILTERS', 3)
+      eng = described_class.new
+      4.times { |i| eng.create_filter(modality: :"mod#{i}") }
+      expect(eng.to_h[:total_filters]).to eq(3)
+    end
+  end
+end