lex-agentic-integration 0.1.0

data/spec/legion/extensions/agentic/integration/context/client_spec.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Integration::Context::Client do
+  let(:client) { described_class.new }
+
+  it 'can be instantiated' do
+    expect(client).to be_a(described_class)
+  end
+
+  it 'includes all runner methods' do
+    expect(client).to respond_to(:create_context)
+    expect(client).to respond_to(:activate_context)
+    expect(client).to respond_to(:detect_context)
+    expect(client).to respond_to(:auto_switch)
+    expect(client).to respond_to(:current_context)
+    expect(client).to respond_to(:update_context)
+    expect(client).to respond_to(:add_cue)
+    expect(client).to respond_to(:frames_in_domain)
+    expect(client).to respond_to(:remove_context)
+    expect(client).to respond_to(:context_stats)
+  end
+
+  it 'exposes the context manager' do
+    expect(client.context_manager).to be_a(Legion::Extensions::Agentic::Integration::Context::Helpers::ContextManager)
+  end
+
+  describe 'full lifecycle' do
+    it 'creates, activates, switches, and decays contexts' do
+      # Create two contexts
+      work = client.create_context(name: :work, domain: :task, cues: %i[code debug review])[:frame]
+      client.create_context(name: :meeting, domain: :social, cues: %i[discuss plan agenda])[:frame]
+
+      # Activate work
+      client.activate_context(frame_id: work[:id])
+      expect(client.current_context[:frame][:name]).to eq(:work)
+
+      # Detect meeting context from cues
+      detected = client.detect_context(input_cues: %i[discuss plan])
+      expect(detected[:count]).to be >= 1
+
+      # Auto-switch to meeting
+      switched = client.auto_switch(input_cues: %i[discuss plan agenda])
+      expect(switched[:switched]).to be true
+
+      # Verify current context changed
+      expect(client.current_context[:frame][:name]).to eq(:meeting)
+
+      # Check stats
+      stats = client.context_stats[:stats]
+      expect(stats[:switch_count]).to eq(1)
+      expect(stats[:frame_count]).to eq(2)
+
+      # Tick decay
+      client.update_context
+      expect(client.context_stats[:stats][:frame_count]).to be >= 1
+    end
+  end
+end

data/spec/legion/extensions/agentic/integration/context/helpers/constants_spec.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Integration::Context::Helpers::Constants do
+  it 'defines MAX_FRAMES' do
+    expect(described_class::MAX_FRAMES).to eq(50)
+  end
+
+  it 'defines MAX_FRAME_STACK' do
+    expect(described_class::MAX_FRAME_STACK).to eq(10)
+  end
+
+  it 'defines SWITCH_COST' do
+    expect(described_class::SWITCH_COST).to eq(0.15)
+  end
+
+  it 'defines FAMILIARITY_ALPHA' do
+    expect(described_class::FAMILIARITY_ALPHA).to eq(0.12)
+  end
+
+  it 'defines FRAME_LABELS covering 0.0..1.0' do
+    labels = described_class::FRAME_LABELS
+    [0.0, 0.1, 0.3, 0.5, 0.7, 0.9, 1.0].each do |val|
+      matched = labels.any? { |range, _| range.cover?(val) }
+      expect(matched).to be(true), "Expected #{val} to match a label range"
+    end
+  end
+
+  it 'has all expected FRAME_LABELS values' do
+    values = described_class::FRAME_LABELS.values
+    expect(values).to contain_exactly(:dominant, :active, :background, :fading)
+  end
+end

data/spec/legion/extensions/agentic/integration/context/helpers/context_manager_spec.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Integration::Context::Helpers::ContextManager do
+  let(:manager) { described_class.new }
+
+  describe '#create_frame' do
+    it 'creates and stores a frame' do
+      frame = manager.create_frame(name: :work, domain: :task, cues: %i[code review])
+      expect(frame).to be_a(Legion::Extensions::Agentic::Integration::Context::Helpers::Frame)
+      expect(manager.frames.size).to eq(1)
+    end
+
+    it 'trims frames when exceeding MAX_FRAMES' do
+      max = Legion::Extensions::Agentic::Integration::Context::Helpers::Constants::MAX_FRAMES
+      (max + 5).times { |i| manager.create_frame(name: :"frame_#{i}") }
+      expect(manager.frames.size).to eq(max)
+    end
+  end
+
+  describe '#activate' do
+    let(:frame) { manager.create_frame(name: :work, cues: %i[code]) }
+
+    it 'activates a frame and pushes to stack' do
+      result = manager.activate(frame.id)
+      expect(result[:frame]).to eq(frame)
+      expect(manager.current_frame).to eq(frame)
+    end
+
+    it 'returns nil for unknown frame' do
+      expect(manager.activate('nonexistent')).to be_nil
+    end
+
+    it 'computes switch cost when changing frames' do
+      f1 = manager.create_frame(name: :work, cues: %i[code])
+      f2 = manager.create_frame(name: :meeting, cues: %i[discuss])
+      manager.activate(f1.id)
+      result = manager.activate(f2.id)
+      expect(result[:switch_cost]).to be_a(Float)
+      expect(result[:switch_cost]).to be > 0.0
+    end
+
+    it 'records switch history' do
+      f1 = manager.create_frame(name: :work)
+      f2 = manager.create_frame(name: :break)
+      manager.activate(f1.id)
+      manager.activate(f2.id)
+      expect(manager.switch_history.size).to eq(1)
+    end
+
+    it 'caps the active stack at MAX_FRAME_STACK' do
+      max = Legion::Extensions::Agentic::Integration::Context::Helpers::Constants::MAX_FRAME_STACK
+      frames = (max + 3).times.map { |i| manager.create_frame(name: :"f_#{i}") }
+      frames.each { |f| manager.activate(f.id) }
+      expect(manager.active_stack.size).to be <= max
+    end
+  end
+
+  describe '#detect_context' do
+    before do
+      manager.create_frame(name: :coding, cues: %i[code debug test])
+      manager.create_frame(name: :design, cues: %i[sketch wireframe review])
+      manager.create_frame(name: :ops, cues: %i[deploy monitor])
+    end
+
+    it 'returns matching frames above relevance threshold' do
+      results = manager.detect_context(%i[code test])
+      expect(results.size).to be >= 1
+      expect(results.first[:frame].name).to eq(:coding)
+    end
+
+    it 'returns empty when no cues match' do
+      results = manager.detect_context(%i[sleep eat])
+      expect(results).to be_empty
+    end
+
+    it 'sorts by relevance descending' do
+      results = manager.detect_context(%i[code debug test])
+      next unless results.size > 1
+
+      expect(results.first[:relevance]).to be >= results.last[:relevance]
+    end
+  end
+
+  describe '#auto_switch' do
+    it 'switches to the best matching frame' do
+      f1 = manager.create_frame(name: :coding, cues: %i[code debug test])
+      manager.create_frame(name: :ops, cues: %i[deploy monitor])
+      manager.activate(f1.id)
+
+      result = manager.auto_switch(%i[deploy monitor alert])
+      expect(result).not_to be_nil
+      expect(result[:frame].name).to eq(:ops)
+    end
+
+    it 'returns nil when current frame is already the best match' do
+      f1 = manager.create_frame(name: :coding, cues: %i[code debug test])
+      manager.activate(f1.id)
+
+      result = manager.auto_switch(%i[code debug])
+      expect(result).to be_nil
+    end
+
+    it 'returns nil when no cues match' do
+      manager.create_frame(name: :coding, cues: %i[code])
+      result = manager.auto_switch(%i[sleep dream])
+      expect(result).to be_nil
+    end
+  end
+
+  describe '#find and #find_by_name' do
+    it 'finds a frame by id' do
+      frame = manager.create_frame(name: :work)
+      expect(manager.find(frame.id)).to eq(frame)
+    end
+
+    it 'finds frames by name' do
+      manager.create_frame(name: :work)
+      manager.create_frame(name: :work)
+      expect(manager.find_by_name(:work).size).to eq(2)
+    end
+  end
+
+  describe '#in_domain' do
+    it 'returns frames for the given domain' do
+      manager.create_frame(name: :a, domain: :task)
+      manager.create_frame(name: :b, domain: :social)
+      manager.create_frame(name: :c, domain: :task)
+      expect(manager.in_domain(:task).size).to eq(2)
+    end
+  end
+
+  describe '#decay_all' do
+    it 'decays all frames' do
+      f = manager.create_frame(name: :work)
+      initial = f.strength
+      manager.decay_all
+      expect(f.strength).to be < initial
+    end
+
+    it 'removes stale frames' do
+      f = manager.create_frame(name: :old)
+      100.times { f.decay }
+      manager.decay_all
+      expect(manager.frames).not_to include(f)
+    end
+  end
+
+  describe '#remove' do
+    it 'removes a frame by id' do
+      f = manager.create_frame(name: :work)
+      manager.remove(f.id)
+      expect(manager.frames).to be_empty
+    end
+
+    it 'removes from active stack too' do
+      f = manager.create_frame(name: :work)
+      manager.activate(f.id)
+      manager.remove(f.id)
+      expect(manager.active_stack).to be_empty
+    end
+  end
+
+  describe '#switch_cost_average' do
+    it 'returns 0.0 with no switches' do
+      expect(manager.switch_cost_average).to eq(0.0)
+    end
+
+    it 'computes the average switch cost' do
+      f1 = manager.create_frame(name: :a)
+      f2 = manager.create_frame(name: :b)
+      manager.activate(f1.id)
+      manager.activate(f2.id)
+      expect(manager.switch_cost_average).to be > 0.0
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns summary statistics' do
+      manager.create_frame(name: :work, domain: :task)
+      h = manager.to_h
+      expect(h).to have_key(:frame_count)
+      expect(h).to have_key(:active_frame)
+      expect(h).to have_key(:stack_depth)
+      expect(h).to have_key(:switch_count)
+      expect(h).to have_key(:avg_switch_cost)
+      expect(h).to have_key(:by_domain)
+      expect(h[:frame_count]).to eq(1)
+    end
+  end
+end

data/spec/legion/extensions/agentic/integration/context/helpers/frame_spec.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Integration::Context::Helpers::Frame do
+  let(:frame) { described_class.new(name: :work, domain: :task, cues: %i[code review debug]) }
+
+  describe '#initialize' do
+    it 'sets name and domain' do
+      expect(frame.name).to eq(:work)
+      expect(frame.domain).to eq(:task)
+    end
+
+    it 'starts with strength 1.0' do
+      expect(frame.strength).to eq(1.0)
+    end
+
+    it 'starts with default familiarity' do
+      expect(frame.familiarity).to be_within(0.01).of(Legion::Extensions::Agentic::Integration::Context::Helpers::Constants::DEFAULT_FAMILIARITY)
+    end
+
+    it 'stores cues' do
+      expect(frame.cues).to eq(%i[code review debug])
+    end
+
+    it 'starts with zero activation count' do
+      expect(frame.activation_count).to eq(0)
+    end
+
+    it 'has a UUID id' do
+      expect(frame.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'caps cues at MAX_CUES_PER_FRAME' do
+      many_cues = (1..50).map { |i| :"cue_#{i}" }
+      f = described_class.new(name: :big, cues: many_cues)
+      expect(f.cues.size).to eq(Legion::Extensions::Agentic::Integration::Context::Helpers::Constants::MAX_CUES_PER_FRAME)
+    end
+  end
+
+  describe '#activate' do
+    it 'increments activation count' do
+      frame.activate
+      expect(frame.activation_count).to eq(1)
+    end
+
+    it 'updates last_activated' do
+      before = frame.last_activated
+      sleep 0.01
+      frame.activate
+      expect(frame.last_activated).to be >= before
+    end
+
+    it 'increases familiarity' do
+      initial = frame.familiarity
+      frame.activate
+      expect(frame.familiarity).to be > initial
+    end
+  end
+
+  describe '#deactivate' do
+    it 'decreases familiarity' do
+      frame.activate
+      raised = frame.familiarity
+      frame.deactivate
+      expect(frame.familiarity).to be < raised
+    end
+  end
+
+  describe '#decay' do
+    it 'reduces strength' do
+      initial = frame.strength
+      frame.decay
+      expect(frame.strength).to be < initial
+    end
+
+    it 'does not go below zero' do
+      100.times { frame.decay }
+      expect(frame.strength).to be >= 0.0
+    end
+  end
+
+  describe '#match_score' do
+    it 'returns 1.0 for perfect match' do
+      expect(frame.match_score(%i[code review debug])).to eq(1.0)
+    end
+
+    it 'returns partial score for partial match' do
+      score = frame.match_score(%i[code deploy])
+      expect(score).to be_within(0.01).of(1.0 / 3.0)
+    end
+
+    it 'returns 0.0 for no overlap' do
+      expect(frame.match_score(%i[sleep eat])).to eq(0.0)
+    end
+
+    it 'returns 0.0 for empty input' do
+      expect(frame.match_score([])).to eq(0.0)
+    end
+
+    it 'returns 0.0 for frame with no cues' do
+      empty = described_class.new(name: :empty)
+      expect(empty.match_score(%i[code])).to eq(0.0)
+    end
+  end
+
+  describe '#add_cue' do
+    it 'adds a new cue' do
+      frame.add_cue(:deploy)
+      expect(frame.cues).to include(:deploy)
+    end
+
+    it 'does not duplicate existing cue' do
+      frame.add_cue(:code)
+      expect(frame.cues.count(:code)).to eq(1)
+    end
+
+    it 'caps cues at MAX_CUES_PER_FRAME' do
+      40.times { |i| frame.add_cue(:"extra_#{i}") }
+      expect(frame.cues.size).to be <= Legion::Extensions::Agentic::Integration::Context::Helpers::Constants::MAX_CUES_PER_FRAME
+    end
+  end
+
+  describe '#remove_cue' do
+    it 'removes the specified cue' do
+      frame.remove_cue(:code)
+      expect(frame.cues).not_to include(:code)
+    end
+  end
+
+  describe '#label' do
+    it 'returns :dominant for fresh frame' do
+      expect(frame.label).to eq(:dominant)
+    end
+
+    it 'returns :fading for heavily decayed frame' do
+      60.times { frame.decay }
+      expect(frame.label).to eq(:fading)
+    end
+  end
+
+  describe '#stale?' do
+    it 'is not stale when fresh' do
+      expect(frame.stale?).to be false
+    end
+
+    it 'becomes stale after heavy decay' do
+      100.times { frame.decay }
+      expect(frame.stale?).to be true
+    end
+  end
+
+  describe '#to_h' do
+    it 'contains all expected keys' do
+      h = frame.to_h
+      expect(h).to have_key(:id)
+      expect(h).to have_key(:name)
+      expect(h).to have_key(:domain)
+      expect(h).to have_key(:strength)
+      expect(h).to have_key(:familiarity)
+      expect(h).to have_key(:label)
+      expect(h).to have_key(:cues)
+      expect(h).to have_key(:activation_count)
+    end
+  end
+end

data/spec/legion/extensions/agentic/integration/context/runners/context_spec.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Integration::Context::Runners::Context do
+  let(:client) { Legion::Extensions::Agentic::Integration::Context::Client.new }
+
+  describe '#create_context' do
+    it 'returns success with frame data' do
+      result = client.create_context(name: :work, domain: :task, cues: %i[code review])
+      expect(result[:success]).to be true
+      expect(result[:frame][:name]).to eq(:work)
+      expect(result[:frame][:domain]).to eq(:task)
+    end
+  end
+
+  describe '#activate_context' do
+    it 'activates a frame by id' do
+      frame = client.create_context(name: :work)[:frame]
+      result = client.activate_context(frame_id: frame[:id])
+      expect(result[:success]).to be true
+      expect(result[:frame][:name]).to eq(:work)
+    end
+
+    it 'returns failure for unknown id' do
+      result = client.activate_context(frame_id: 'nonexistent')
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:not_found)
+    end
+
+    it 'reports switch cost when changing frames' do
+      f1 = client.create_context(name: :work)[:frame]
+      f2 = client.create_context(name: :break)[:frame]
+      client.activate_context(frame_id: f1[:id])
+      result = client.activate_context(frame_id: f2[:id])
+      expect(result[:switch_cost]).to be > 0.0
+    end
+  end
+
+  describe '#detect_context' do
+    before do
+      client.create_context(name: :coding, cues: %i[code debug test])
+      client.create_context(name: :ops, cues: %i[deploy monitor alert])
+    end
+
+    it 'returns matching candidates' do
+      result = client.detect_context(input_cues: %i[code debug])
+      expect(result[:success]).to be true
+      expect(result[:count]).to be >= 1
+      expect(result[:best][:name]).to eq(:coding)
+    end
+
+    it 'returns empty when nothing matches' do
+      result = client.detect_context(input_cues: %i[sleep dream])
+      expect(result[:count]).to eq(0)
+    end
+  end
+
+  describe '#auto_switch' do
+    it 'switches to a better matching context' do
+      f1 = client.create_context(name: :coding, cues: %i[code debug])[:frame]
+      client.create_context(name: :ops, cues: %i[deploy monitor])
+      client.activate_context(frame_id: f1[:id])
+
+      result = client.auto_switch(input_cues: %i[deploy monitor alert])
+      expect(result[:success]).to be true
+      expect(result[:switched]).to be true
+    end
+
+    it 'does not switch when current is best' do
+      f1 = client.create_context(name: :coding, cues: %i[code debug])[:frame]
+      client.activate_context(frame_id: f1[:id])
+
+      result = client.auto_switch(input_cues: %i[code debug])
+      expect(result[:switched]).to be false
+    end
+  end
+
+  describe '#current_context' do
+    it 'returns nil when no frame is active' do
+      result = client.current_context
+      expect(result[:success]).to be true
+      expect(result[:frame]).to be_nil
+    end
+
+    it 'returns the active frame' do
+      f = client.create_context(name: :work)[:frame]
+      client.activate_context(frame_id: f[:id])
+      result = client.current_context
+      expect(result[:frame][:name]).to eq(:work)
+    end
+  end
+
+  describe '#update_context' do
+    it 'decays and returns frame count' do
+      client.create_context(name: :work)
+      result = client.update_context
+      expect(result[:success]).to be true
+      expect(result[:frame_count]).to eq(1)
+    end
+  end
+
+  describe '#add_cue' do
+    it 'adds a cue to a frame' do
+      f = client.create_context(name: :work, cues: %i[code])[:frame]
+      result = client.add_cue(frame_id: f[:id], cue: :review)
+      expect(result[:success]).to be true
+      expect(result[:frame][:cues]).to include(:review)
+    end
+
+    it 'returns failure for unknown frame' do
+      result = client.add_cue(frame_id: 'bad', cue: :test)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#frames_in_domain' do
+    it 'returns frames for the given domain' do
+      client.create_context(name: :a, domain: :task)
+      client.create_context(name: :b, domain: :social)
+      result = client.frames_in_domain(domain: :task)
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#remove_context' do
+    it 'removes a frame' do
+      f = client.create_context(name: :work)[:frame]
+      result = client.remove_context(frame_id: f[:id])
+      expect(result[:success]).to be true
+      expect(client.context_stats[:stats][:frame_count]).to eq(0)
+    end
+  end
+
+  describe '#context_stats' do
+    it 'returns summary statistics' do
+      client.create_context(name: :work, domain: :task)
+      result = client.context_stats
+      expect(result[:success]).to be true
+      expect(result[:stats][:frame_count]).to eq(1)
+      expect(result[:stats]).to have_key(:by_domain)
+    end
+  end
+end

data/spec/legion/extensions/agentic/integration/distributed_cognition/client_spec.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Integration::DistributedCognition::Client do
+  subject(:client) { described_class.new }
+
+  it 'registers and contributes' do
+    created = client.register_cognitive_participant(
+      name: 'worker', participant_type: :agent, domain: :test
+    )
+    result = client.record_cognitive_contribution(
+      participant_id: created[:participant_id],
+      contribution_type: :computation, success: true
+    )
+    expect(result[:success]).to be true
+  end
+
+  it 'returns stats' do
+    result = client.distributed_cognition_stats
+    expect(result[:success]).to be true
+  end
+end