lex-agentic-attention 0.1.0

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Kaleidoscope::Client do
+  subject(:client) { described_class.new }
+
+  it 'includes the runner module' do
+    expect(described_class.ancestors).to include(
+      Legion::Extensions::Agentic::Attention::Kaleidoscope::Runners::CognitiveKaleidoscope
+    )
+  end
+
+  it 'responds to create_facet' do
+    expect(client).to respond_to(:create_facet)
+  end
+
+  it 'responds to create_pattern' do
+    expect(client).to respond_to(:create_pattern)
+  end
+
+  it 'responds to rotate' do
+    expect(client).to respond_to(:rotate)
+  end
+
+  it 'responds to polish' do
+    expect(client).to respond_to(:polish)
+  end
+
+  it 'responds to kaleidoscope_status' do
+    expect(client).to respond_to(:kaleidoscope_status)
+  end
+
+  it 'can create facet and pattern through client' do
+    facet_result = client.create_facet(facet_type: :belief, domain: :test, content: 'x')
+    expect(facet_result[:success]).to be true
+    pattern_result = client.create_pattern
+    expect(pattern_result[:success]).to be true
+  end
+end

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Kaleidoscope::Helpers::Constants do
+  described_class = Legion::Extensions::Agentic::Attention::Kaleidoscope::Helpers::Constants
+
+  describe 'FACET_TYPES' do
+    it 'contains expected types' do
+      expect(described_class::FACET_TYPES).to eq(%i[belief experience emotion memory intuition])
+    end
+
+    it 'is frozen' do
+      expect(described_class::FACET_TYPES).to be_frozen
+    end
+  end
+
+  describe 'SYMMETRY_TYPES' do
+    it 'contains expected types' do
+      expect(described_class::SYMMETRY_TYPES).to eq(%i[bilateral radial rotational asymmetric])
+    end
+  end
+
+  describe 'ROTATION_MODES' do
+    it 'contains expected modes' do
+      expect(described_class::ROTATION_MODES).to eq(%i[slow steady rapid chaotic])
+    end
+  end
+
+  describe 'numeric constants' do
+    it 'defines MAX_FACETS' do
+      expect(described_class::MAX_FACETS).to eq(500)
+    end
+
+    it 'defines MAX_PATTERNS' do
+      expect(described_class::MAX_PATTERNS).to eq(100)
+    end
+
+    it 'defines ROTATION_STEP' do
+      expect(described_class::ROTATION_STEP).to eq(0.1)
+    end
+
+    it 'defines DECAY_RATE' do
+      expect(described_class::DECAY_RATE).to eq(0.02)
+    end
+  end
+
+  describe '.label_for' do
+    context 'with BRILLIANCE_LABELS' do
+      it 'returns :dazzling for high values' do
+        expect(described_class.label_for(described_class::BRILLIANCE_LABELS, 0.9)).to eq(:dazzling)
+      end
+
+      it 'returns :vivid for 0.7' do
+        expect(described_class.label_for(described_class::BRILLIANCE_LABELS, 0.7)).to eq(:vivid)
+      end
+
+      it 'returns :moderate for 0.5' do
+        expect(described_class.label_for(described_class::BRILLIANCE_LABELS, 0.5)).to eq(:moderate)
+      end
+
+      it 'returns :dim for 0.3' do
+        expect(described_class.label_for(described_class::BRILLIANCE_LABELS, 0.3)).to eq(:dim)
+      end
+
+      it 'returns :dark for 0.1' do
+        expect(described_class.label_for(described_class::BRILLIANCE_LABELS, 0.1)).to eq(:dark)
+      end
+    end
+
+    context 'with COMPLEXITY_LABELS' do
+      it 'returns :fractal for 0.9' do
+        expect(described_class.label_for(described_class::COMPLEXITY_LABELS, 0.9)).to eq(:fractal)
+      end
+
+      it 'returns :minimal for 0.1' do
+        expect(described_class.label_for(described_class::COMPLEXITY_LABELS, 0.1)).to eq(:minimal)
+      end
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/kaleidoscope/helpers/facet_spec.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Kaleidoscope::Helpers::Facet do
+  subject(:facet) do
+    described_class.new(facet_type: :belief, domain: :reasoning, content: 'core principle')
+  end
+
+  describe '#initialize' do
+    it 'assigns a UUID id' do
+      expect(facet.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets facet_type as symbol' do
+      expect(facet.facet_type).to eq(:belief)
+    end
+
+    it 'sets domain as symbol' do
+      expect(facet.domain).to eq(:reasoning)
+    end
+
+    it 'stores content' do
+      expect(facet.content).to eq('core principle')
+    end
+
+    it 'defaults brilliance to 0.7' do
+      expect(facet.brilliance).to eq(0.7)
+    end
+
+    it 'defaults transparency to 0.5' do
+      expect(facet.transparency).to eq(0.5)
+    end
+
+    it 'defaults angle to 0.0' do
+      expect(facet.angle).to eq(0.0)
+    end
+
+    it 'accepts custom brilliance' do
+      f = described_class.new(facet_type: :emotion, domain: :test, content: 'x', brilliance: 0.3)
+      expect(f.brilliance).to eq(0.3)
+    end
+
+    it 'clamps brilliance to 0..1' do
+      f = described_class.new(facet_type: :memory, domain: :test, content: 'x', brilliance: 5.0)
+      expect(f.brilliance).to eq(1.0)
+    end
+
+    it 'clamps angle to 0..360' do
+      f = described_class.new(facet_type: :intuition, domain: :test, content: 'x', angle: 500.0)
+      expect(f.angle).to eq(360.0)
+    end
+
+    it 'raises on unknown facet type' do
+      expect do
+        described_class.new(facet_type: :plasma, domain: :test, content: 'x')
+      end.to raise_error(ArgumentError, /unknown facet type/)
+    end
+
+    it 'sets created_at' do
+      expect(facet.created_at).to be_a(Time)
+    end
+  end
+
+  describe '#rotate!' do
+    it 'increases angle' do
+      facet.rotate!(degrees: 45)
+      expect(facet.angle).to eq(45.0)
+    end
+
+    it 'wraps around at 360' do
+      facet.rotate!(degrees: 400)
+      expect(facet.angle).to eq(40.0)
+    end
+  end
+
+  describe '#polish!' do
+    it 'increases brilliance' do
+      initial = facet.brilliance
+      facet.polish!(rate: 0.1)
+      expect(facet.brilliance).to eq((initial + 0.1).round(10))
+    end
+
+    it 'clamps at 1.0' do
+      facet.polish!(rate: 5.0)
+      expect(facet.brilliance).to eq(1.0)
+    end
+  end
+
+  describe '#tarnish!' do
+    it 'decreases brilliance' do
+      initial = facet.brilliance
+      facet.tarnish!
+      expect(facet.brilliance).to be < initial
+    end
+  end
+
+  describe '#dazzling?' do
+    it 'returns false at default' do
+      expect(facet).not_to be_dazzling
+    end
+
+    it 'returns true when brilliance >= 0.8' do
+      facet.brilliance = 0.85
+      expect(facet).to be_dazzling
+    end
+  end
+
+  describe '#dark?' do
+    it 'returns false at default' do
+      expect(facet).not_to be_dark
+    end
+
+    it 'returns true when brilliance < 0.2' do
+      facet.brilliance = 0.1
+      expect(facet).to be_dark
+    end
+  end
+
+  describe '#opaque?' do
+    it 'returns false at default transparency' do
+      expect(facet).not_to be_opaque
+    end
+
+    it 'returns true when transparency < 0.2' do
+      facet.transparency = 0.1
+      expect(facet).to be_opaque
+    end
+  end
+
+  describe '#clear?' do
+    it 'returns false at default' do
+      expect(facet).not_to be_clear
+    end
+
+    it 'returns true when transparency >= 0.8' do
+      facet.transparency = 0.9
+      expect(facet).to be_clear
+    end
+  end
+
+  describe '#brilliance_label' do
+    it 'returns :vivid at default' do
+      expect(facet.brilliance_label).to eq(:vivid)
+    end
+  end
+
+  describe '#to_h' do
+    subject(:hash) { facet.to_h }
+
+    it 'includes all expected keys' do
+      expected = %i[id facet_type domain content brilliance transparency
+                    angle brilliance_label dazzling dark created_at]
+      expect(hash.keys).to match_array(expected)
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/kaleidoscope/helpers/kaleidoscope_engine_spec.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Kaleidoscope::Helpers::KaleidoscopeEngine do
+  subject(:engine) { described_class.new }
+
+  let(:default_attrs) { { facet_type: :belief, domain: :reasoning, content: 'test facet' } }
+
+  describe '#create_facet' do
+    it 'creates and stores a facet' do
+      f = engine.create_facet(**default_attrs)
+      expect(f).to be_a(Legion::Extensions::Agentic::Attention::Kaleidoscope::Helpers::Facet)
+      expect(engine.all_facets.size).to eq(1)
+    end
+
+    it 'raises when limit reached' do
+      stub_const('Legion::Extensions::Agentic::Attention::Kaleidoscope::Helpers::Constants::MAX_FACETS', 2)
+      engine.create_facet(**default_attrs)
+      engine.create_facet(facet_type: :emotion, domain: :test, content: 'x')
+      expect do
+        engine.create_facet(facet_type: :memory, domain: :test, content: 'y')
+      end.to raise_error(ArgumentError, /facet limit/)
+    end
+  end
+
+  describe '#create_pattern' do
+    it 'creates and stores a pattern' do
+      p = engine.create_pattern
+      expect(p).to be_a(Legion::Extensions::Agentic::Attention::Kaleidoscope::Helpers::Pattern)
+      expect(engine.all_patterns.size).to eq(1)
+    end
+
+    it 'accepts symmetry parameter' do
+      p = engine.create_pattern(symmetry: :bilateral)
+      expect(p.symmetry).to eq(:bilateral)
+    end
+
+    it 'raises when limit reached' do
+      stub_const('Legion::Extensions::Agentic::Attention::Kaleidoscope::Helpers::Constants::MAX_PATTERNS', 1)
+      engine.create_pattern
+      expect { engine.create_pattern }.to raise_error(ArgumentError, /pattern limit/)
+    end
+  end
+
+  describe '#add_facet_to_pattern' do
+    it 'links a facet to a pattern' do
+      f = engine.create_facet(**default_attrs)
+      p = engine.create_pattern
+      result = engine.add_facet_to_pattern(facet_id: f.id, pattern_id: p.id)
+      expect(result).to eq(:added)
+    end
+
+    it 'raises for unknown facet' do
+      p = engine.create_pattern
+      expect do
+        engine.add_facet_to_pattern(facet_id: 'bad', pattern_id: p.id)
+      end.to raise_error(ArgumentError, /facet not found/)
+    end
+
+    it 'raises for unknown pattern' do
+      f = engine.create_facet(**default_attrs)
+      expect do
+        engine.add_facet_to_pattern(facet_id: f.id, pattern_id: 'bad')
+      end.to raise_error(ArgumentError, /pattern not found/)
+    end
+  end
+
+  describe '#rotate_facet' do
+    it 'rotates a facet' do
+      f = engine.create_facet(**default_attrs)
+      engine.rotate_facet(facet_id: f.id, degrees: 90)
+      expect(f.angle).to eq(90.0)
+    end
+  end
+
+  describe '#polish_facet' do
+    it 'increases facet brilliance' do
+      f = engine.create_facet(**default_attrs, brilliance: 0.5)
+      engine.polish_facet(facet_id: f.id, rate: 0.2)
+      expect(f.brilliance).to eq(0.7)
+    end
+  end
+
+  describe '#rotate_pattern' do
+    it 'rotates all facets in the pattern' do
+      f = engine.create_facet(**default_attrs)
+      p = engine.create_pattern
+      engine.add_facet_to_pattern(facet_id: f.id, pattern_id: p.id)
+      engine.rotate_pattern(pattern_id: p.id, degrees: 45)
+      expect(f.angle).to eq(45.0)
+    end
+  end
+
+  describe '#tarnish_all!' do
+    it 'reduces brilliance on all facets' do
+      f1 = engine.create_facet(**default_attrs)
+      f2 = engine.create_facet(facet_type: :emotion, domain: :test, content: 'y')
+      engine.tarnish_all!
+      expect(f1.brilliance).to be < 0.7
+      expect(f2.brilliance).to be < 0.7
+    end
+  end
+
+  describe '#facets_by_type' do
+    it 'returns counts per type' do
+      engine.create_facet(**default_attrs)
+      engine.create_facet(facet_type: :emotion, domain: :test, content: 'x')
+      counts = engine.facets_by_type
+      expect(counts[:belief]).to eq(1)
+      expect(counts[:emotion]).to eq(1)
+      expect(counts[:memory]).to eq(0)
+    end
+  end
+
+  describe '#brightest' do
+    it 'returns facets sorted by brilliance descending' do
+      f1 = engine.create_facet(**default_attrs, brilliance: 0.3)
+      f2 = engine.create_facet(facet_type: :emotion, domain: :t, content: 'x', brilliance: 0.9)
+      expect(engine.brightest(limit: 2).first).to eq(f2)
+      expect(engine.brightest(limit: 2).last).to eq(f1)
+    end
+  end
+
+  describe '#dimmest' do
+    it 'returns facets sorted by brilliance ascending' do
+      f1 = engine.create_facet(**default_attrs, brilliance: 0.3)
+      engine.create_facet(facet_type: :emotion, domain: :t, content: 'x', brilliance: 0.9)
+      expect(engine.dimmest(limit: 1).first).to eq(f1)
+    end
+  end
+
+  describe '#dazzling_facets' do
+    it 'returns only dazzling facets' do
+      engine.create_facet(**default_attrs, brilliance: 0.9)
+      engine.create_facet(facet_type: :emotion, domain: :t, content: 'x', brilliance: 0.3)
+      expect(engine.dazzling_facets.size).to eq(1)
+    end
+  end
+
+  describe '#dark_facets' do
+    it 'returns only dark facets' do
+      engine.create_facet(**default_attrs, brilliance: 0.1)
+      engine.create_facet(facet_type: :emotion, domain: :t, content: 'x', brilliance: 0.7)
+      expect(engine.dark_facets.size).to eq(1)
+    end
+  end
+
+  describe '#kaleidoscope_report' do
+    it 'returns a comprehensive hash' do
+      engine.create_facet(**default_attrs)
+      engine.create_pattern
+      report = engine.kaleidoscope_report
+      expect(report).to include(
+        :total_facets, :total_patterns, :by_type,
+        :dazzling_count, :dark_count, :avg_brilliance, :avg_complexity
+      )
+    end
+
+    it 'handles empty engine' do
+      report = engine.kaleidoscope_report
+      expect(report[:total_facets]).to eq(0)
+      expect(report[:avg_brilliance]).to eq(0.0)
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/kaleidoscope/helpers/pattern_spec.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Kaleidoscope::Helpers::Pattern do
+  subject(:pattern) { described_class.new }
+
+  describe '#initialize' do
+    it 'assigns a UUID id' do
+      expect(pattern.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'defaults symmetry to :radial' do
+      expect(pattern.symmetry).to eq(:radial)
+    end
+
+    it 'defaults complexity to 0.5' do
+      expect(pattern.complexity).to eq(0.5)
+    end
+
+    it 'defaults stability to 0.7' do
+      expect(pattern.stability).to eq(0.7)
+    end
+
+    it 'starts with empty facet_ids' do
+      expect(pattern.facet_ids).to be_empty
+    end
+
+    it 'raises on unknown symmetry' do
+      expect do
+        described_class.new(symmetry: :hexagonal)
+      end.to raise_error(ArgumentError, /unknown symmetry/)
+    end
+
+    it 'accepts custom symmetry' do
+      p = described_class.new(symmetry: :bilateral)
+      expect(p.symmetry).to eq(:bilateral)
+    end
+  end
+
+  describe '#add_facet' do
+    it 'adds a facet id' do
+      result = pattern.add_facet('facet-1')
+      expect(result).to eq(:added)
+      expect(pattern.facet_ids).to include('facet-1')
+    end
+
+    it 'returns :already_present for duplicates' do
+      pattern.add_facet('facet-1')
+      expect(pattern.add_facet('facet-1')).to eq(:already_present)
+    end
+
+    it 'recalculates complexity' do
+      20.times { |i| pattern.add_facet("f-#{i}") }
+      expect(pattern.complexity).to eq(1.0)
+    end
+  end
+
+  describe '#remove_facet' do
+    it 'removes a facet id' do
+      pattern.add_facet('facet-1')
+      expect(pattern.remove_facet('facet-1')).to eq(:removed)
+      expect(pattern.facet_ids).not_to include('facet-1')
+    end
+
+    it 'returns :not_found for missing id' do
+      expect(pattern.remove_facet('nope')).to eq(:not_found)
+    end
+  end
+
+  describe '#rotate_all!' do
+    it 'reduces stability slightly' do
+      initial = pattern.stability
+      pattern.rotate_all!(degrees: 90)
+      expect(pattern.stability).to be < initial
+    end
+  end
+
+  describe '#stabilize!' do
+    it 'increases stability' do
+      pattern.stability = 0.5
+      pattern.stabilize!(rate: 0.1)
+      expect(pattern.stability).to eq(0.6)
+    end
+  end
+
+  describe '#destabilize!' do
+    it 'decreases stability' do
+      initial = pattern.stability
+      pattern.destabilize!(rate: 0.1)
+      expect(pattern.stability).to eq((initial - 0.1).round(10))
+    end
+  end
+
+  describe '#fractal?' do
+    it 'returns false at default' do
+      expect(pattern).not_to be_fractal
+    end
+
+    it 'returns true when complexity >= 0.8' do
+      pattern.complexity = 0.9
+      expect(pattern).to be_fractal
+    end
+  end
+
+  describe '#minimal?' do
+    it 'returns false at default' do
+      expect(pattern).not_to be_minimal
+    end
+
+    it 'returns true when complexity < 0.2' do
+      pattern.complexity = 0.1
+      expect(pattern).to be_minimal
+    end
+  end
+
+  describe '#stable?' do
+    it 'returns true at default' do
+      expect(pattern).to be_stable
+    end
+  end
+
+  describe '#chaotic?' do
+    it 'returns false at default' do
+      expect(pattern).not_to be_chaotic
+    end
+
+    it 'returns true when stability < 0.3' do
+      pattern.stability = 0.2
+      expect(pattern).to be_chaotic
+    end
+  end
+
+  describe '#complexity_label' do
+    it 'returns a symbol' do
+      expect(pattern.complexity_label).to be_a(Symbol)
+    end
+  end
+
+  describe '#facet_count' do
+    it 'returns 0 initially' do
+      expect(pattern.facet_count).to eq(0)
+    end
+
+    it 'tracks facet additions' do
+      pattern.add_facet('f-1')
+      pattern.add_facet('f-2')
+      expect(pattern.facet_count).to eq(2)
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all expected keys' do
+      expected = %i[id symmetry complexity stability complexity_label
+                    facet_count fractal chaotic created_at]
+      expect(pattern.to_h.keys).to match_array(expected)
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/kaleidoscope/runners/cognitive_kaleidoscope_spec.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Kaleidoscope::Runners::CognitiveKaleidoscope do
+  let(:runner) do
+    obj = Object.new
+    obj.extend(described_class)
+    obj
+  end
+
+  let(:engine) { Legion::Extensions::Agentic::Attention::Kaleidoscope::Helpers::KaleidoscopeEngine.new }
+
+  describe '#create_facet' do
+    it 'returns success with facet hash' do
+      result = runner.create_facet(facet_type: :belief, domain: :reasoning,
+                                   content: 'test', engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:facet][:facet_type]).to eq(:belief)
+    end
+
+    it 'returns failure for invalid type' do
+      result = runner.create_facet(facet_type: :plasma, domain: :test,
+                                   content: 'x', engine: engine)
+      expect(result[:success]).to be false
+      expect(result[:error]).to match(/unknown facet type/)
+    end
+  end
+
+  describe '#create_pattern' do
+    it 'returns success with pattern hash' do
+      result = runner.create_pattern(engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:pattern]).to be_a(Hash)
+    end
+
+    it 'accepts symmetry' do
+      result = runner.create_pattern(symmetry: :bilateral, engine: engine)
+      expect(result[:pattern][:symmetry]).to eq(:bilateral)
+    end
+  end
+
+  describe '#add_to_pattern' do
+    it 'links facet to pattern' do
+      f = engine.create_facet(facet_type: :belief, domain: :t, content: 'x')
+      p = engine.create_pattern
+      result = runner.add_to_pattern(facet_id: f.id, pattern_id: p.id, engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:status]).to eq(:added)
+    end
+
+    it 'returns failure for bad ids' do
+      result = runner.add_to_pattern(facet_id: 'bad', pattern_id: 'bad', engine: engine)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#rotate' do
+    it 'rotates a facet' do
+      f = engine.create_facet(facet_type: :emotion, domain: :t, content: 'x')
+      result = runner.rotate(facet_id: f.id, degrees: 90, engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:facet][:angle]).to eq(90.0)
+    end
+
+    it 'rotates a pattern' do
+      p = engine.create_pattern
+      result = runner.rotate(pattern_id: p.id, degrees: 45, engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:pattern]).to be_a(Hash)
+    end
+
+    it 'returns failure when neither given' do
+      result = runner.rotate(engine: engine)
+      expect(result[:success]).to be false
+      expect(result[:error]).to match(/must provide/)
+    end
+  end
+
+  describe '#polish' do
+    it 'increases facet brilliance' do
+      f = engine.create_facet(facet_type: :memory, domain: :t, content: 'x', brilliance: 0.5)
+      result = runner.polish(facet_id: f.id, rate: 0.2, engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:facet][:brilliance]).to eq(0.7)
+    end
+  end
+
+  describe '#list_facets' do
+    before do
+      engine.create_facet(facet_type: :belief, domain: :t, content: 'a')
+      engine.create_facet(facet_type: :emotion, domain: :t, content: 'b')
+      engine.create_facet(facet_type: :belief, domain: :t, content: 'c')
+    end
+
+    it 'returns all facets' do
+      result = runner.list_facets(engine: engine)
+      expect(result[:count]).to eq(3)
+    end
+
+    it 'filters by facet_type' do
+      result = runner.list_facets(facet_type: :belief, engine: engine)
+      expect(result[:count]).to eq(2)
+    end
+  end
+
+  describe '#kaleidoscope_status' do
+    it 'returns a report' do
+      result = runner.kaleidoscope_status(engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:report]).to include(:total_facets, :avg_brilliance)
+    end
+  end
+end