lex-agentic-memory 0.1.0

data/spec/legion/extensions/agentic/memory/offloading/helpers/external_store_spec.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Offloading::Helpers::ExternalStore do
+  let(:store) { described_class.new(name: 'notes_db', store_type: :database) }
+
+  describe '#initialize' do
+    it 'assigns a UUID id' do
+      expect(store.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores name' do
+      expect(store.name).to eq('notes_db')
+    end
+
+    it 'stores store_type' do
+      expect(store.store_type).to eq(:database)
+    end
+
+    it 'defaults trust to DEFAULT_STORE_TRUST (0.7)' do
+      expect(store.trust).to eq(0.7)
+    end
+
+    it 'initializes items_stored to 0' do
+      expect(store.items_stored).to eq(0)
+    end
+
+    it 'initializes successful_retrievals to 0' do
+      expect(store.successful_retrievals).to eq(0)
+    end
+
+    it 'initializes failed_retrievals to 0' do
+      expect(store.failed_retrievals).to eq(0)
+    end
+
+    it 'records created_at as a Time' do
+      expect(store.created_at).to be_a(Time)
+    end
+  end
+
+  describe '#increment_items!' do
+    it 'increments items_stored' do
+      store.increment_items!
+      expect(store.items_stored).to eq(1)
+    end
+
+    it 'returns self for chaining' do
+      expect(store.increment_items!).to eq(store)
+    end
+  end
+
+  describe '#record_success!' do
+    it 'increments successful_retrievals' do
+      store.record_success!
+      expect(store.successful_retrievals).to eq(1)
+    end
+
+    it 'boosts trust by TRUST_BOOST' do
+      trust_before = store.trust
+      store.record_success!
+      expect(store.trust).to be > trust_before
+    end
+
+    it 'does not exceed trust of 1.0' do
+      10.times { store.record_success! }
+      expect(store.trust).to be <= 1.0
+    end
+
+    it 'returns self for chaining' do
+      expect(store.record_success!).to eq(store)
+    end
+  end
+
+  describe '#record_failure!' do
+    it 'increments failed_retrievals' do
+      store.record_failure!
+      expect(store.failed_retrievals).to eq(1)
+    end
+
+    it 'decays trust by TRUST_DECAY' do
+      trust_before = store.trust
+      store.record_failure!
+      expect(store.trust).to be < trust_before
+    end
+
+    it 'does not drop trust below 0.0' do
+      20.times { store.record_failure! }
+      expect(store.trust).to be >= 0.0
+    end
+
+    it 'returns self for chaining' do
+      expect(store.record_failure!).to eq(store)
+    end
+  end
+
+  describe '#retrieval_rate' do
+    it 'returns 0.0 with no retrievals' do
+      expect(store.retrieval_rate).to eq(0.0)
+    end
+
+    it 'returns 1.0 when all retrievals succeed' do
+      3.times { store.record_success! }
+      expect(store.retrieval_rate).to eq(1.0)
+    end
+
+    it 'returns 0.5 for equal success/failure' do
+      store.record_success!
+      store.record_failure!
+      expect(store.retrieval_rate).to eq(0.5)
+    end
+
+    it 'rounds to 10 decimal places' do
+      2.times { store.record_success! }
+      store.record_failure!
+      expect(store.retrieval_rate).to eq((2.0 / 3).round(10))
+    end
+  end
+
+  describe '#reliable?' do
+    it 'returns true when trust >= 0.7' do
+      expect(store.reliable?).to be true
+    end
+
+    it 'returns false when trust drops below 0.7' do
+      4.times { store.record_failure! }
+      expect(store.reliable?).to be false
+    end
+  end
+
+  describe '#trust_label' do
+    it 'returns :trusted for default trust of 0.7' do
+      expect(store.trust_label).to eq(:trusted)
+    end
+
+    it 'returns :highly_trusted after many successes' do
+      5.times { store.record_success! }
+      expect(store.trust_label).to eq(:highly_trusted)
+    end
+
+    it 'returns :unreliable after many failures' do
+      30.times { store.record_failure! }
+      expect(store.trust_label).to eq(:unreliable)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with expected keys' do
+      h = store.to_h
+      expect(h).to include(:id, :name, :store_type, :trust, :trust_label, :items_stored,
+                           :successful_retrievals, :failed_retrievals, :retrieval_rate,
+                           :reliable, :created_at)
+    end
+
+    it 'reflects current trust value' do
+      store.record_failure!
+      expect(store.to_h[:trust]).to eq(store.trust)
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/offloading/helpers/offloaded_item_spec.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Offloading::Helpers::OffloadedItem do
+  let(:store_id) { SecureRandom.uuid }
+  let(:item) do
+    described_class.new(
+      content:    'The capital of France is Paris',
+      item_type:  :fact,
+      importance: 0.8,
+      store_id:   store_id
+    )
+  end
+
+  describe '#initialize' do
+    it 'assigns a UUID id' do
+      expect(item.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores content' do
+      expect(item.content).to eq('The capital of France is Paris')
+    end
+
+    it 'stores item_type' do
+      expect(item.item_type).to eq(:fact)
+    end
+
+    it 'stores importance' do
+      expect(item.importance).to eq(0.8)
+    end
+
+    it 'stores store_id' do
+      expect(item.store_id).to eq(store_id)
+    end
+
+    it 'clamps importance above 1.0 to 1.0' do
+      overimportant = described_class.new(content: 'x', item_type: :fact, importance: 1.5, store_id: store_id)
+      expect(overimportant.importance).to eq(1.0)
+    end
+
+    it 'clamps importance below 0.0 to 0.0' do
+      negative = described_class.new(content: 'x', item_type: :fact, importance: -0.5, store_id: store_id)
+      expect(negative.importance).to eq(0.0)
+    end
+
+    it 'initializes retrieved_count to 0' do
+      expect(item.retrieved_count).to eq(0)
+    end
+
+    it 'initializes last_retrieved_at to nil' do
+      expect(item.last_retrieved_at).to be_nil
+    end
+
+    it 'records offloaded_at as a Time' do
+      expect(item.offloaded_at).to be_a(Time)
+    end
+  end
+
+  describe '#retrieve!' do
+    it 'increments retrieved_count' do
+      item.retrieve!
+      expect(item.retrieved_count).to eq(1)
+    end
+
+    it 'updates last_retrieved_at' do
+      item.retrieve!
+      expect(item.last_retrieved_at).to be_a(Time)
+    end
+
+    it 'returns self for chaining' do
+      expect(item.retrieve!).to eq(item)
+    end
+
+    it 'accumulates multiple retrievals' do
+      3.times { item.retrieve! }
+      expect(item.retrieved_count).to eq(3)
+    end
+  end
+
+  describe '#stale?' do
+    it 'returns false for newly offloaded item with no retrievals' do
+      expect(item.stale?(threshold_seconds: 3600)).to be false
+    end
+
+    it 'returns true when last retrieved time exceeds threshold' do
+      item.retrieve!
+      item.instance_variable_set(:@last_retrieved_at, Time.now.utc - 7200)
+      expect(item.stale?(threshold_seconds: 3600)).to be true
+    end
+
+    it 'returns false when within threshold' do
+      item.retrieve!
+      expect(item.stale?(threshold_seconds: 3600)).to be false
+    end
+  end
+
+  describe '#importance_label' do
+    it 'returns :critical for high importance' do
+      expect(item.importance_label).to eq(:critical)
+    end
+
+    it 'returns :trivial for very low importance' do
+      trivial = described_class.new(content: 'x', item_type: :fact, importance: 0.1, store_id: store_id)
+      expect(trivial.importance_label).to eq(:trivial)
+    end
+
+    it 'returns :moderate for mid-range importance' do
+      moderate = described_class.new(content: 'x', item_type: :fact, importance: 0.5, store_id: store_id)
+      expect(moderate.importance_label).to eq(:moderate)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with expected keys' do
+      h = item.to_h
+      expect(h).to include(:id, :content, :item_type, :importance, :importance_label,
+                           :store_id, :offloaded_at, :retrieved_count, :last_retrieved_at)
+    end
+
+    it 'rounds importance to 10 decimal places' do
+      expect(item.to_h[:importance]).to eq(item.importance.round(10))
+    end
+  end
+end

data/spec/legion/extensions/agentic/memory/offloading/helpers/offloading_engine_spec.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Memory::Offloading::Helpers::OffloadingEngine do
+  let(:engine) { described_class.new }
+  let(:store) { engine.register_store(name: 'my_store', store_type: :database) }
+
+  describe '#register_store' do
+    it 'creates and returns a store' do
+      expect(store).to be_a(Legion::Extensions::Agentic::Memory::Offloading::Helpers::ExternalStore)
+    end
+
+    it 'adds the store to @stores' do
+      store
+      expect(engine.stores.size).to eq(1)
+    end
+
+    it 'returns nil when at MAX_STORES limit' do
+      stub_const('Legion::Extensions::Agentic::Memory::Offloading::Helpers::Constants::MAX_STORES', 1)
+      engine.register_store(name: 'first', store_type: :file)
+      second = engine.register_store(name: 'second', store_type: :file)
+      expect(second).to be_nil
+    end
+  end
+
+  describe '#offload' do
+    it 'creates and returns an offloaded item' do
+      item = engine.offload(content: 'remember this', item_type: :fact, importance: 0.6, store_id: store.id)
+      expect(item).to be_a(Legion::Extensions::Agentic::Memory::Offloading::Helpers::OffloadedItem)
+    end
+
+    it 'adds item to @items' do
+      engine.offload(content: 'remember this', item_type: :fact, importance: 0.6, store_id: store.id)
+      expect(engine.items.size).to eq(1)
+    end
+
+    it 'increments items_stored on the store' do
+      engine.offload(content: 'x', item_type: :fact, importance: 0.5, store_id: store.id)
+      expect(store.items_stored).to eq(1)
+    end
+
+    it 'returns nil for unknown store_id' do
+      item = engine.offload(content: 'x', item_type: :fact, importance: 0.5, store_id: 'bad-id')
+      expect(item).to be_nil
+    end
+
+    it 'returns nil when at MAX_ITEMS limit' do
+      stub_const('Legion::Extensions::Agentic::Memory::Offloading::Helpers::Constants::MAX_ITEMS', 1)
+      engine.offload(content: 'first', item_type: :fact, importance: 0.5, store_id: store.id)
+      second = engine.offload(content: 'second', item_type: :fact, importance: 0.5, store_id: store.id)
+      expect(second).to be_nil
+    end
+  end
+
+  describe '#retrieve' do
+    let!(:item) { engine.offload(content: 'test', item_type: :reminder, importance: 0.4, store_id: store.id) }
+
+    it 'returns the item' do
+      retrieved = engine.retrieve(item_id: item.id)
+      expect(retrieved).to eq(item)
+    end
+
+    it 'increments item retrieved_count' do
+      engine.retrieve(item_id: item.id)
+      expect(item.retrieved_count).to eq(1)
+    end
+
+    it 'records success on the store' do
+      engine.retrieve(item_id: item.id)
+      expect(store.successful_retrievals).to eq(1)
+    end
+
+    it 'returns nil for unknown item_id' do
+      expect(engine.retrieve(item_id: 'no-such-item')).to be_nil
+    end
+  end
+
+  describe '#retrieve_failed' do
+    let!(:item) { engine.offload(content: 'test', item_type: :fact, importance: 0.5, store_id: store.id) }
+
+    it 'returns the item' do
+      expect(engine.retrieve_failed(item_id: item.id)).to eq(item)
+    end
+
+    it 'records failure on the store' do
+      engine.retrieve_failed(item_id: item.id)
+      expect(store.failed_retrievals).to eq(1)
+    end
+
+    it 'decays store trust' do
+      trust_before = store.trust
+      engine.retrieve_failed(item_id: item.id)
+      expect(store.trust).to be < trust_before
+    end
+
+    it 'returns nil for unknown item_id' do
+      expect(engine.retrieve_failed(item_id: 'ghost')).to be_nil
+    end
+  end
+
+  describe '#items_in_store' do
+    it 'returns items belonging to the given store' do
+      engine.offload(content: 'a', item_type: :fact, importance: 0.5, store_id: store.id)
+      engine.offload(content: 'b', item_type: :fact, importance: 0.5, store_id: store.id)
+      other_store = engine.register_store(name: 'other', store_type: :file)
+      engine.offload(content: 'c', item_type: :fact, importance: 0.5, store_id: other_store.id)
+
+      items = engine.items_in_store(store_id: store.id)
+      expect(items.size).to eq(2)
+    end
+
+    it 'returns empty array for store with no items' do
+      expect(engine.items_in_store(store_id: store.id)).to eq([])
+    end
+  end
+
+  describe '#items_by_type' do
+    before do
+      engine.offload(content: 'a', item_type: :fact, importance: 0.5, store_id: store.id)
+      engine.offload(content: 'b', item_type: :fact, importance: 0.6, store_id: store.id)
+      engine.offload(content: 'c', item_type: :plan, importance: 0.7, store_id: store.id)
+    end
+
+    it 'returns items of the given type' do
+      expect(engine.items_by_type(item_type: :fact).size).to eq(2)
+    end
+
+    it 'returns empty array for unused type' do
+      expect(engine.items_by_type(item_type: :calculation)).to eq([])
+    end
+  end
+
+  describe '#most_important_offloaded' do
+    before do
+      engine.offload(content: 'low',  item_type: :fact, importance: 0.2, store_id: store.id)
+      engine.offload(content: 'high', item_type: :fact, importance: 0.9, store_id: store.id)
+      engine.offload(content: 'mid',  item_type: :fact, importance: 0.5, store_id: store.id)
+    end
+
+    it 'returns items sorted by importance descending' do
+      items = engine.most_important_offloaded(limit: 3)
+      importances = items.map(&:importance)
+      expect(importances).to eq(importances.sort.reverse)
+    end
+
+    it 'respects limit' do
+      items = engine.most_important_offloaded(limit: 2)
+      expect(items.size).to eq(2)
+    end
+
+    it 'returns the highest importance item first' do
+      items = engine.most_important_offloaded(limit: 1)
+      expect(items.first.importance).to eq(0.9)
+    end
+  end
+
+  describe '#offloading_ratio' do
+    it 'returns 0.0 with no items' do
+      expect(engine.offloading_ratio).to eq(0.0)
+    end
+
+    it 'increases as items are added' do
+      engine.offload(content: 'x', item_type: :fact, importance: 0.5, store_id: store.id)
+      expect(engine.offloading_ratio).to be > 0.0
+    end
+  end
+
+  describe '#overall_store_trust' do
+    it 'returns 0.0 with no stores' do
+      expect(described_class.new.overall_store_trust).to eq(0.0)
+    end
+
+    it 'returns average trust across stores' do
+      s1 = engine.register_store(name: 's1', store_type: :file)
+      s2 = engine.register_store(name: 's2', store_type: :notes)
+      s1.record_failure!
+      expected = ((s1.trust + s2.trust + store.trust) / 3.0).round(10)
+      expect(engine.overall_store_trust).to eq(expected)
+    end
+  end
+
+  describe '#most_trusted_store' do
+    it 'returns nil with no stores' do
+      expect(described_class.new.most_trusted_store).to be_nil
+    end
+
+    it 'returns the store with highest trust' do
+      s2 = engine.register_store(name: 's2', store_type: :file)
+      s2.record_success!
+      expect(engine.most_trusted_store.trust).to be >= store.trust
+    end
+  end
+
+  describe '#least_trusted_store' do
+    it 'returns nil with no stores' do
+      expect(described_class.new.least_trusted_store).to be_nil
+    end
+
+    it 'returns the store with lowest trust' do
+      s2 = engine.register_store(name: 's2', store_type: :file)
+      3.times { s2.record_failure! }
+      expect(engine.least_trusted_store.trust).to be <= store.trust
+    end
+  end
+
+  describe '#offloading_report' do
+    before do
+      engine.offload(content: 'fact one', item_type: :fact, importance: 0.8, store_id: store.id)
+      engine.offload(content: 'plan one', item_type: :plan, importance: 0.6, store_id: store.id)
+    end
+
+    it 'includes total_items count' do
+      expect(engine.offloading_report[:total_items]).to eq(2)
+    end
+
+    it 'includes total_stores count' do
+      expect(engine.offloading_report[:total_stores]).to eq(1)
+    end
+
+    it 'includes offloading_ratio' do
+      expect(engine.offloading_report[:offloading_ratio]).to be > 0.0
+    end
+
+    it 'includes offloading_label' do
+      expect(engine.offloading_report[:offloading_label]).to be_a(Symbol)
+    end
+
+    it 'includes overall_store_trust' do
+      expect(engine.offloading_report[:overall_store_trust]).to be_a(Float)
+    end
+
+    it 'includes stores_summary array' do
+      expect(engine.offloading_report[:stores_summary]).to be_an(Array)
+    end
+
+    it 'includes items_by_type breakdown' do
+      breakdown = engine.offloading_report[:items_by_type]
+      expect(breakdown[:fact]).to eq(1)
+      expect(breakdown[:plan]).to eq(1)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns items and stores as hashes' do
+      engine.offload(content: 'x', item_type: :fact, importance: 0.5, store_id: store.id)
+      h = engine.to_h
+      expect(h).to have_key(:items)
+      expect(h).to have_key(:stores)
+    end
+  end
+end