lex-agentic-memory 0.1.0

data/spec/legion/extensions/agentic/memory/hologram/helpers/hologram_engine_spec.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Hologram::Helpers::HologramEngine do
+  subject(:engine) { described_class.new }
+
+  def build_hologram(overrides = {})
+    engine.create_hologram(
+      domain:  overrides.fetch(:domain, :memory),
+      content: overrides.fetch(:content, 'the quick brown fox jumps over the lazy dog')
+    )
+  end
+
+  describe '#create_hologram' do
+    it 'returns a Hologram instance' do
+      expect(build_hologram).to be_a(Legion::Extensions::Agentic::Memory::Hologram::Helpers::Hologram)
+    end
+
+    it 'stores the hologram internally' do
+      h = build_hologram
+      expect(engine.get(h.id)).to eq(h)
+    end
+
+    it 'increments hologram count' do
+      3.times { build_hologram }
+      expect(engine.holograms.size).to eq(3)
+    end
+
+    it 'assigns the provided domain' do
+      h = build_hologram(domain: :emotion)
+      expect(h.domain).to eq(:emotion)
+    end
+
+    it 'assigns the provided content' do
+      h = build_hologram(content: 'unique content here')
+      expect(h.content).to eq('unique content here')
+    end
+  end
+
+  describe '#fragment_hologram' do
+    let(:hologram) { build_hologram }
+
+    it 'returns an array of fragments' do
+      result = engine.fragment_hologram(hologram_id: hologram.id, count: 3)
+      expect(result).to be_an(Array)
+    end
+
+    it 'returns the requested number of fragments' do
+      result = engine.fragment_hologram(hologram_id: hologram.id, count: 4)
+      expect(result.size).to eq(4)
+    end
+
+    it 'returns nil for unknown hologram_id' do
+      result = engine.fragment_hologram(hologram_id: SecureRandom.uuid, count: 2)
+      expect(result).to be_nil
+    end
+
+    it 'attaches fragments to the hologram' do
+      engine.fragment_hologram(hologram_id: hologram.id, count: 3)
+      expect(hologram.fragments.size).to eq(3)
+    end
+  end
+
+  describe '#reconstruct_from_fragments' do
+    let(:hologram) { build_hologram }
+    let(:fragments) { engine.fragment_hologram(hologram_id: hologram.id, count: 4) }
+
+    it 'returns success: true when sufficient fragments are used' do
+      ids = fragments.select(&:sufficient?).map(&:id)
+      result = engine.reconstruct_from_fragments(hologram_id: hologram.id, fragment_ids: ids)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns success: false when hologram not found' do
+      result = engine.reconstruct_from_fragments(
+        hologram_id:  SecureRandom.uuid,
+        fragment_ids: []
+      )
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:hologram_not_found)
+    end
+
+    it 'returns resolution value on success' do
+      ids = fragments.map(&:id)
+      result = engine.reconstruct_from_fragments(hologram_id: hologram.id, fragment_ids: ids)
+      expect(result[:resolution]).to be_a(Float) if result[:success]
+    end
+
+    it 'returns success: false with empty fragment ids and no sufficient fragments match' do
+      result = engine.reconstruct_from_fragments(hologram_id: hologram.id, fragment_ids: [])
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#measure_interference' do
+    let(:hologram_a) { build_hologram(content: 'the quick brown fox') }
+    let(:hologram_b) { build_hologram(content: 'the quick brown fox') }
+    let(:hologram_c) { build_hologram(content: 'completely unrelated content here now') }
+
+    it 'returns interference score as float' do
+      result = engine.measure_interference(hologram_id_a: hologram_a.id, hologram_id_b: hologram_b.id)
+      expect(result[:interference]).to be_a(Float)
+    end
+
+    it 'returns high interference for near-identical content' do
+      result = engine.measure_interference(hologram_id_a: hologram_a.id, hologram_id_b: hologram_b.id)
+      expect(result[:interference]).to be > 0.5
+    end
+
+    it 'returns lower interference for dissimilar content' do
+      r1 = engine.measure_interference(hologram_id_a: hologram_a.id, hologram_id_b: hologram_b.id)
+      r2 = engine.measure_interference(hologram_id_a: hologram_a.id, hologram_id_b: hologram_c.id)
+      expect(r1[:interference]).to be >= r2[:interference]
+    end
+
+    it 'includes a label key' do
+      result = engine.measure_interference(hologram_id_a: hologram_a.id, hologram_id_b: hologram_b.id)
+      expect(result[:label]).to be_a(Symbol)
+    end
+
+    it 'returns reason :hologram_not_found when a hologram is missing' do
+      result = engine.measure_interference(
+        hologram_id_a: SecureRandom.uuid,
+        hologram_id_b: hologram_b.id
+      )
+      expect(result[:reason]).to eq(:hologram_not_found)
+    end
+  end
+
+  describe '#degrade_all!' do
+    before do
+      hologram = build_hologram
+      engine.fragment_hologram(hologram_id: hologram.id, count: 3)
+    end
+
+    it 'reduces fidelity on all fragments' do
+      before_values = engine.holograms.flat_map { |h| h.fragments.map(&:fidelity) }
+      engine.degrade_all!
+      after_values = engine.holograms.flat_map { |h| h.fragments.map(&:fidelity) }
+      expect(after_values.sum).to be < before_values.sum
+    end
+
+    it 'affects completeness on all fragments' do
+      before_values = engine.holograms.flat_map { |h| h.fragments.map(&:completeness) }
+      engine.degrade_all!
+      after_values = engine.holograms.flat_map { |h| h.fragments.map(&:completeness) }
+      expect(after_values.sum).to be < before_values.sum
+    end
+  end
+
+  describe '#best_preserved' do
+    before do
+      3.times do |i|
+        h = build_hologram(content: "hologram content #{i}")
+        engine.fragment_hologram(hologram_id: h.id, count: 2)
+      end
+    end
+
+    it 'returns an array' do
+      expect(engine.best_preserved(limit: 2)).to be_an(Array)
+    end
+
+    it 'respects the limit' do
+      expect(engine.best_preserved(limit: 2).size).to be <= 2
+    end
+
+    it 'returns holograms sorted by resolution descending' do
+      top = engine.best_preserved(limit: 3)
+      resolutions = top.map(&:resolution)
+      expect(resolutions).to eq(resolutions.sort.reverse)
+    end
+
+    it 'returns empty array when no holograms have fragments' do
+      fresh_engine = described_class.new
+      fresh_engine.create_hologram(domain: :memory, content: 'no fragments')
+      expect(fresh_engine.best_preserved).to be_empty
+    end
+  end
+
+  describe '#most_fragmented' do
+    before do
+      3.times do |i|
+        h = build_hologram(content: "content for hologram #{i}")
+        engine.fragment_hologram(hologram_id: h.id, count: 2)
+      end
+    end
+
+    it 'returns an array' do
+      expect(engine.most_fragmented(limit: 2)).to be_an(Array)
+    end
+
+    it 'respects the limit' do
+      expect(engine.most_fragmented(limit: 2).size).to be <= 2
+    end
+
+    it 'returns holograms sorted by resolution ascending' do
+      result = engine.most_fragmented(limit: 3)
+      resolutions = result.map(&:resolution)
+      expect(resolutions).to eq(resolutions.sort)
+    end
+  end
+
+  describe '#hologram_report' do
+    before do
+      2.times do |i|
+        h = build_hologram(content: "content number #{i}")
+        engine.fragment_hologram(hologram_id: h.id, count: 3)
+      end
+    end
+
+    subject(:report) { engine.hologram_report }
+
+    it 'includes all expected keys' do
+      expected_keys = %i[
+        total_holograms holograms_with_frags average_resolution
+        resolution_label best_preserved_count most_fragmented_count
+      ]
+      expect(report.keys).to match_array(expected_keys)
+    end
+
+    it 'reports correct total_holograms' do
+      expect(report[:total_holograms]).to eq(2)
+    end
+
+    it 'reports correct holograms_with_frags' do
+      expect(report[:holograms_with_frags]).to eq(2)
+    end
+
+    it 'reports average_resolution as float' do
+      expect(report[:average_resolution]).to be_a(Float)
+    end
+
+    it 'includes resolution_label as symbol' do
+      expect(report[:resolution_label]).to be_a(Symbol)
+    end
+  end
+
+  describe '#holograms' do
+    it 'returns empty array initially' do
+      expect(engine.holograms).to be_empty
+    end
+
+    it 'returns all created holograms' do
+      3.times { build_hologram }
+      expect(engine.holograms.size).to eq(3)
+    end
+  end
+
+  describe '#get' do
+    it 'returns the hologram by id' do
+      h = build_hologram
+      expect(engine.get(h.id)).to eq(h)
+    end
+
+    it 'returns nil for unknown id' do
+      expect(engine.get(SecureRandom.uuid)).to be_nil
+    end
+  end
+
+  describe 'MAX_HOLOGRAMS pruning' do
+    it 'prunes when count reaches MAX_HOLOGRAMS' do
+      max = Legion::Extensions::Agentic::Memory::Hologram::Helpers::Constants::MAX_HOLOGRAMS
+      max.times { |i| build_hologram(content: "hologram #{i}") }
+      expect(engine.holograms.size).to eq(max)
+      build_hologram(content: 'one more hologram')
+      expect(engine.holograms.size).to be <= max
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/hologram/helpers/hologram_spec.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Hologram::Helpers::Hologram do
+  let(:domain)  { :memory }
+  let(:content) { 'the quick brown fox jumps over the lazy dog' }
+
+  subject(:hologram) { described_class.new(domain: domain, content: content) }
+
+  describe '#initialize' do
+    it 'generates a UUID id' do
+      expect(hologram.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores domain as symbol' do
+      expect(hologram.domain).to eq(:memory)
+    end
+
+    it 'converts string domain to symbol' do
+      h = described_class.new(domain: 'emotion', content: content)
+      expect(h.domain).to eq(:emotion)
+    end
+
+    it 'stores content' do
+      expect(hologram.content).to eq(content)
+    end
+
+    it 'initializes with empty fragments' do
+      expect(hologram.fragments).to be_empty
+    end
+
+    it 'sets created_at to a Time' do
+      expect(hologram.created_at).to be_a(Time)
+    end
+  end
+
+  describe '#resolution' do
+    it 'returns 0.0 when there are no fragments' do
+      expect(hologram.resolution).to eq(0.0)
+    end
+
+    it 'returns 0.0 when all fragments are insufficient' do
+      hologram.fragment!(2).each { |f| f.degrade!(0.9) }
+      expect(hologram.resolution).to eq(0.0)
+    end
+
+    it 'returns a value between 0.0 and 1.0 with sufficient fragments' do
+      hologram.fragment!(4)
+      expect(hologram.resolution).to be_between(0.0, 1.0)
+    end
+
+    it 'returns a non-zero resolution with high-completeness fragments' do
+      hologram.fragment!(2)
+      expect(hologram.resolution).to be > 0.0
+    end
+  end
+
+  describe '#fragment!' do
+    it 'returns an array of HolographicFragment objects' do
+      frags = hologram.fragment!(3)
+      expect(frags).to all(be_a(Legion::Extensions::Agentic::Memory::Hologram::Helpers::HolographicFragment))
+    end
+
+    it 'creates the requested number of fragments' do
+      frags = hologram.fragment!(5)
+      expect(frags.size).to eq(5)
+    end
+
+    it 'appends fragments to @fragments' do
+      hologram.fragment!(3)
+      expect(hologram.fragments.size).to eq(3)
+    end
+
+    it 'accumulates fragments across multiple calls' do
+      hologram.fragment!(2)
+      hologram.fragment!(3)
+      expect(hologram.fragments.size).to eq(5)
+    end
+
+    it 'sets parent_hologram_id to self id on all fragments' do
+      frags = hologram.fragment!(4)
+      expect(frags.all? { |f| f.parent_hologram_id == hologram.id }).to be true
+    end
+
+    it 'clamps count to minimum 1' do
+      frags = hologram.fragment!(0)
+      expect(frags.size).to eq(1)
+    end
+
+    it 'clamps count to maximum 20' do
+      frags = hologram.fragment!(50)
+      expect(frags.size).to eq(20)
+    end
+
+    it 'stores the same content as the hologram in each fragment' do
+      frags = hologram.fragment!(3)
+      expect(frags.all? { |f| f.content == content }).to be true
+    end
+  end
+
+  describe '#reconstruct' do
+    context 'with sufficient fragments' do
+      let(:fragments) { hologram.fragment!(4) }
+
+      it 'returns success: true' do
+        expect(hologram.reconstruct(fragments)[:success]).to be true
+      end
+
+      it 'returns a resolution value' do
+        expect(hologram.reconstruct(fragments)[:resolution]).to be_between(0.0, 1.0)
+      end
+
+      it 'returns a resolution label as symbol' do
+        expect(hologram.reconstruct(fragments)[:label]).to be_a(Symbol)
+      end
+
+      it 'returns fragment_count equal to sufficient fragments' do
+        result = hologram.reconstruct(fragments)
+        expect(result[:fragment_count]).to be_between(1, fragments.size)
+      end
+
+      it 'returns total_fragments equal to input count' do
+        result = hologram.reconstruct(fragments)
+        expect(result[:total_fragments]).to eq(fragments.size)
+      end
+    end
+
+    context 'with no sufficient fragments' do
+      let(:bad_fragments) do
+        hologram.fragment!(2).tap { |frags| frags.each { |f| f.degrade!(0.9) } }
+      end
+
+      it 'returns success: false' do
+        expect(hologram.reconstruct(bad_fragments)[:success]).to be false
+      end
+
+      it 'returns reason :insufficient_fragments' do
+        expect(hologram.reconstruct(bad_fragments)[:reason]).to eq(:insufficient_fragments)
+      end
+
+      it 'returns resolution 0.0' do
+        expect(hologram.reconstruct(bad_fragments)[:resolution]).to eq(0.0)
+      end
+    end
+
+    context 'with empty array' do
+      it 'returns success: false' do
+        expect(hologram.reconstruct([])[:success]).to be false
+      end
+    end
+  end
+
+  describe '#add_fragment' do
+    it 'appends a fragment to the list' do
+      frag = Legion::Extensions::Agentic::Memory::Hologram::Helpers::HolographicFragment.new(
+        content: content, parent_hologram_id: hologram.id
+      )
+      hologram.add_fragment(frag)
+      expect(hologram.fragments).to include(frag)
+    end
+
+    it 'returns the added fragment' do
+      frag = Legion::Extensions::Agentic::Memory::Hologram::Helpers::HolographicFragment.new(
+        content: content, parent_hologram_id: hologram.id
+      )
+      result = hologram.add_fragment(frag)
+      expect(result).to eq(frag)
+    end
+  end
+
+  describe '#resolution_label' do
+    it 'returns a symbol' do
+      expect(hologram.resolution_label).to be_a(Symbol)
+    end
+
+    it 'returns :fragmentary with no fragments' do
+      expect(hologram.resolution_label).to eq(:fragmentary)
+    end
+
+    it 'accepts an override value' do
+      expect(hologram.resolution_label(0.95)).to eq(:perfect)
+    end
+  end
+
+  describe '#interference_with' do
+    let(:other) { described_class.new(domain: :emotion, content: 'the quick brown fox') }
+
+    it 'returns a float between 0.0 and 1.0' do
+      score = hologram.interference_with(other)
+      expect(score).to be_between(0.0, 1.0)
+    end
+
+    it 'returns higher interference for more overlapping content' do
+      close = described_class.new(domain: :memory, content: 'the quick brown fox jumps')
+      distant = described_class.new(domain: :memory, content: 'completely different words here')
+      expect(hologram.interference_with(close)).to be > hologram.interference_with(distant)
+    end
+
+    it 'returns 0.0 when compared to itself by id' do
+      expect(hologram.interference_with(hologram)).to eq(0.0)
+    end
+
+    it 'returns 0.0 when other is nil' do
+      expect(hologram.interference_with(nil)).to eq(0.0)
+    end
+
+    it 'returns 0.0 for completely different content' do
+      unrelated = described_class.new(domain: :memory, content: 'xyz abc def')
+      score = hologram.interference_with(unrelated)
+      expect(score).to be >= 0.0
+    end
+
+    it 'returns 1.0 for identical content' do
+      twin = described_class.new(domain: :memory, content: content)
+      expect(hologram.interference_with(twin)).to be_within(0.001).of(1.0)
+    end
+  end
+
+  describe '#to_h' do
+    subject(:hash) { hologram.to_h }
+
+    before { hologram.fragment!(2) }
+
+    it 'includes :id' do
+      expect(hash[:id]).to eq(hologram.id)
+    end
+
+    it 'includes :domain' do
+      expect(hash[:domain]).to eq(:memory)
+    end
+
+    it 'includes :content' do
+      expect(hash[:content]).to eq(content)
+    end
+
+    it 'includes :resolution as float' do
+      expect(hash[:resolution]).to be_a(Float)
+    end
+
+    it 'includes :resolution_label as symbol' do
+      expect(hash[:resolution_label]).to be_a(Symbol)
+    end
+
+    it 'includes :fragment_count matching actual count' do
+      expect(hash[:fragment_count]).to eq(2)
+    end
+
+    it 'includes :fragments as array of hashes' do
+      expect(hash[:fragments]).to be_an(Array)
+      expect(hash[:fragments].first).to be_a(Hash)
+    end
+
+    it 'includes :created_at as ISO8601 string' do
+      expect(hash[:created_at]).to match(/\d{4}-\d{2}-\d{2}T/)
+    end
+  end
+end