lex-agentic-attention 0.1.0

data/spec/legion/extensions/agentic/attention/regulation/runners/attention_regulation_spec.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Regulation::Runners::AttentionRegulation do
+  let(:runner) do
+    obj = Object.new
+    obj.extend(described_class)
+    obj
+  end
+
+  describe '#add_attention_target' do
+    it 'creates a target and returns success' do
+      result = runner.add_attention_target(name: 'email', domain: :work, salience: 0.4)
+      expect(result[:success]).to be true
+      expect(result[:target_id]).to be_a(Symbol)
+      expect(result[:name]).to eq('email')
+    end
+
+    it 'returns failure when limit is reached' do
+      30.times { |i| runner.add_attention_target(name: "target #{i}", salience: 0.3) }
+      result = runner.add_attention_target(name: 'overflow', salience: 0.5)
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:limit_reached)
+    end
+  end
+
+  describe '#focus_attention' do
+    it 'focuses on a known target' do
+      created = runner.add_attention_target(name: 'task', salience: 0.5)
+      result = runner.focus_attention(target_id: created[:target_id])
+      expect(result[:success]).to be true
+      expect(result[:mode]).to eq(:focused)
+    end
+
+    it 'returns failure for unknown target' do
+      result = runner.focus_attention(target_id: :bogus)
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:not_found)
+    end
+  end
+
+  describe '#defocus_attention' do
+    it 'defocuses and returns success' do
+      result = runner.defocus_attention
+      expect(result[:success]).to be true
+      expect(result[:mode]).to eq(:diffuse)
+    end
+  end
+
+  describe '#scan_attention' do
+    it 'returns success with scanning mode when nothing captures' do
+      runner.add_attention_target(name: 'low', salience: 0.2)
+      result = runner.scan_attention
+      expect(result[:success]).to be true
+      expect(result[:mode]).to eq(:scanning)
+    end
+
+    it 'includes captured_target_id when a target is captured' do
+      runner.add_attention_target(name: 'urgent', salience: 0.9)
+      result = runner.scan_attention
+      expect(result[:success]).to be true
+      expect(result[:captured_target_id]).to be_a(Symbol)
+    end
+  end
+
+  describe '#rest_attention' do
+    it 'returns success with resting mode' do
+      result = runner.rest_attention
+      expect(result[:success]).to be true
+      expect(result[:mode]).to eq(:resting)
+    end
+  end
+
+  describe '#zoom_attention_in' do
+    it 'increases zoom and returns success' do
+      result = runner.zoom_attention_in(amount: 0.1)
+      expect(result[:success]).to be true
+      expect(result[:zoom]).to be > 0.5
+    end
+
+    it 'uses default amount' do
+      result = runner.zoom_attention_in
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#zoom_attention_out' do
+    it 'decreases zoom and returns success' do
+      result = runner.zoom_attention_out(amount: 0.1)
+      expect(result[:success]).to be true
+      expect(result[:zoom]).to be < 0.5
+    end
+
+    it 'uses default amount' do
+      result = runner.zoom_attention_out
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#current_attention_target' do
+    it 'returns target: nil when not focused' do
+      result = runner.current_attention_target
+      expect(result[:success]).to be true
+      expect(result[:target]).to be_nil
+    end
+
+    it 'returns current target when focused' do
+      created = runner.add_attention_target(name: 'active', salience: 0.5)
+      runner.focus_attention(target_id: created[:target_id])
+      result = runner.current_attention_target
+      expect(result[:success]).to be true
+      expect(result[:target]).to be_a(Hash)
+      expect(result[:target][:name]).to eq('active')
+    end
+  end
+
+  describe '#most_salient_target' do
+    it 'returns target: nil when no targets' do
+      result = runner.most_salient_target
+      expect(result[:success]).to be true
+      expect(result[:target]).to be_nil
+    end
+
+    it 'returns the most salient target' do
+      runner.add_attention_target(name: 'low', salience: 0.2)
+      runner.add_attention_target(name: 'high', salience: 0.8)
+      result = runner.most_salient_target
+      expect(result[:success]).to be true
+      expect(result[:target][:name]).to eq('high')
+    end
+  end
+
+  describe '#update_attention' do
+    it 'ticks and returns stats' do
+      result = runner.update_attention
+      expect(result[:success]).to be true
+      expect(result).to include(:mode, :zoom, :resource, :resource_label)
+    end
+  end
+
+  describe '#attention_regulation_stats' do
+    it 'returns stats hash' do
+      result = runner.attention_regulation_stats
+      expect(result[:success]).to be true
+      expect(result).to include(:mode, :target_count)
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/relevance_theory/helpers/cognitive_input_spec.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::RelevanceTheory::Helpers::CognitiveInput do
+  subject(:input) do
+    described_class.new(content: 'test input', input_type: :assertion, context: :general)
+  end
+
+  describe '#initialize' do
+    it 'creates with defaults' do
+      expect(input.content).to eq('test input')
+      expect(input.input_type).to eq(:assertion)
+      expect(input.context).to eq(:general)
+      expect(input.cognitive_effect).to eq(0.5)
+      expect(input.processing_effort).to eq(0.5)
+    end
+
+    it 'generates a uuid' do
+      expect(input.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'clamps effect and effort' do
+      clamped = described_class.new(content: 'x', input_type: :assertion, context: :c,
+                                    cognitive_effect: 5.0, processing_effort: -1.0)
+      expect(clamped.cognitive_effect).to eq(1.0)
+      expect(clamped.processing_effort).to eq(0.01)
+    end
+  end
+
+  describe '#relevance' do
+    it 'returns effect / effort' do
+      expect(input.relevance).to eq(1.0)
+    end
+
+    it 'is higher when effect is high and effort is low' do
+      high_rel = described_class.new(content: 'x', input_type: :assertion, context: :c,
+                                     cognitive_effect: 0.9, processing_effort: 0.1)
+      expect(high_rel.relevance).to eq(9.0)
+    end
+  end
+
+  describe '#normalized_relevance' do
+    it 'clamps to 0..1' do
+      high = described_class.new(content: 'x', input_type: :assertion, context: :c,
+                                 cognitive_effect: 0.9, processing_effort: 0.1)
+      expect(high.normalized_relevance).to eq(1.0)
+    end
+  end
+
+  describe '#relevance_label' do
+    it 'returns a symbol' do
+      expect(input.relevance_label).to be_a(Symbol)
+    end
+
+    it 'returns :maximally_relevant for high relevance' do
+      high = described_class.new(content: 'x', input_type: :assertion, context: :c,
+                                 cognitive_effect: 0.9, processing_effort: 0.1)
+      expect(high.relevance_label).to eq(:maximally_relevant)
+    end
+
+    it 'returns :irrelevant for low relevance' do
+      low = described_class.new(content: 'x', input_type: :assertion, context: :c,
+                                cognitive_effect: 0.05, processing_effort: 0.9)
+      expect(low.relevance_label).to eq(:irrelevant)
+    end
+  end
+
+  describe '#worth_processing?' do
+    it 'is true when normalized_relevance >= threshold' do
+      expect(input.worth_processing?).to be true
+    end
+
+    it 'is false when relevance is too low' do
+      low = described_class.new(content: 'x', input_type: :assertion, context: :c,
+                                cognitive_effect: 0.05, processing_effort: 0.9)
+      expect(low.worth_processing?).to be false
+    end
+  end
+
+  describe '#strengthen!' do
+    it 'increases cognitive effect' do
+      old_effect = input.cognitive_effect
+      input.strengthen!(amount: 0.1)
+      expect(input.cognitive_effect).to be > old_effect
+    end
+  end
+
+  describe '#weaken!' do
+    it 'decreases cognitive effect' do
+      old_effect = input.cognitive_effect
+      input.weaken!(amount: 0.1)
+      expect(input.cognitive_effect).to be < old_effect
+    end
+  end
+
+  describe '#increase_effort!' do
+    it 'increases processing effort' do
+      old_effort = input.processing_effort
+      input.increase_effort!(amount: 0.1)
+      expect(input.processing_effort).to be > old_effort
+    end
+  end
+
+  describe '#decay!' do
+    it 'reduces effect and increases effort' do
+      old_effect = input.cognitive_effect
+      old_effort = input.processing_effort
+      input.decay!
+      expect(input.cognitive_effect).to be < old_effect
+      expect(input.processing_effort).to be > old_effort
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a complete hash' do
+      hash = input.to_h
+      expect(hash).to include(:id, :content, :input_type, :context, :cognitive_effect,
+                              :processing_effort, :relevance, :normalized, :relevance_label,
+                              :worth_processing, :effect_type)
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/relevance_theory/helpers/relevance_engine_spec.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::RelevanceTheory::Helpers::RelevanceEngine do
+  subject(:engine) { described_class.new }
+
+  let(:input) { engine.submit_input(content: 'test', input_type: :assertion, context: :general) }
+
+  describe '#submit_input' do
+    it 'creates and stores an input' do
+      result = engine.submit_input(content: 'hello', input_type: :observation, context: :work)
+      expect(result).to be_a(Legion::Extensions::Agentic::Attention::RelevanceTheory::Helpers::CognitiveInput)
+      expect(result.content).to eq('hello')
+    end
+
+    it 'records history' do
+      engine.submit_input(content: 'x', input_type: :assertion, context: :c)
+      expect(engine.history.last[:event]).to eq(:submitted)
+    end
+  end
+
+  describe '#assess_relevance' do
+    it 'assesses an existing input' do
+      result = engine.assess_relevance(input_id: input.id)
+      expect(result[:success]).to be true
+      expect(result[:relevance]).to be_a(Float)
+      expect(result[:label]).to be_a(Symbol)
+    end
+
+    it 'returns not_found for missing input' do
+      result = engine.assess_relevance(input_id: 'missing')
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#strengthen_input' do
+    it 'strengthens an existing input' do
+      old_relevance = input.normalized_relevance
+      result = engine.strengthen_input(input_id: input.id, amount: 0.2)
+      expect(result[:success]).to be true
+      expect(result[:relevance]).to be >= old_relevance
+    end
+  end
+
+  describe '#weaken_input' do
+    it 'weakens an existing input' do
+      result = engine.weaken_input(input_id: input.id, amount: 0.2)
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#worth_processing' do
+    it 'returns inputs above attention threshold' do
+      engine.submit_input(content: 'high', input_type: :assertion, context: :c,
+                          cognitive_effect: 0.9, processing_effort: 0.1)
+      engine.submit_input(content: 'low', input_type: :assertion, context: :c,
+                          cognitive_effect: 0.01, processing_effort: 0.9)
+      expect(engine.worth_processing.size).to eq(1)
+    end
+  end
+
+  describe '#irrelevant_inputs' do
+    it 'returns inputs below attention threshold' do
+      engine.submit_input(content: 'low', input_type: :assertion, context: :c,
+                          cognitive_effect: 0.01, processing_effort: 0.9)
+      expect(engine.irrelevant_inputs.size).to eq(1)
+    end
+  end
+
+  describe '#most_relevant' do
+    it 'returns inputs sorted by relevance desc' do
+      engine.submit_input(content: 'low', input_type: :assertion, context: :c,
+                          cognitive_effect: 0.2, processing_effort: 0.8)
+      high = engine.submit_input(content: 'high', input_type: :assertion, context: :c,
+                                 cognitive_effect: 0.9, processing_effort: 0.1)
+      result = engine.most_relevant(limit: 2)
+      expect(result.first).to eq(high)
+    end
+  end
+
+  describe '#by_context' do
+    it 'filters by context' do
+      engine.submit_input(content: 'a', input_type: :assertion, context: :work)
+      engine.submit_input(content: 'b', input_type: :assertion, context: :play)
+      expect(engine.by_context(context: :work).size).to eq(1)
+    end
+  end
+
+  describe '#by_effect_type' do
+    it 'filters by effect type' do
+      engine.submit_input(content: 'a', input_type: :assertion, context: :c,
+                          effect_type: :strengthening)
+      engine.submit_input(content: 'b', input_type: :assertion, context: :c,
+                          effect_type: :contradiction)
+      expect(engine.by_effect_type(effect_type: :strengthening).size).to eq(1)
+    end
+  end
+
+  describe '#context_relevance' do
+    it 'returns average relevance for context' do
+      engine.submit_input(content: 'a', input_type: :assertion, context: :work,
+                          cognitive_effect: 0.8, processing_effort: 0.2)
+      score = engine.context_relevance(context: :work)
+      expect(score).to be > 0
+    end
+
+    it 'returns 0.0 for empty context' do
+      expect(engine.context_relevance(context: :nonexistent)).to eq(0.0)
+    end
+  end
+
+  describe '#attention_budget' do
+    it 'returns budget stats' do
+      engine.submit_input(content: 'x', input_type: :assertion, context: :c)
+      budget = engine.attention_budget
+      expect(budget).to include(:total_inputs, :worth_processing, :filtered_out,
+                                :processing_ratio, :avg_relevance)
+    end
+  end
+
+  describe '#decay_all' do
+    it 'reduces relevance of all inputs' do
+      input
+      old_relevance = input.normalized_relevance
+      engine.decay_all
+      expect(input.normalized_relevance).to be <= old_relevance
+    end
+  end
+
+  describe '#prune_irrelevant' do
+    it 'removes very low relevance inputs' do
+      engine.submit_input(content: 'low', input_type: :assertion, context: :c,
+                          cognitive_effect: 0.01, processing_effort: 0.9)
+      expect(engine.prune_irrelevant).to eq(1)
+    end
+
+    it 'does not prune relevant inputs' do
+      input
+      expect(engine.prune_irrelevant).to eq(0)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns stats hash' do
+      input
+      stats = engine.to_h
+      expect(stats).to include(:total_inputs, :processable, :avg_relevance, :history_count)
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/relevance_theory/relevance_theory_spec.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::RelevanceTheory do
+  it 'has a version number' do
+    expect(Legion::Extensions::Agentic::Attention::RelevanceTheory::VERSION).not_to be_nil
+  end
+
+  it 'has a version that is a string' do
+    expect(Legion::Extensions::Agentic::Attention::RelevanceTheory::VERSION).to be_a(String)
+  end
+end

data/spec/legion/extensions/agentic/attention/relevance_theory/runners/relevance_theory_spec.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::RelevanceTheory::Runners::RelevanceTheory do
+  let(:client) { Legion::Extensions::Agentic::Attention::RelevanceTheory::Helpers::Client.new }
+
+  describe '#submit_relevance_input' do
+    it 'submits an input' do
+      result = client.submit_relevance_input(content: 'test', input_type: :assertion, context: :work)
+      expect(result[:success]).to be true
+      expect(result[:input][:content]).to eq('test')
+    end
+  end
+
+  describe '#assess_input_relevance' do
+    it 'assesses an input' do
+      created = client.submit_relevance_input(content: 'x', input_type: :assertion, context: :c)
+      result = client.assess_input_relevance(input_id: created[:input][:id])
+      expect(result[:success]).to be true
+      expect(result[:label]).to be_a(Symbol)
+    end
+  end
+
+  describe '#strengthen_relevance' do
+    it 'strengthens an input' do
+      created = client.submit_relevance_input(content: 'x', input_type: :assertion, context: :c)
+      result = client.strengthen_relevance(input_id: created[:input][:id])
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#weaken_relevance' do
+    it 'weakens an input' do
+      created = client.submit_relevance_input(content: 'x', input_type: :assertion, context: :c)
+      result = client.weaken_relevance(input_id: created[:input][:id])
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#worth_processing_report' do
+    it 'returns processable inputs' do
+      result = client.worth_processing_report
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#most_relevant_inputs' do
+    it 'returns top relevant inputs' do
+      client.submit_relevance_input(content: 'a', input_type: :assertion, context: :c)
+      result = client.most_relevant_inputs(limit: 3)
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#context_relevance_report' do
+    it 'returns context relevance score' do
+      client.submit_relevance_input(content: 'a', input_type: :assertion, context: :work)
+      result = client.context_relevance_report(context: :work)
+      expect(result[:success]).to be true
+      expect(result[:relevance]).to be_a(Float)
+    end
+  end
+
+  describe '#attention_budget_report' do
+    it 'returns attention budget stats' do
+      result = client.attention_budget_report
+      expect(result[:success]).to be true
+      expect(result).to include(:total_inputs, :processing_ratio)
+    end
+  end
+
+  describe '#update_relevance_theory' do
+    it 'decays and prunes' do
+      result = client.update_relevance_theory
+      expect(result[:success]).to be true
+      expect(result).to have_key(:pruned)
+    end
+  end
+
+  describe '#relevance_theory_stats' do
+    it 'returns stats' do
+      result = client.relevance_theory_stats
+      expect(result[:success]).to be true
+      expect(result).to include(:total_inputs, :processable)
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Salience::Client do
+  subject(:client) { described_class.new }
+
+  describe '#initialize' do
+    it 'creates a default SalienceMap' do
+      expect(client.salience_map).to be_a(Legion::Extensions::Agentic::Attention::Salience::Helpers::SalienceMap)
+    end
+
+    it 'accepts an injected salience_map' do
+      custom_map = Legion::Extensions::Agentic::Attention::Salience::Helpers::SalienceMap.new
+      injected   = described_class.new(salience_map: custom_map)
+      expect(injected.salience_map).to be(custom_map)
+    end
+  end
+
+  describe 'runner method delegation' do
+    it 'responds to compute_salience' do
+      expect(client).to respond_to(:compute_salience)
+    end
+
+    it 'responds to salience_status' do
+      expect(client).to respond_to(:salience_status)
+    end
+
+    it 'responds to salience_for' do
+      expect(client).to respond_to(:salience_for)
+    end
+
+    it 'responds to salience_history' do
+      expect(client).to respond_to(:salience_history)
+    end
+
+    it 'responds to salience_stats' do
+      expect(client).to respond_to(:salience_stats)
+    end
+  end
+
+  describe 'stateful behavior' do
+    it 'accumulates history across multiple calls' do
+      client.compute_salience(tick_results: {})
+      client.compute_salience(tick_results: { emotion: { arousal: 0.5 } })
+      expect(client.salience_map.history.size).to eq(2)
+    end
+
+    it 'uses the same salience_map instance across calls' do
+      map_before = client.salience_map
+      client.compute_salience(tick_results: {})
+      expect(client.salience_map).to be(map_before)
+    end
+
+    it 'two clients have independent state' do
+      client1 = described_class.new
+      client2 = described_class.new
+      client1.compute_salience(tick_results: { emotion: { arousal: 0.9 } })
+      expect(client2.salience_map.history.size).to eq(0)
+    end
+  end
+end

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

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Salience::Helpers::Constants do
+  describe 'SALIENCE_SOURCES' do
+    it 'defines exactly 8 sources' do
+      expect(described_class::SALIENCE_SOURCES.size).to eq(8)
+    end
+
+    it 'includes all expected sources' do
+      %i[emotion mood attention curiosity homeostasis trust empathy volition].each do |source|
+        expect(described_class::SALIENCE_SOURCES).to include(source)
+      end
+    end
+
+    it 'is frozen' do
+      expect(described_class::SALIENCE_SOURCES).to be_frozen
+    end
+  end
+
+  describe 'SOURCE_WEIGHTS' do
+    it 'has a weight for every source' do
+      described_class::SALIENCE_SOURCES.each do |source|
+        expect(described_class::SOURCE_WEIGHTS).to have_key(source)
+      end
+    end
+
+    it 'weights sum to 1.0' do
+      total = described_class::SOURCE_WEIGHTS.values.sum
+      expect(total).to be_within(0.001).of(1.0)
+    end
+
+    it 'assigns emotion the highest weight' do
+      expect(described_class::SOURCE_WEIGHTS[:emotion]).to eq(0.20)
+    end
+
+    it 'is frozen' do
+      expect(described_class::SOURCE_WEIGHTS).to be_frozen
+    end
+  end
+
+  describe 'URGENCY_LEVELS' do
+    it 'defines exactly 5 levels' do
+      expect(described_class::URGENCY_LEVELS.size).to eq(5)
+    end
+
+    it 'includes critical, high, moderate, low, background' do
+      %i[critical high moderate low background].each do |level|
+        expect(described_class::URGENCY_LEVELS).to include(level)
+      end
+    end
+
+    it 'is frozen' do
+      expect(described_class::URGENCY_LEVELS).to be_frozen
+    end
+  end
+
+  describe 'URGENCY_THRESHOLDS' do
+    it 'has a threshold for every urgency level' do
+      described_class::URGENCY_LEVELS.each do |level|
+        expect(described_class::URGENCY_THRESHOLDS).to have_key(level)
+      end
+    end
+
+    it 'covers the full range from 0 to 1' do
+      thresholds = described_class::URGENCY_THRESHOLDS.values
+      expect(thresholds.min).to eq(0.0)
+      expect(thresholds.max).to eq(0.9)
+    end
+
+    it 'sets critical at 0.9' do
+      expect(described_class::URGENCY_THRESHOLDS[:critical]).to eq(0.9)
+    end
+
+    it 'sets background at 0.0' do
+      expect(described_class::URGENCY_THRESHOLDS[:background]).to eq(0.0)
+    end
+  end
+
+  describe 'numeric constants' do
+    it 'defines MAX_SALIENCE_ITEMS as 10' do
+      expect(described_class::MAX_SALIENCE_ITEMS).to eq(10)
+    end
+
+    it 'defines SALIENCE_DECAY_RATE as 0.05' do
+      expect(described_class::SALIENCE_DECAY_RATE).to eq(0.05)
+    end
+
+    it 'defines INTEGRATION_ALPHA as 0.3' do
+      expect(described_class::INTEGRATION_ALPHA).to eq(0.3)
+    end
+
+    it 'defines NOVELTY_BOOST as 0.2' do
+      expect(described_class::NOVELTY_BOOST).to eq(0.2)
+    end
+
+    it 'defines CONFLICT_AMPLIFIER as 1.5' do
+      expect(described_class::CONFLICT_AMPLIFIER).to eq(1.5)
+    end
+  end
+end