lex-agentic-attention 0.1.0

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Priming::Client do
+  subject(:client) { described_class.new }
+
+  describe '#initialize' do
+    it 'creates a default network' do
+      expect(client.network).to be_a(Legion::Extensions::Agentic::Attention::Priming::Helpers::ActivationNetwork)
+    end
+
+    it 'accepts an injected network' do
+      custom = Legion::Extensions::Agentic::Attention::Priming::Helpers::ActivationNetwork.new
+      injected = described_class.new(network: custom)
+      expect(injected.network).to equal(custom)
+    end
+  end
+
+  describe 'spreading activation lifecycle' do
+    it 'models semantic priming: dog -> bone -> fetch -> park' do
+      # Build a semantic network
+      client.add_concept(name: :dog, domain: :animals)
+      client.add_concept(name: :bone, domain: :objects)
+      client.add_concept(name: :fetch, domain: :activities)
+      client.add_concept(name: :park, domain: :places)
+
+      client.link_concepts(name_a: :dog, name_b: :bone, strength: 0.9)
+      client.link_concepts(name_a: :dog, name_b: :fetch, strength: 0.7)
+      client.link_concepts(name_a: :fetch, name_b: :park, strength: 0.6)
+
+      # Prime "dog" — should spread to bone, fetch, and park
+      client.prime_concept(name: :dog)
+
+      bone_check = client.check_primed(name: :bone)
+      fetch_check = client.check_primed(name: :fetch)
+      park_check = client.check_primed(name: :park)
+
+      expect(bone_check[:primed]).to be true
+      expect(fetch_check[:primed]).to be true
+      # Park is 2 hops away — may or may not be primed depending on spread
+      expect(park_check[:activation]).to be >= 0.0
+
+      # Dog should be most strongly primed
+      strongest = client.strongest_primes(count: 1)
+      expect(strongest[:primes].first[:name]).to eq(:dog)
+
+      # Decay over time
+      5.times { client.update_priming }
+      after_decay = client.check_primed(name: :bone)
+      expect(after_decay[:activation]).to be < bone_check[:activation]
+
+      # Eventually all priming fades
+      20.times { client.update_priming }
+      stats = client.priming_stats
+      expect(stats[:stats][:active_primes]).to eq(0)
+    end
+
+    it 'demonstrates domain-specific priming' do
+      # Animal domain
+      client.add_concept(name: :dog, domain: :animals)
+      client.add_concept(name: :cat, domain: :animals)
+      client.link_concepts(name_a: :dog, name_b: :cat, strength: 0.8)
+
+      # Vehicle domain
+      client.add_concept(name: :car, domain: :vehicles)
+      client.add_concept(name: :truck, domain: :vehicles)
+      client.link_concepts(name_a: :car, name_b: :truck, strength: 0.8)
+
+      # Prime one domain
+      client.prime_concept(name: :dog)
+
+      # Only animal domain should be primed
+      animals = client.primed_concepts(domain: :animals)
+      vehicles = client.primed_concepts(domain: :vehicles)
+      expect(animals[:count]).to be >= 1
+      expect(vehicles[:count]).to eq(0)
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/priming/helpers/activation_network_spec.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Priming::Helpers::ActivationNetwork do
+  subject(:network) { described_class.new }
+
+  let(:constants) { Legion::Extensions::Agentic::Attention::Priming::Helpers::Constants }
+
+  describe '#initialize' do
+    it 'starts empty' do
+      expect(network.concepts).to eq({})
+      expect(network.concept_count).to eq(0)
+    end
+  end
+
+  describe '#add_concept' do
+    it 'adds a concept node' do
+      concept = network.add_concept(name: :dog)
+      expect(concept.name).to eq(:dog)
+      expect(network.concept_count).to eq(1)
+    end
+
+    it 'returns existing concept if already present' do
+      first = network.add_concept(name: :dog)
+      second = network.add_concept(name: :dog)
+      expect(first).to equal(second)
+    end
+
+    it 'accepts domain' do
+      concept = network.add_concept(name: :dog, domain: :animals)
+      expect(concept.domain).to eq(:animals)
+    end
+  end
+
+  describe '#link' do
+    it 'creates bidirectional associations' do
+      network.link(:dog, :cat)
+      expect(network.concepts[:dog].association_strength(:cat)).to be > 0
+      expect(network.concepts[:cat].association_strength(:dog)).to be > 0
+    end
+
+    it 'auto-creates concepts if missing' do
+      network.link(:apple, :banana)
+      expect(network.concept_count).to eq(2)
+    end
+
+    it 'accepts custom strength' do
+      network.link(:dog, :cat, strength: 0.9)
+      expect(network.concepts[:dog].association_strength(:cat)).to eq(0.9)
+    end
+  end
+
+  describe '#prime' do
+    before do
+      network.link(:dog, :cat, strength: 0.8)
+      network.link(:cat, :mouse, strength: 0.6)
+      network.link(:mouse, :cheese, strength: 0.7)
+    end
+
+    it 'activates the target concept' do
+      network.prime(:dog)
+      expect(network.activation_for(:dog)).to be > 0
+    end
+
+    it 'spreads activation to neighbors' do
+      network.prime(:dog)
+      expect(network.activation_for(:cat)).to be > 0
+    end
+
+    it 'spreads with diminishing strength' do
+      network.prime(:dog)
+      expect(network.activation_for(:dog)).to be > network.activation_for(:cat)
+      expect(network.activation_for(:cat)).to be > network.activation_for(:mouse)
+    end
+
+    it 'respects max spread hops' do
+      network.link(:cheese, :crackers, strength: 0.5)
+      # Use a strong boost to ensure spread reaches far enough to test limits
+      network.prime(:dog, boost: 0.8)
+      # dog->cat->mouse->cheese = 3 hops (within limit), cheese->crackers = 4th hop (beyond limit)
+      cheese_activation = network.activation_for(:cheese)
+      crackers_activation = network.activation_for(:crackers)
+      # Crackers should have less activation than cheese (spread attenuates or stops at max hops)
+      expect(crackers_activation).to be <= cheese_activation
+    end
+
+    it 'can prime without spreading' do
+      network.prime(:dog, spread: false)
+      expect(network.activation_for(:dog)).to be > 0
+      expect(network.activation_for(:cat)).to eq(0.0)
+    end
+
+    it 'returns nil for unknown concept' do
+      expect(network.prime(:unknown)).to be_nil
+    end
+  end
+
+  describe '#activation_for' do
+    it 'returns 0 for unknown concepts' do
+      expect(network.activation_for(:unknown)).to eq(0.0)
+    end
+  end
+
+  describe '#primed_concepts' do
+    it 'returns only activated concepts' do
+      network.link(:dog, :cat)
+      network.prime(:dog, spread: false)
+      primed = network.primed_concepts
+      expect(primed.size).to eq(1)
+      expect(primed.first.name).to eq(:dog)
+    end
+  end
+
+  describe '#primed_in_domain' do
+    it 'filters by domain' do
+      network.add_concept(name: :dog, domain: :animals)
+      network.add_concept(name: :car, domain: :vehicles)
+      network.prime(:dog, spread: false)
+      network.prime(:car, spread: false)
+      animals = network.primed_in_domain(:animals)
+      expect(animals.size).to eq(1)
+      expect(animals.first.name).to eq(:dog)
+    end
+  end
+
+  describe '#decay_all' do
+    it 'reduces activation of all concepts' do
+      network.add_concept(name: :dog)
+      network.prime(:dog, spread: false)
+      initial = network.activation_for(:dog)
+      network.decay_all
+      expect(network.activation_for(:dog)).to be < initial
+    end
+
+    it 'eventually removes all priming' do
+      network.add_concept(name: :dog)
+      network.prime(:dog, spread: false)
+      20.times { network.decay_all }
+      expect(network.primed_concepts).to be_empty
+    end
+  end
+
+  describe '#neighbors' do
+    it 'returns associated concepts' do
+      network.link(:dog, :cat)
+      network.link(:dog, :bone)
+      nbrs = network.neighbors(:dog)
+      expect(nbrs.map(&:name)).to contain_exactly(:cat, :bone)
+    end
+
+    it 'returns empty for unknown concepts' do
+      expect(network.neighbors(:unknown)).to eq([])
+    end
+  end
+
+  describe '#strongest_primes' do
+    it 'returns top N primed concepts' do
+      network.add_concept(name: :a)
+      network.add_concept(name: :b)
+      network.add_concept(name: :c)
+      network.prime(:a, boost: 0.9, spread: false)
+      network.prime(:b, boost: 0.5, spread: false)
+      network.prime(:c, boost: 0.7, spread: false)
+      top = network.strongest_primes(2)
+      expect(top.map(&:name)).to eq(%i[a c])
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns network stats' do
+      h = network.to_h
+      expect(h).to include(:concept_count, :active_primes, :primed_concepts, :domains)
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/priming/helpers/concept_node_spec.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Priming::Helpers::ConceptNode do
+  subject(:node) { described_class.new(name: :dog, domain: :animals) }
+
+  let(:constants) { Legion::Extensions::Agentic::Attention::Priming::Helpers::Constants }
+
+  describe '#initialize' do
+    it 'stores name and domain' do
+      expect(node.name).to eq(:dog)
+      expect(node.domain).to eq(:animals)
+    end
+
+    it 'starts with zero activation' do
+      expect(node.activation).to eq(0.0)
+    end
+
+    it 'starts with no prime source' do
+      expect(node.prime_source).to be_nil
+    end
+
+    it 'starts with empty associations' do
+      expect(node.associations).to eq({})
+    end
+
+    it 'defaults domain to general' do
+      general = described_class.new(name: :thing)
+      expect(general.domain).to eq(:general)
+    end
+  end
+
+  describe '#primed?' do
+    it 'is false when activation is zero' do
+      expect(node.primed?).to be false
+    end
+
+    it 'is true when activation exceeds threshold' do
+      node.prime
+      expect(node.primed?).to be true
+    end
+  end
+
+  describe '#associate' do
+    it 'adds an association' do
+      node.associate(:cat)
+      expect(node.associations).to have_key(:cat)
+    end
+
+    it 'uses default strength' do
+      node.associate(:cat)
+      expect(node.association_strength(:cat)).to eq(constants::DEFAULT_ASSOCIATION_STRENGTH)
+    end
+
+    it 'accepts custom strength' do
+      node.associate(:cat, strength: 0.8)
+      expect(node.association_strength(:cat)).to eq(0.8)
+    end
+
+    it 'clamps strength within bounds' do
+      node.associate(:cat, strength: 5.0)
+      expect(node.association_strength(:cat)).to eq(constants::ASSOCIATION_CEILING)
+    end
+
+    it 'trims excess associations' do
+      (constants::MAX_ASSOCIATIONS + 5).times { |i| node.associate(:"concept_#{i}") }
+      expect(node.associations.size).to be <= constants::MAX_ASSOCIATIONS
+    end
+  end
+
+  describe '#strengthen_association' do
+    it 'increases association strength' do
+      node.associate(:cat)
+      initial = node.association_strength(:cat)
+      node.strengthen_association(:cat)
+      expect(node.association_strength(:cat)).to be > initial
+    end
+
+    it 'caps at ceiling' do
+      node.associate(:cat, strength: constants::ASSOCIATION_CEILING)
+      node.strengthen_association(:cat)
+      expect(node.association_strength(:cat)).to eq(constants::ASSOCIATION_CEILING)
+    end
+
+    it 'does nothing for unknown associations' do
+      node.strengthen_association(:unknown)
+      expect(node.associations).to be_empty
+    end
+  end
+
+  describe '#decay_associations' do
+    it 'reduces association strengths' do
+      node.associate(:cat)
+      initial = node.association_strength(:cat)
+      node.decay_associations
+      expect(node.association_strength(:cat)).to be < initial
+    end
+
+    it 'floors at minimum' do
+      node.associate(:cat, strength: constants::ASSOCIATION_FLOOR)
+      node.decay_associations
+      expect(node.association_strength(:cat)).to eq(constants::ASSOCIATION_FLOOR)
+    end
+  end
+
+  describe '#decay_activation' do
+    it 'reduces activation' do
+      node.prime
+      initial = node.activation
+      node.decay_activation
+      expect(node.activation).to be < initial
+    end
+
+    it 'floors at zero' do
+      node.activation = 0.01
+      node.decay_activation
+      expect(node.activation).to eq(0.0)
+    end
+
+    it 'clears prime source when not primed' do
+      node.prime(source: :test)
+      10.times { node.decay_activation }
+      expect(node.prime_source).to be_nil
+    end
+  end
+
+  describe '#prime' do
+    it 'increases activation' do
+      node.prime
+      expect(node.activation).to eq(constants::PRIME_BOOST)
+    end
+
+    it 'accepts custom boost' do
+      node.prime(boost: 0.5)
+      expect(node.activation).to eq(0.5)
+    end
+
+    it 'records source' do
+      node.prime(source: :visual)
+      expect(node.prime_source).to eq(:visual)
+    end
+
+    it 'caps activation at 1.0' do
+      node.prime(boost: 0.8)
+      node.prime(boost: 0.8)
+      expect(node.activation).to eq(1.0)
+    end
+  end
+
+  describe '#associated_names' do
+    it 'returns list of associated concept names' do
+      node.associate(:cat)
+      node.associate(:bone)
+      expect(node.associated_names).to contain_exactly(:cat, :bone)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns all fields' do
+      h = node.to_h
+      expect(h).to include(:name, :domain, :activation, :primed, :prime_source, :associations)
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Priming::Helpers::Constants do
+  describe 'PRIME_BOOST' do
+    it 'is a positive float' do
+      expect(described_class::PRIME_BOOST).to be > 0.0
+      expect(described_class::PRIME_BOOST).to be <= 1.0
+    end
+  end
+
+  describe 'PRIME_DECAY' do
+    it 'is a positive float less than boost' do
+      expect(described_class::PRIME_DECAY).to be > 0.0
+      expect(described_class::PRIME_DECAY).to be < described_class::PRIME_BOOST
+    end
+  end
+
+  describe 'SPREAD_FACTOR' do
+    it 'is between 0 and 1' do
+      expect(described_class::SPREAD_FACTOR).to be_between(0.0, 1.0).exclusive
+    end
+  end
+
+  describe 'MAX_SPREAD_HOPS' do
+    it 'is a positive integer' do
+      expect(described_class::MAX_SPREAD_HOPS).to be_a(Integer)
+      expect(described_class::MAX_SPREAD_HOPS).to be > 0
+    end
+  end
+
+  describe 'PRIME_THRESHOLD' do
+    it 'is a small positive float' do
+      expect(described_class::PRIME_THRESHOLD).to be > 0.0
+      expect(described_class::PRIME_THRESHOLD).to be < described_class::PRIME_BOOST
+    end
+  end
+
+  describe 'association constants' do
+    it 'has floor less than ceiling' do
+      expect(described_class::ASSOCIATION_FLOOR).to be < described_class::ASSOCIATION_CEILING
+    end
+
+    it 'has default between floor and ceiling' do
+      expect(described_class::DEFAULT_ASSOCIATION_STRENGTH).to be_between(
+        described_class::ASSOCIATION_FLOOR, described_class::ASSOCIATION_CEILING
+      )
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/priming/runners/priming_spec.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Priming::Runners::Priming do
+  let(:runner) do
+    obj = Object.new
+    obj.extend(described_class)
+    obj
+  end
+
+  before do
+    runner.add_concept(name: :dog, domain: :animals)
+    runner.add_concept(name: :cat, domain: :animals)
+    runner.add_concept(name: :car, domain: :vehicles)
+    runner.link_concepts(name_a: :dog, name_b: :cat, strength: 0.8)
+  end
+
+  describe '#prime_concept' do
+    it 'primes a concept and returns its state' do
+      result = runner.prime_concept(name: :dog)
+      expect(result[:success]).to be true
+      expect(result[:concept][:activation]).to be > 0
+      expect(result[:concept][:primed]).to be true
+    end
+
+    it 'spreads activation to linked concepts' do
+      runner.prime_concept(name: :dog)
+      cat_check = runner.check_primed(name: :cat)
+      expect(cat_check[:primed]).to be true
+    end
+
+    it 'does not spread to unlinked concepts' do
+      runner.prime_concept(name: :dog)
+      car_check = runner.check_primed(name: :car)
+      expect(car_check[:primed]).to be false
+    end
+
+    it 'accepts custom boost' do
+      result = runner.prime_concept(name: :dog, boost: 0.1, spread: false)
+      expect(result[:concept][:activation]).to eq(0.1)
+    end
+
+    it 'auto-creates concepts if needed' do
+      result = runner.prime_concept(name: :fish)
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#add_concept' do
+    it 'adds a new concept' do
+      result = runner.add_concept(name: :bird, domain: :animals)
+      expect(result[:success]).to be true
+      expect(result[:concept][:name]).to eq(:bird)
+    end
+  end
+
+  describe '#link_concepts' do
+    it 'links two concepts' do
+      result = runner.link_concepts(name_a: :dog, name_b: :car)
+      expect(result[:success]).to be true
+      expect(result[:strength]).to be > 0
+    end
+  end
+
+  describe '#update_priming' do
+    it 'decays all activations' do
+      runner.prime_concept(name: :dog)
+      initial = runner.check_primed(name: :dog)[:activation]
+      runner.update_priming
+      after = runner.check_primed(name: :dog)[:activation]
+      expect(after).to be < initial
+    end
+
+    it 'returns active prime count' do
+      runner.prime_concept(name: :dog)
+      result = runner.update_priming
+      expect(result[:success]).to be true
+      expect(result).to include(:active_primes, :concept_count)
+    end
+  end
+
+  describe '#check_primed' do
+    it 'returns priming status' do
+      result = runner.check_primed(name: :dog)
+      expect(result[:success]).to be true
+      expect(result[:primed]).to be false
+      expect(result[:activation]).to eq(0.0)
+    end
+
+    it 'shows primed after priming' do
+      runner.prime_concept(name: :dog)
+      result = runner.check_primed(name: :dog)
+      expect(result[:primed]).to be true
+    end
+  end
+
+  describe '#primed_concepts' do
+    it 'returns all primed concepts' do
+      runner.prime_concept(name: :dog)
+      result = runner.primed_concepts
+      expect(result[:success]).to be true
+      expect(result[:count]).to be >= 1
+    end
+
+    it 'filters by domain' do
+      runner.prime_concept(name: :dog)
+      runner.prime_concept(name: :car, spread: false)
+      animals = runner.primed_concepts(domain: :animals)
+      vehicles = runner.primed_concepts(domain: :vehicles)
+      expect(animals[:count]).to be >= 1
+      expect(vehicles[:count]).to eq(1)
+    end
+  end
+
+  describe '#strongest_primes' do
+    it 'returns top primed concepts' do
+      runner.prime_concept(name: :dog, boost: 0.9, spread: false)
+      runner.prime_concept(name: :cat, boost: 0.3, spread: false)
+      result = runner.strongest_primes(count: 1)
+      expect(result[:primes].first[:name]).to eq(:dog)
+    end
+  end
+
+  describe '#neighbors_for' do
+    it 'returns linked concepts' do
+      result = runner.neighbors_for(name: :dog)
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(1)
+      expect(result[:neighbors].first[:name]).to eq(:cat)
+    end
+  end
+
+  describe '#priming_stats' do
+    it 'returns network summary' do
+      result = runner.priming_stats
+      expect(result[:success]).to be true
+      expect(result[:stats]).to include(:concept_count, :active_primes)
+    end
+  end
+end

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Prism::Client do
+  subject(:client) { described_class.new }
+
+  describe '#initialize' do
+    it 'creates a client with a default engine' do
+      expect(client.engine).to be_a(Legion::Extensions::Agentic::Attention::Prism::Helpers::PrismEngine)
+    end
+
+    it 'accepts an injected engine' do
+      custom = Legion::Extensions::Agentic::Attention::Prism::Helpers::PrismEngine.new
+      c = described_class.new(engine: custom)
+      expect(c.engine).to be(custom)
+    end
+
+    it 'accepts extra kwargs via ** splat' do
+      expect { described_class.new(extra: :param) }.not_to raise_error
+    end
+  end
+
+  describe 'runner delegation' do
+    let(:engine) { Legion::Extensions::Agentic::Attention::Prism::Helpers::PrismEngine.new }
+    subject(:client) { described_class.new(engine: engine) }
+
+    it 'delegates create_beam to the runner' do
+      result = client.create_beam(domain: :test, content: 'client test idea')
+      expect(result[:success]).to be true
+    end
+
+    it 'delegates decompose to the runner' do
+      id = client.create_beam(domain: :test, content: 'decompose me')[:beam_id]
+      result = client.decompose(beam_id: id)
+      expect(result[:success]).to be true
+      expect(result[:component_count]).to eq(8)
+    end
+
+    it 'delegates recompose to the runner' do
+      result = client.recompose(component_ids: [])
+      expect(result[:success]).to be true
+    end
+
+    it 'delegates attenuate_all to the runner' do
+      id = client.create_beam(domain: :d, content: 'attenuate me')[:beam_id]
+      client.decompose(beam_id: id)
+      result = client.attenuate_all
+      expect(result[:success]).to be true
+    end
+
+    it 'delegates dominant_bands to the runner' do
+      result = client.dominant_bands
+      expect(result[:success]).to be true
+    end
+
+    it 'delegates most_intense to the runner' do
+      result = client.most_intense
+      expect(result[:success]).to be true
+      expect(result[:components]).to be_an(Array)
+    end
+
+    it 'delegates spectral_report to the runner' do
+      result = client.spectral_report
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe 'full decompose-recompose cycle' do
+    let(:engine) { Legion::Extensions::Agentic::Attention::Prism::Helpers::PrismEngine.new }
+    subject(:client) { described_class.new(engine: engine) }
+
+    it 'completes a full white-light-in rainbow-out-recombine cycle' do
+      idea = 'The mind arises from complexity through emergent self-organization of neural substrates'
+      cr = client.create_beam(domain: :philosophy, content: idea)
+      expect(cr[:success]).to be true
+
+      dr = client.decompose(beam_id: cr[:beam_id])
+      expect(dr[:success]).to be true
+      expect(dr[:component_count]).to eq(8)
+
+      beam = engine.get_beam(cr[:beam_id])
+      ids  = beam.components.reject(&:faded?).map { |c| "#{cr[:beam_id]}:#{c.band}" }
+      rr   = client.recompose(component_ids: ids)
+      expect(rr[:success]).to be true
+    end
+  end
+end