lex-cognitive-chunking 0.1.0

data/spec/legion/extensions/cognitive_chunking/helpers/chunk_spec.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveChunking::Helpers::Chunk do
+  let(:chunk) { described_class.new(label: 'chess opening') }
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(chunk.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores label' do
+      expect(chunk.label).to eq('chess opening')
+    end
+
+    it 'starts with empty item_ids' do
+      expect(chunk.item_ids).to be_empty
+    end
+
+    it 'starts with empty sub_chunk_ids' do
+      expect(chunk.sub_chunk_ids).to be_empty
+    end
+
+    it 'starts with DEFAULT_COHERENCE' do
+      expect(chunk.coherence).to eq(Legion::Extensions::CognitiveChunking::Helpers::Constants::DEFAULT_COHERENCE)
+    end
+
+    it 'starts with recall_strength of 0.8' do
+      expect(chunk.recall_strength).to eq(0.8)
+    end
+
+    it 'starts with access_count of 0' do
+      expect(chunk.access_count).to eq(0)
+    end
+
+    it 'pre-populates item_ids from constructor' do
+      c = described_class.new(label: 'test', item_ids: %w[a b c])
+      expect(c.item_ids).to eq(%w[a b c])
+    end
+
+    it 'does not share item_ids reference' do
+      ids = %w[a b]
+      c = described_class.new(label: 'test', item_ids: ids)
+      ids << 'c'
+      expect(c.item_ids.size).to eq(2)
+    end
+  end
+
+  describe '#add_item!' do
+    it 'adds item_id to item_ids' do
+      chunk.add_item!(item_id: 'abc')
+      expect(chunk.item_ids).to include('abc')
+    end
+
+    it 'does not add duplicates' do
+      chunk.add_item!(item_id: 'abc')
+      chunk.add_item!(item_id: 'abc')
+      expect(chunk.item_ids.count('abc')).to eq(1)
+    end
+  end
+
+  describe '#remove_item!' do
+    before { chunk.add_item!(item_id: 'abc') }
+
+    it 'removes item_id' do
+      chunk.remove_item!(item_id: 'abc')
+      expect(chunk.item_ids).not_to include('abc')
+    end
+  end
+
+  describe '#add_sub_chunk!' do
+    it 'adds sub_chunk_id' do
+      chunk.add_sub_chunk!(chunk_id: 'sub-1')
+      expect(chunk.sub_chunk_ids).to include('sub-1')
+    end
+
+    it 'does not add duplicates' do
+      chunk.add_sub_chunk!(chunk_id: 'sub-1')
+      chunk.add_sub_chunk!(chunk_id: 'sub-1')
+      expect(chunk.sub_chunk_ids.count('sub-1')).to eq(1)
+    end
+  end
+
+  describe '#reinforce!' do
+    it 'increments access_count' do
+      chunk.reinforce!
+      expect(chunk.access_count).to eq(1)
+    end
+
+    it 'boosts coherence' do
+      original = chunk.coherence
+      chunk.reinforce!
+      expect(chunk.coherence).to be > original
+    end
+
+    it 'boosts recall_strength' do
+      original = chunk.recall_strength
+      chunk.reinforce!
+      expect(chunk.recall_strength).to be > original
+    end
+
+    it 'caps coherence at 1.0' do
+      20.times { chunk.reinforce! }
+      expect(chunk.coherence).to eq(1.0)
+    end
+
+    it 'caps recall_strength at 1.0' do
+      20.times { chunk.reinforce! }
+      expect(chunk.recall_strength).to eq(1.0)
+    end
+  end
+
+  describe '#decay!' do
+    it 'reduces recall_strength' do
+      original = chunk.recall_strength
+      chunk.decay!
+      expect(chunk.recall_strength).to be < original
+    end
+
+    it 'reduces coherence' do
+      original = chunk.coherence
+      chunk.decay!
+      expect(chunk.coherence).to be < original
+    end
+
+    it 'floors recall_strength at 0.0' do
+      100.times { chunk.decay! }
+      expect(chunk.recall_strength).to eq(0.0)
+    end
+  end
+
+  describe '#size' do
+    it 'returns count of item_ids' do
+      chunk.add_item!(item_id: 'a')
+      chunk.add_item!(item_id: 'b')
+      expect(chunk.size).to eq(2)
+    end
+  end
+
+  describe '#hierarchical?' do
+    it 'returns false when no sub_chunks' do
+      expect(chunk.hierarchical?).to be false
+    end
+
+    it 'returns true when sub_chunks exist' do
+      chunk.add_sub_chunk!(chunk_id: 'child')
+      expect(chunk.hierarchical?).to be true
+    end
+  end
+
+  describe '#coherence_label' do
+    it 'returns :loosely_chunked for default coherence (0.5)' do
+      expect(chunk.coherence_label).to eq(:loosely_chunked)
+    end
+  end
+
+  describe '#recall_label' do
+    it 'returns :instant for high recall_strength (0.8)' do
+      expect(chunk.recall_label).to eq(:instant)
+    end
+  end
+
+  describe '#size_label' do
+    it 'returns :micro for empty chunk' do
+      expect(chunk.size_label).to eq(:micro)
+    end
+
+    it 'returns :large for 7+ items' do
+      7.times { |i| chunk.add_item!(item_id: "item-#{i}") }
+      expect(chunk.size_label).to eq(:large)
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all expected keys' do
+      h = chunk.to_h
+      expected = %i[id label item_ids sub_chunk_ids coherence recall_strength
+                    access_count created_at size hierarchical coherence_label
+                    recall_label size_label]
+      expect(h.keys).to include(*expected)
+    end
+
+    it 'rounds coherence to 10 decimal places' do
+      chunk.reinforce!
+      expect(chunk.to_h[:coherence]).to eq(chunk.coherence.round(10))
+    end
+  end
+end

data/spec/legion/extensions/cognitive_chunking/helpers/chunking_engine_spec.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveChunking::Helpers::ChunkingEngine do
+  let(:engine) { described_class.new }
+
+  def add_items(count, domain: :general)
+    count.times.map { |i| engine.add_item(content: "item #{i}", domain: domain) }
+  end
+
+  describe '#add_item' do
+    it 'returns success with item_id' do
+      result = engine.add_item(content: 'rook pins queen', domain: :chess)
+      expect(result[:success]).to be true
+      expect(result[:item_id]).to be_a(String)
+    end
+
+    it 'stores the item' do
+      result = engine.add_item(content: 'test', domain: :general)
+      expect(engine.items[result[:item_id]]).not_to be_nil
+    end
+
+    it 'returns item hash in result' do
+      result = engine.add_item(content: 'test')
+      expect(result[:item]).to have_key(:id)
+    end
+  end
+
+  describe '#create_chunk' do
+    let(:items) { add_items(3) }
+    let(:item_ids) { items.map { |r| r[:item_id] } }
+
+    it 'returns success with chunk_id' do
+      result = engine.create_chunk(label: 'group', item_ids: item_ids)
+      expect(result[:success]).to be true
+      expect(result[:chunk_id]).to be_a(String)
+    end
+
+    it 'stores the chunk' do
+      result = engine.create_chunk(label: 'group', item_ids: item_ids)
+      expect(engine.chunks[result[:chunk_id]]).not_to be_nil
+    end
+
+    it 'marks items as chunked' do
+      result = engine.create_chunk(label: 'group', item_ids: item_ids)
+      item_ids.each do |id|
+        expect(engine.items[id].chunked?).to be true
+        expect(engine.items[id].chunk_id).to eq(result[:chunk_id])
+      end
+    end
+
+    it 'fails for empty item_ids' do
+      result = engine.create_chunk(label: 'empty', item_ids: [])
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq(:empty_item_ids)
+    end
+
+    it 'fails for non-existent item_ids' do
+      result = engine.create_chunk(label: 'bad', item_ids: %w[nonexistent])
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq(:no_valid_items)
+    end
+  end
+
+  describe '#merge_chunks' do
+    def setup_two_chunks
+      items_a = add_items(2)
+      items_b = add_items(2)
+      chunk_a = engine.create_chunk(label: 'A', item_ids: items_a.map { |r| r[:item_id] })
+      chunk_b = engine.create_chunk(label: 'B', item_ids: items_b.map { |r| r[:item_id] })
+      [chunk_a[:chunk_id], chunk_b[:chunk_id]]
+    end
+
+    it 'creates a hierarchical parent chunk' do
+      chunk_ids = setup_two_chunks
+      result = engine.merge_chunks(chunk_ids: chunk_ids, label: 'Parent')
+      expect(result[:success]).to be true
+      parent = engine.chunks[result[:chunk_id]]
+      expect(parent.hierarchical?).to be true
+    end
+
+    it 'parent has all item_ids from children' do
+      chunk_ids = setup_two_chunks
+      result = engine.merge_chunks(chunk_ids: chunk_ids, label: 'Parent')
+      parent = engine.chunks[result[:chunk_id]]
+      expect(parent.item_ids.size).to eq(4)
+    end
+
+    it 'includes merged_from in result' do
+      chunk_ids = setup_two_chunks
+      result = engine.merge_chunks(chunk_ids: chunk_ids, label: 'Parent')
+      expect(result[:merged_from]).to match_array(chunk_ids)
+    end
+
+    it 'fails with fewer than 2 chunk_ids' do
+      add_items(2)
+      result = engine.merge_chunks(chunk_ids: ['only-one'], label: 'Bad')
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq(:insufficient_chunks)
+    end
+  end
+
+  describe '#load_to_working_memory' do
+    let(:item_id) { engine.add_item(content: 'test')[:item_id] }
+    let(:chunk_id) { engine.create_chunk(label: 'wm test', item_ids: [item_id])[:chunk_id] }
+
+    it 'adds chunk to working memory' do
+      result = engine.load_to_working_memory(chunk_id: chunk_id)
+      expect(result[:success]).to be true
+      expect(engine.working_memory).to include(chunk_id)
+    end
+
+    it 'reinforces the chunk on load' do
+      original_count = engine.chunks[chunk_id].access_count
+      engine.load_to_working_memory(chunk_id: chunk_id)
+      expect(engine.chunks[chunk_id].access_count).to be > original_count
+    end
+
+    it 'fails for unknown chunk' do
+      result = engine.load_to_working_memory(chunk_id: 'nonexistent')
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq(:chunk_not_found)
+    end
+
+    it 'fails when already loaded' do
+      engine.load_to_working_memory(chunk_id: chunk_id)
+      result = engine.load_to_working_memory(chunk_id: chunk_id)
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq(:already_loaded)
+    end
+
+    it 'fails when working memory is at capacity' do
+      # Fill working memory to WORKING_MEMORY_CAPACITY
+      7.times do
+        id = engine.add_item(content: 'filler')[:item_id]
+        cid = engine.create_chunk(label: 'filler', item_ids: [id])[:chunk_id]
+        engine.load_to_working_memory(chunk_id: cid)
+      end
+      result = engine.load_to_working_memory(chunk_id: chunk_id)
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq(:capacity_exceeded)
+    end
+  end
+
+  describe '#unload_from_working_memory' do
+    let(:item_id) { engine.add_item(content: 'test')[:item_id] }
+    let(:chunk_id) { engine.create_chunk(label: 'unload test', item_ids: [item_id])[:chunk_id] }
+
+    before { engine.load_to_working_memory(chunk_id: chunk_id) }
+
+    it 'removes chunk from working memory' do
+      engine.unload_from_working_memory(chunk_id: chunk_id)
+      expect(engine.working_memory).not_to include(chunk_id)
+    end
+
+    it 'returns success' do
+      result = engine.unload_from_working_memory(chunk_id: chunk_id)
+      expect(result[:success]).to be true
+    end
+
+    it 'fails if not in working memory' do
+      engine.unload_from_working_memory(chunk_id: chunk_id)
+      result = engine.unload_from_working_memory(chunk_id: chunk_id)
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq(:not_in_working_memory)
+    end
+  end
+
+  describe '#working_memory_load' do
+    it 'returns 0.0 for empty working memory' do
+      expect(engine.working_memory_load).to eq(0.0)
+    end
+
+    it 'returns load as a ratio' do
+      id = engine.add_item(content: 'x')[:item_id]
+      cid = engine.create_chunk(label: 'x', item_ids: [id])[:chunk_id]
+      engine.load_to_working_memory(chunk_id: cid)
+      expected = (1.0 / 7).round(10)
+      expect(engine.working_memory_load).to be_within(0.0001).of(expected)
+    end
+  end
+
+  describe '#working_memory_overloaded?' do
+    it 'returns false when under capacity' do
+      expect(engine.working_memory_overloaded?).to be false
+    end
+  end
+
+  describe '#decay_all!' do
+    it 'decays all chunks' do
+      id = engine.add_item(content: 'x')[:item_id]
+      cid = engine.create_chunk(label: 'x', item_ids: [id])[:chunk_id]
+      original_recall = engine.chunks[cid].recall_strength
+      engine.decay_all!
+      expect(engine.chunks[cid].recall_strength).to be < original_recall
+    end
+
+    it 'returns success with count' do
+      add_items(3).each_with_index do |r, i|
+        engine.create_chunk(label: "c#{i}", item_ids: [r[:item_id]])
+      end
+      result = engine.decay_all!
+      expect(result[:success]).to be true
+      expect(result[:chunks_decayed]).to eq(3)
+    end
+  end
+
+  describe '#reinforce_chunk' do
+    let(:item_id) { engine.add_item(content: 'reinforce me')[:item_id] }
+    let(:chunk_id) { engine.create_chunk(label: 'reinforce', item_ids: [item_id])[:chunk_id] }
+
+    it 'boosts recall strength' do
+      before_recall = engine.chunks[chunk_id].recall_strength
+      engine.reinforce_chunk(chunk_id: chunk_id)
+      expect(engine.chunks[chunk_id].recall_strength).to be > before_recall
+    end
+
+    it 'fails for unknown chunk_id' do
+      result = engine.reinforce_chunk(chunk_id: 'bad')
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq(:chunk_not_found)
+    end
+  end
+
+  describe '#strongest_chunks' do
+    it 'returns chunks sorted by recall_strength descending' do
+      r1 = engine.add_item(content: 'a')[:item_id]
+      r2 = engine.add_item(content: 'b')[:item_id]
+      c1 = engine.create_chunk(label: 'weak', item_ids: [r1])[:chunk_id]
+      c2 = engine.create_chunk(label: 'strong', item_ids: [r2])[:chunk_id]
+      engine.chunks[c1].decay!
+      engine.chunks[c2].reinforce!
+      chunks = engine.strongest_chunks(limit: 2)
+      expect(chunks.first[:recall_strength]).to be >= chunks.last[:recall_strength]
+    end
+
+    it 'respects limit' do
+      add_items(5).each_with_index { |r, i| engine.create_chunk(label: "c#{i}", item_ids: [r[:item_id]]) }
+      expect(engine.strongest_chunks(limit: 3).size).to eq(3)
+    end
+  end
+
+  describe '#unchunked_items' do
+    it 'returns items not in any chunk' do
+      r1 = engine.add_item(content: 'chunked item')[:item_id]
+      engine.add_item(content: 'free item')
+      engine.create_chunk(label: 'group', item_ids: [r1])
+      unchunked = engine.unchunked_items
+      expect(unchunked.size).to eq(1)
+      expect(unchunked.first[:content]).to eq('free item')
+    end
+  end
+
+  describe '#chunking_efficiency' do
+    it 'returns 0.0 for no items' do
+      expect(engine.chunking_efficiency).to eq(0.0)
+    end
+
+    it 'returns ratio of chunked to total' do
+      r1 = engine.add_item(content: 'a')[:item_id]
+      engine.add_item(content: 'b')
+      engine.create_chunk(label: 'test', item_ids: [r1])
+      expect(engine.chunking_efficiency).to be_within(0.001).of(0.5)
+    end
+  end
+
+  describe '#chunking_report' do
+    it 'includes required report keys' do
+      report = engine.chunking_report
+      expect(report).to have_key(:total_items)
+      expect(report).to have_key(:total_chunks)
+      expect(report).to have_key(:unchunked_items)
+      expect(report).to have_key(:chunking_efficiency)
+      expect(report).to have_key(:working_memory)
+      expect(report).to have_key(:strongest_chunks)
+    end
+
+    it 'includes working memory capacity label' do
+      expect(engine.chunking_report[:working_memory][:label]).to be_a(Symbol)
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes items, chunks, and working_memory keys' do
+      h = engine.to_h
+      expect(h).to have_key(:items)
+      expect(h).to have_key(:chunks)
+      expect(h).to have_key(:working_memory)
+    end
+  end
+end

data/spec/legion/extensions/cognitive_chunking/helpers/constants_spec.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveChunking::Helpers::Constants do
+  describe 'core capacity constants' do
+    it 'defines MAX_ITEMS as 500' do
+      expect(described_class::MAX_ITEMS).to eq(500)
+    end
+
+    it 'defines MAX_CHUNKS as 200' do
+      expect(described_class::MAX_CHUNKS).to eq(200)
+    end
+
+    it 'defines WORKING_MEMORY_CAPACITY as 7' do
+      expect(described_class::WORKING_MEMORY_CAPACITY).to eq(7)
+    end
+
+    it 'defines CAPACITY_VARIANCE as 2' do
+      expect(described_class::CAPACITY_VARIANCE).to eq(2)
+    end
+  end
+
+  describe 'score constants' do
+    it 'defines DEFAULT_COHERENCE as 0.5' do
+      expect(described_class::DEFAULT_COHERENCE).to eq(0.5)
+    end
+
+    it 'defines COHERENCE_BOOST as 0.08' do
+      expect(described_class::COHERENCE_BOOST).to eq(0.08)
+    end
+
+    it 'defines COHERENCE_DECAY as 0.03' do
+      expect(described_class::COHERENCE_DECAY).to eq(0.03)
+    end
+
+    it 'defines RECALL_DECAY as 0.02' do
+      expect(described_class::RECALL_DECAY).to eq(0.02)
+    end
+
+    it 'defines RECALL_BOOST as 0.1' do
+      expect(described_class::RECALL_BOOST).to eq(0.1)
+    end
+  end
+
+  describe 'CHUNK_SIZE_LABELS' do
+    it 'labels size 7 as large' do
+      label = described_class::CHUNK_SIZE_LABELS.find { |range, _| range.cover?(7) }&.last
+      expect(label).to eq(:large)
+    end
+
+    it 'labels size 5 as medium' do
+      label = described_class::CHUNK_SIZE_LABELS.find { |range, _| range.cover?(5) }&.last
+      expect(label).to eq(:medium)
+    end
+
+    it 'labels size 3 as small' do
+      label = described_class::CHUNK_SIZE_LABELS.find { |range, _| range.cover?(3) }&.last
+      expect(label).to eq(:small)
+    end
+
+    it 'labels size 1 as micro' do
+      label = described_class::CHUNK_SIZE_LABELS.find { |range, _| range.cover?(1) }&.last
+      expect(label).to eq(:micro)
+    end
+  end
+
+  describe 'COHERENCE_LABELS' do
+    it 'labels 0.9 as tightly_chunked' do
+      label = described_class::COHERENCE_LABELS.find { |range, _| range.cover?(0.9) }&.last
+      expect(label).to eq(:tightly_chunked)
+    end
+
+    it 'labels 0.5 as loosely_chunked' do
+      label = described_class::COHERENCE_LABELS.find { |range, _| range.cover?(0.5) }&.last
+      expect(label).to eq(:loosely_chunked)
+    end
+
+    it 'labels 0.1 as unchunked' do
+      label = described_class::COHERENCE_LABELS.find { |range, _| range.cover?(0.1) }&.last
+      expect(label).to eq(:unchunked)
+    end
+  end
+
+  describe 'RECALL_LABELS' do
+    it 'labels 0.9 as instant' do
+      label = described_class::RECALL_LABELS.find { |range, _| range.cover?(0.9) }&.last
+      expect(label).to eq(:instant)
+    end
+
+    it 'labels 0.5 as moderate' do
+      label = described_class::RECALL_LABELS.find { |range, _| range.cover?(0.5) }&.last
+      expect(label).to eq(:moderate)
+    end
+
+    it 'labels 0.1 as forgotten' do
+      label = described_class::RECALL_LABELS.find { |range, _| range.cover?(0.1) }&.last
+      expect(label).to eq(:forgotten)
+    end
+  end
+
+  describe 'CAPACITY_LABELS' do
+    it 'labels 0.9 as overloaded' do
+      label = described_class::CAPACITY_LABELS.find { |range, _| range.cover?(0.9) }&.last
+      expect(label).to eq(:overloaded)
+    end
+
+    it 'labels 0.5 as comfortable' do
+      label = described_class::CAPACITY_LABELS.find { |range, _| range.cover?(0.5) }&.last
+      expect(label).to eq(:comfortable)
+    end
+
+    it 'labels 0.1 as empty' do
+      label = described_class::CAPACITY_LABELS.find { |range, _| range.cover?(0.1) }&.last
+      expect(label).to eq(:empty)
+    end
+  end
+end

data/spec/legion/extensions/cognitive_chunking/helpers/information_item_spec.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveChunking::Helpers::InformationItem do
+  let(:item) { described_class.new(content: 'bishop controls e4', domain: :chess) }
+
+  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('bishop controls e4')
+    end
+
+    it 'stores domain' do
+      expect(item.domain).to eq(:chess)
+    end
+
+    it 'defaults chunked to false' do
+      expect(item.chunked?).to be false
+    end
+
+    it 'defaults chunk_id to nil' do
+      expect(item.chunk_id).to be_nil
+    end
+
+    it 'sets created_at' do
+      expect(item.created_at).to be_a(Time)
+    end
+
+    it 'defaults domain to :general' do
+      plain = described_class.new(content: 'hello')
+      expect(plain.domain).to eq(:general)
+    end
+  end
+
+  describe '#assign_to_chunk!' do
+    it 'marks item as chunked' do
+      item.assign_to_chunk!(chunk_id: 'abc-123')
+      expect(item.chunked?).to be true
+    end
+
+    it 'stores the chunk_id' do
+      item.assign_to_chunk!(chunk_id: 'abc-123')
+      expect(item.chunk_id).to eq('abc-123')
+    end
+  end
+
+  describe '#unchunk!' do
+    before { item.assign_to_chunk!(chunk_id: 'abc-123') }
+
+    it 'clears chunked flag' do
+      item.unchunk!
+      expect(item.chunked?).to be false
+    end
+
+    it 'clears chunk_id' do
+      item.unchunk!
+      expect(item.chunk_id).to be_nil
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all expected keys' do
+      h = item.to_h
+      expect(h.keys).to contain_exactly(:id, :content, :domain, :chunked, :chunk_id, :created_at)
+    end
+
+    it 'reflects chunked state' do
+      item.assign_to_chunk!(chunk_id: 'xyz')
+      expect(item.to_h[:chunked]).to be true
+      expect(item.to_h[:chunk_id]).to eq('xyz')
+    end
+  end
+end