lex-agentic-attention 0.1.0

data/spec/legion/extensions/agentic/attention/arousal/helpers/arousal_model_spec.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Arousal::Helpers::ArousalModel do
+  let(:model) { described_class.new }
+
+  describe '#initialize' do
+    it 'starts at the default arousal level' do
+      expect(model.arousal).to be_within(0.001).of(Legion::Extensions::Agentic::Attention::Arousal::Helpers::Constants::DEFAULT_AROUSAL)
+    end
+
+    it 'starts with empty history' do
+      expect(model.arousal_history).to be_empty
+    end
+
+    it 'starts with zero performance' do
+      expect(model.performance_last).to eq(0.0)
+    end
+  end
+
+  describe '#stimulate' do
+    it 'increases arousal' do
+      before = model.arousal
+      model.stimulate(amount: 0.3, source: :test)
+      expect(model.arousal).to be > before
+    end
+
+    it 'records the source in history' do
+      model.stimulate(amount: 0.2, source: :external)
+      expect(model.arousal_history.last[:source]).to eq(:external)
+    end
+
+    it 'clamps arousal at ceiling' do
+      10.times { model.stimulate(amount: 1.0, source: :test) }
+      expect(model.arousal).to be <= 1.0
+    end
+
+    it 'returns the new arousal level' do
+      result = model.stimulate(amount: 0.2, source: :test)
+      expect(result).to eq(model.arousal)
+    end
+  end
+
+  describe '#calm' do
+    before { model.stimulate(amount: 0.5, source: :setup) }
+
+    it 'decreases arousal' do
+      before = model.arousal
+      model.calm(amount: 0.2)
+      expect(model.arousal).to be < before
+    end
+
+    it 'clamps arousal at floor' do
+      10.times { model.calm(amount: 1.0) }
+      expect(model.arousal).to be >= 0.0
+    end
+
+    it 'returns the new arousal level' do
+      result = model.calm(amount: 0.1)
+      expect(result).to eq(model.arousal)
+    end
+  end
+
+  describe '#decay' do
+    it 'moves arousal toward the default resting level from above' do
+      model.stimulate(amount: 0.5, source: :setup)
+      raised = model.arousal
+      model.decay
+      # After stimulating above default, decay should lower it (move toward default)
+      expect(model.arousal).to be < raised
+    end
+
+    it 'records a decay entry in history' do
+      model.decay
+      expect(model.arousal_history.last[:source]).to eq(:decay)
+    end
+  end
+
+  describe '#performance' do
+    it 'returns a value between 0 and 1' do
+      perf = model.performance
+      expect(perf).to be >= 0.0
+      expect(perf).to be <= 1.0
+    end
+
+    it 'returns highest performance near the optimal arousal' do
+      model.stimulate(amount: 0.2, source: :test)
+      perf_near_optimal = model.performance(task_complexity: :moderate)
+
+      model2 = described_class.new
+      10.times { model2.stimulate(amount: 0.8, source: :test) }
+      perf_far_from_optimal = model2.performance(task_complexity: :moderate)
+
+      expect(perf_near_optimal).to be >= perf_far_from_optimal
+    end
+
+    it 'uses complexity-specific optimal for simple tasks' do
+      perf_simple = model.performance(task_complexity: :simple)
+      expect(perf_simple).to be_a(Float)
+    end
+
+    it 'updates performance_last' do
+      model.performance(task_complexity: :moderate)
+      expect(model.performance_last).to be > 0.0
+    end
+  end
+
+  describe '#arousal_label' do
+    it 'returns :dormant for near-zero arousal' do
+      10.times { model.calm(amount: 1.0) }
+      expect(model.arousal_label).to eq(:dormant)
+    end
+
+    it 'returns :panic for high arousal' do
+      10.times { model.stimulate(amount: 1.0, source: :test) }
+      expect(model.arousal_label).to eq(:panic)
+    end
+
+    it 'returns a symbol for any arousal level' do
+      expect(model.arousal_label).to be_a(Symbol)
+    end
+  end
+
+  describe '#optimal_for' do
+    it 'returns the correct optimal for each complexity' do
+      constants = Legion::Extensions::Agentic::Attention::Arousal::Helpers::Constants
+      expect(model.optimal_for(:trivial)).to eq(constants::TASK_COMPLEXITIES[:trivial])
+      expect(model.optimal_for(:moderate)).to eq(constants::TASK_COMPLEXITIES[:moderate])
+      expect(model.optimal_for(:extreme)).to eq(constants::TASK_COMPLEXITIES[:extreme])
+    end
+
+    it 'returns the default when complexity is unknown' do
+      expect(model.optimal_for(:unknown)).to eq(Legion::Extensions::Agentic::Attention::Arousal::Helpers::Constants::OPTIMAL_AROUSAL_DEFAULT)
+    end
+  end
+
+  describe '#arousal_history cap' do
+    it 'does not exceed MAX_AROUSAL_HISTORY entries' do
+      max = Legion::Extensions::Agentic::Attention::Arousal::Helpers::Constants::MAX_AROUSAL_HISTORY
+      (max + 10).times { model.stimulate(amount: 0.01, source: :test) }
+      expect(model.arousal_history.size).to eq(max)
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes arousal, label, performance_last, and history_size' do
+      h = model.to_h
+      expect(h).to have_key(:arousal)
+      expect(h).to have_key(:label)
+      expect(h).to have_key(:performance_last)
+      expect(h).to have_key(:history_size)
+    end
+
+    it 'reflects the current state' do
+      model.stimulate(amount: 0.2, source: :test)
+      h = model.to_h
+      expect(h[:arousal]).to eq(model.arousal)
+      expect(h[:history_size]).to eq(model.arousal_history.size)
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Arousal::Helpers::Constants do
+  describe 'DEFAULT_AROUSAL' do
+    it 'is 0.3' do
+      expect(described_class::DEFAULT_AROUSAL).to eq(0.3)
+    end
+  end
+
+  describe 'AROUSAL_FLOOR and AROUSAL_CEILING' do
+    it 'floor is 0.0' do
+      expect(described_class::AROUSAL_FLOOR).to eq(0.0)
+    end
+
+    it 'ceiling is 1.0' do
+      expect(described_class::AROUSAL_CEILING).to eq(1.0)
+    end
+  end
+
+  describe 'TASK_COMPLEXITIES' do
+    it 'includes all expected complexity levels' do
+      expect(described_class::TASK_COMPLEXITIES.keys).to contain_exactly(:trivial, :simple, :moderate, :complex, :extreme)
+    end
+
+    it 'trivial has the highest optimal arousal' do
+      expect(described_class::TASK_COMPLEXITIES[:trivial]).to be > described_class::TASK_COMPLEXITIES[:extreme]
+    end
+
+    it 'extreme has the lowest optimal arousal' do
+      expect(described_class::TASK_COMPLEXITIES[:extreme]).to eq(0.3)
+    end
+  end
+
+  describe 'AROUSAL_LABELS' do
+    it 'covers the full 0.0..1.0 range' do
+      test_values = [0.0, 0.1, 0.3, 0.5, 0.7, 0.9, 1.0]
+      test_values.each do |v|
+        matched = described_class::AROUSAL_LABELS.any? { |range, _| range.cover?(v) }
+        expect(matched).to be(true), "Expected #{v} to match a label range"
+      end
+    end
+
+    it 'maps values >= 0.8 to :panic' do
+      range, label = described_class::AROUSAL_LABELS.find { |r, _| r.cover?(0.9) }
+      expect(label).to eq(:panic)
+      expect(range).to cover(0.9)
+    end
+
+    it 'maps values in 0.4..0.6 to :optimal' do
+      range, label = described_class::AROUSAL_LABELS.find { |r, _| r.cover?(0.5) }
+      expect(label).to eq(:optimal)
+      expect(range).to cover(0.5)
+    end
+  end
+
+  describe 'OPTIMAL_AROUSAL_SIMPLE and OPTIMAL_AROUSAL_COMPLEX' do
+    it 'simple optimal is higher than complex optimal' do
+      expect(described_class::OPTIMAL_AROUSAL_SIMPLE).to be > described_class::OPTIMAL_AROUSAL_COMPLEX
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/arousal/runners/arousal_spec.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/attention/arousal/client'
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Arousal::Runners::Arousal do
+  let(:client) { Legion::Extensions::Agentic::Attention::Arousal::Client.new }
+
+  describe '#stimulate' do
+    it 'returns success: true' do
+      result = client.stimulate
+      expect(result[:success]).to be(true)
+    end
+
+    it 'returns the new arousal level' do
+      result = client.stimulate(amount: 0.2, source: :test)
+      expect(result[:arousal]).to be_a(Float)
+    end
+
+    it 'returns a label' do
+      result = client.stimulate
+      expect(result[:label]).to be_a(Symbol)
+    end
+
+    it 'returns the source' do
+      result = client.stimulate(source: :external_event)
+      expect(result[:source]).to eq(:external_event)
+    end
+
+    it 'increases arousal above default' do
+      result = client.stimulate(amount: 0.4)
+      expect(result[:arousal]).to be > Legion::Extensions::Agentic::Attention::Arousal::Helpers::Constants::DEFAULT_AROUSAL
+    end
+  end
+
+  describe '#calm' do
+    before { client.stimulate(amount: 0.5) }
+
+    it 'returns success: true' do
+      expect(client.calm[:success]).to be(true)
+    end
+
+    it 'returns the new arousal level' do
+      result = client.calm(amount: 0.1)
+      expect(result[:arousal]).to be_a(Float)
+    end
+
+    it 'returns a label' do
+      expect(client.calm[:label]).to be_a(Symbol)
+    end
+  end
+
+  describe '#update_arousal' do
+    it 'returns success: true' do
+      expect(client.update_arousal[:success]).to be(true)
+    end
+
+    it 'returns arousal, label, and performance' do
+      result = client.update_arousal
+      expect(result).to have_key(:arousal)
+      expect(result).to have_key(:label)
+      expect(result).to have_key(:performance)
+    end
+
+    it 'returns performance between 0 and 1' do
+      result = client.update_arousal
+      expect(result[:performance]).to be_between(0.0, 1.0)
+    end
+  end
+
+  describe '#check_performance' do
+    it 'returns success: true' do
+      expect(client.check_performance[:success]).to be(true)
+    end
+
+    it 'returns performance, arousal, optimal_arousal, and task_complexity' do
+      result = client.check_performance(task_complexity: :simple)
+      expect(result).to have_key(:performance)
+      expect(result).to have_key(:arousal)
+      expect(result).to have_key(:optimal_arousal)
+      expect(result[:task_complexity]).to eq(:simple)
+    end
+
+    it 'reflects the optimal arousal for the given complexity' do
+      result_simple  = client.check_performance(task_complexity: :simple)
+      result_extreme = client.check_performance(task_complexity: :extreme)
+      expect(result_simple[:optimal_arousal]).to be > result_extreme[:optimal_arousal]
+    end
+  end
+
+  describe '#arousal_status' do
+    it 'returns success: true' do
+      expect(client.arousal_status[:success]).to be(true)
+    end
+
+    it 'returns arousal, label, performance, and history_size' do
+      result = client.arousal_status
+      expect(result).to have_key(:arousal)
+      expect(result).to have_key(:label)
+      expect(result).to have_key(:performance)
+      expect(result).to have_key(:history_size)
+    end
+  end
+
+  describe '#arousal_guidance' do
+    it 'returns success: true' do
+      expect(client.arousal_guidance[:success]).to be(true)
+    end
+
+    it 'returns guidance as a symbol' do
+      result = client.arousal_guidance
+      expect(result[:guidance]).to be_a(Symbol)
+    end
+
+    it 'returns :throttle when arousal is well above optimal' do
+      5.times { client.stimulate(amount: 1.0) }
+      result = client.arousal_guidance(task_complexity: :extreme)
+      expect(result[:guidance]).to eq(:throttle)
+    end
+
+    it 'returns :boost when arousal is well below optimal' do
+      10.times { client.calm(amount: 1.0) }
+      result = client.arousal_guidance(task_complexity: :trivial)
+      expect(result[:guidance]).to eq(:boost)
+    end
+
+    it 'returns :maintain when near optimal' do
+      result = client.arousal_guidance(task_complexity: :moderate)
+      expect(%i[maintain throttle boost]).to include(result[:guidance])
+    end
+
+    it 'includes optimal_arousal and task_complexity' do
+      result = client.arousal_guidance(task_complexity: :complex)
+      expect(result[:optimal_arousal]).to eq(0.4)
+      expect(result[:task_complexity]).to eq(:complex)
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Blindspot::Client do
+  subject(:client) { described_class.new }
+
+  it 'includes the runner module' do
+    expect(client).to respond_to(:register_blindspot)
+  end
+
+  it 'provides a BlindspotEngine' do
+    expect(client.engine).to be_a(
+      Legion::Extensions::Agentic::Attention::Blindspot::Helpers::BlindspotEngine
+    )
+  end
+
+  it 'registers and acknowledges a blindspot' do
+    result = client.register_blindspot(
+      domain:        :logic,
+      discovered_by: :self_reflection,
+      description:   'Underestimates rare events'
+    )
+    expect(result[:success]).to be true
+
+    ack = client.acknowledge_blindspot(blindspot_id: result[:id])
+    expect(ack[:success]).to be true
+    expect(ack[:status]).to eq(:acknowledged)
+  end
+
+  it 'full lifecycle: register -> mitigate -> resolve' do
+    reg = client.register_blindspot(domain: :planning, discovered_by: :peer_feedback,
+                                    description: 'Overestimates available time')
+    client.mitigate_blindspot(blindspot_id: reg[:id])
+    res = client.resolve_blindspot(blindspot_id: reg[:id])
+    expect(res[:status]).to eq(:resolved)
+  end
+
+  it 'awareness score is 1.0 with no blindspots' do
+    report = client.awareness_score_report
+    expect(report[:awareness_score]).to eq(1.0)
+  end
+end

data/spec/legion/extensions/agentic/attention/blindspot/helpers/blindspot_engine_spec.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Blindspot::Helpers::BlindspotEngine do
+  subject(:engine) { described_class.new }
+
+  let(:blindspot) do
+    engine.register_blindspot(
+      domain:        :reasoning,
+      discovered_by: :error_analysis,
+      description:   'Confirmation bias in evidence weighing'
+    )
+  end
+
+  describe '#initialize' do
+    it 'starts with awareness_score of 1.0' do
+      expect(engine.awareness_score).to eq(1.0)
+    end
+  end
+
+  describe '#register_blindspot' do
+    it 'returns a Blindspot object' do
+      expect(blindspot).to be_a(Legion::Extensions::Agentic::Attention::Blindspot::Helpers::Blindspot)
+    end
+
+    it 'assigns a uuid' do
+      expect(blindspot.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'recalculates awareness score after registration' do
+      blindspot
+      expect(engine.awareness_score).to be < 1.0
+    end
+  end
+
+  describe '#acknowledge_blindspot' do
+    it 'returns found: false for unknown id' do
+      result = engine.acknowledge_blindspot(blindspot_id: 'bad-id')
+      expect(result[:found]).to be false
+    end
+
+    it 'acknowledges a known blindspot' do
+      result = engine.acknowledge_blindspot(blindspot_id: blindspot.id)
+      expect(result[:found]).to be true
+      expect(result[:status]).to eq(:acknowledged)
+    end
+
+    it 'updates awareness score after acknowledging' do
+      engine.acknowledge_blindspot(blindspot_id: blindspot.id)
+      expect(engine.awareness_score).to eq(1.0)
+    end
+  end
+
+  describe '#mitigate_blindspot' do
+    it 'returns found: false for unknown id' do
+      result = engine.mitigate_blindspot(blindspot_id: 'bad-id')
+      expect(result[:found]).to be false
+    end
+
+    it 'mitigates a known blindspot' do
+      result = engine.mitigate_blindspot(blindspot_id: blindspot.id)
+      expect(result[:found]).to be true
+      expect(result[:status]).to eq(:mitigated)
+    end
+
+    it 'reduces severity on mitigation' do
+      before = blindspot.severity
+      engine.mitigate_blindspot(blindspot_id: blindspot.id)
+      expect(blindspot.severity).to be < before
+    end
+  end
+
+  describe '#resolve_blindspot' do
+    it 'returns found: false for unknown id' do
+      result = engine.resolve_blindspot(blindspot_id: 'bad-id')
+      expect(result[:found]).to be false
+    end
+
+    it 'resolves a known blindspot' do
+      result = engine.resolve_blindspot(blindspot_id: blindspot.id)
+      expect(result[:found]).to be true
+      expect(result[:status]).to eq(:resolved)
+    end
+  end
+
+  describe '#set_boundary' do
+    it 'creates a new boundary' do
+      b = engine.set_boundary(domain: :math, confidence: 0.8, coverage_estimate: 0.6)
+      expect(b).to be_a(Legion::Extensions::Agentic::Attention::Blindspot::Helpers::KnowledgeBoundary)
+    end
+
+    it 'updates existing boundary for same domain' do
+      engine.set_boundary(domain: :math, confidence: 0.5)
+      b2 = engine.set_boundary(domain: :math, confidence: 0.9)
+      expect(b2.confidence).to eq(0.9)
+    end
+  end
+
+  describe '#detect_boundary_gap' do
+    it 'returns gap_detected: false when no boundary set' do
+      result = engine.detect_boundary_gap(domain: :unknown_domain, error_occurred: true)
+      expect(result[:gap_detected]).to be false
+      expect(result[:reason]).to eq(:no_boundary)
+    end
+
+    it 'returns gap_detected: true when error occurs and confidence is high' do
+      engine.set_boundary(domain: :physics, confidence: 0.8)
+      result = engine.detect_boundary_gap(domain: :physics, error_occurred: true)
+      expect(result[:gap_detected]).to be true
+    end
+
+    it 'returns gap_detected: false when no error' do
+      engine.set_boundary(domain: :physics, confidence: 0.8)
+      result = engine.detect_boundary_gap(domain: :physics, error_occurred: false)
+      expect(result[:gap_detected]).to be false
+    end
+  end
+
+  describe '#blindspots_by_domain' do
+    it 'returns blindspots matching domain' do
+      blindspot
+      results = engine.blindspots_by_domain(:reasoning)
+      expect(results.size).to eq(1)
+      expect(results.first.domain).to eq(:reasoning)
+    end
+
+    it 'returns empty for non-existent domain' do
+      expect(engine.blindspots_by_domain(:unknown_xyz)).to be_empty
+    end
+  end
+
+  describe '#active_blindspots' do
+    it 'returns only active blindspots' do
+      blindspot
+      expect(engine.active_blindspots.size).to eq(1)
+    end
+
+    it 'excludes acknowledged blindspots' do
+      engine.acknowledge_blindspot(blindspot_id: blindspot.id)
+      expect(engine.active_blindspots).to be_empty
+    end
+  end
+
+  describe '#acknowledged_blindspots' do
+    it 'returns acknowledged blindspots' do
+      engine.acknowledge_blindspot(blindspot_id: blindspot.id)
+      expect(engine.acknowledged_blindspots.size).to eq(1)
+    end
+  end
+
+  describe '#resolved_blindspots' do
+    it 'returns resolved blindspots' do
+      engine.resolve_blindspot(blindspot_id: blindspot.id)
+      expect(engine.resolved_blindspots.size).to eq(1)
+    end
+  end
+
+  describe '#most_severe' do
+    it 'returns blindspots sorted by severity descending' do
+      engine.register_blindspot(domain: :a, discovered_by: :unknown,
+                                description: 'low', severity: 0.2)
+      high = engine.register_blindspot(domain: :b, discovered_by: :unknown,
+                                       description: 'high', severity: 0.9)
+      result = engine.most_severe(limit: 2)
+      expect(result.first.id).to eq(high.id)
+    end
+
+    it 'respects limit' do
+      3.times { |i| engine.register_blindspot(domain: :x, discovered_by: :unknown, description: "s#{i}") }
+      expect(engine.most_severe(limit: 2).size).to eq(2)
+    end
+  end
+
+  describe '#mitigation_strategies' do
+    it 'returns strategies for active blindspots' do
+      blindspot
+      strategies = engine.mitigation_strategies
+      expect(strategies.size).to eq(1)
+      expect(strategies.first).to include(:blindspot_id, :domain, :severity, :strategy)
+    end
+
+    it 'returns strategies filtered by domain' do
+      blindspot
+      engine.register_blindspot(domain: :other, discovered_by: :unknown, description: 'other')
+      strategies = engine.mitigation_strategies(domain: :reasoning)
+      expect(strategies.size).to eq(1)
+    end
+
+    it 'returns empty after all are acknowledged' do
+      engine.acknowledge_blindspot(blindspot_id: blindspot.id)
+      expect(engine.mitigation_strategies).to be_empty
+    end
+  end
+
+  describe '#coverage_report' do
+    it 'returns empty when no boundaries set' do
+      expect(engine.coverage_report).to be_empty
+    end
+
+    it 'returns boundaries as hashes' do
+      engine.set_boundary(domain: :logic, confidence: 0.7)
+      report = engine.coverage_report
+      expect(report.size).to eq(1)
+      expect(report.first).to include(:domain, :confidence, :coverage_estimate)
+    end
+  end
+
+  describe '#awareness_label' do
+    it 'returns :unaware when score is 0' do
+      engine.register_blindspot(domain: :x, discovered_by: :unknown, description: 'x')
+      expect(engine.awareness_label).to be_a(Symbol)
+    end
+
+    it 'returns :highly_aware at score 1.0' do
+      expect(engine.awareness_label).to eq(:highly_aware)
+    end
+  end
+
+  describe '#awareness_gap' do
+    it 'returns 0.0 when no blindspots' do
+      expect(engine.awareness_gap).to eq(0.0)
+    end
+
+    it 'is complement of awareness_score' do
+      blindspot
+      expect((engine.awareness_score + engine.awareness_gap).round(10)).to eq(1.0)
+    end
+  end
+
+  describe '#johari_report' do
+    it 'returns comprehensive report' do
+      blindspot
+      report = engine.johari_report
+      expect(report).to include(:total_blindspots, :active, :acknowledged, :resolved,
+                                :awareness_score, :awareness_label, :awareness_gap,
+                                :boundaries_tracked, :most_severe)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns summary stats' do
+      h = engine.to_h
+      expect(h).to include(:total_blindspots, :active, :acknowledged,
+                           :resolved, :awareness_score, :awareness_label)
+    end
+  end
+end