lex-priming 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 43f24c3a9f138b82377240b94d0dc119248eef77e33471cdea3e3cecc441c214
+  data.tar.gz: be0034521b593b83159a3ee7004020145941c2bc4e83c20a75b69fe03d333763
+SHA512:
+  metadata.gz: 977af104675e1ee4e6ed965846932eb9443cdbbae17d2d3d22a823e50f197e3e8db07d0efaeb6408a4a71f57eccfce09f27bb3f72904b97238103e4beadbc67e
+  data.tar.gz: e402a48a4c880eafe14fb2156a0101a68c624e207ffed52930d1bb3eebc93ff5ce240f864720cf581cf739993dab5c4baf1caa1add3d8f687ecc6bff49a96930

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Iverson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,54 @@
+# lex-priming
+
+Associative activation network for the LegionIO cognitive architecture. Implements spreading activation priming across linked concept nodes.
+
+## What It Does
+
+Maintains a network of concept nodes connected by association strengths. When a concept is primed, its activation is boosted and that activation spreads through the network via BFS — each hop attenuated by the spread factor and association strength. Concepts decay each tick. Supports querying which concepts are currently primed, finding the strongest activations, and retrieving neighbors.
+
+## Usage
+
+```ruby
+client = Legion::Extensions::Priming::Client.new
+
+# Build the concept network
+client.add_concept(name: :authentication, domain: :security)
+client.add_concept(name: :credentials, domain: :security)
+client.add_concept(name: :session_token, domain: :security)
+client.link_concepts(name_a: :authentication, name_b: :credentials, strength: 0.8)
+client.link_concepts(name_a: :credentials, name_b: :session_token, strength: 0.7)
+
+# Prime a concept (activation spreads to neighbors)
+client.prime_concept(name: :authentication, boost: 0.5, spread: true)
+
+# Check which concepts are now active
+client.primed_concepts
+# => { success: true, concepts: [
+#      { name: :authentication, activation: 0.5, domain: :security },
+#      { name: :credentials, activation: 0.175, domain: :security },
+#      { name: :session_token, activation: 0.031, domain: :security }
+#    ], count: 3 }
+
+# Top activations
+client.strongest_primes(count: 3)
+
+# Check a specific concept
+client.check_primed(name: :credentials)
+# => { success: true, name: :credentials, activation: 0.175, primed: true, source: :authentication }
+
+# Each tick: decay activations
+client.update_priming
+client.priming_stats
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lib/legion/extensions/priming/client.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Priming
+      class Client
+        include Runners::Priming
+
+        attr_reader :network
+
+        def initialize(network: nil, **)
+          @network = network || Helpers::ActivationNetwork.new
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/priming/helpers/activation_network.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Priming
+      module Helpers
+        class ActivationNetwork
+          attr_reader :concepts
+
+          def initialize
+            @concepts = {}
+          end
+
+          def add_concept(name:, domain: :general)
+            @concepts[name] ||= ConceptNode.new(name: name, domain: domain)
+            trim_concepts
+            @concepts[name]
+          end
+
+          def link(name_a, name_b, strength: Constants::DEFAULT_ASSOCIATION_STRENGTH)
+            add_concept(name: name_a) unless @concepts.key?(name_a)
+            add_concept(name: name_b) unless @concepts.key?(name_b)
+            @concepts[name_a].associate(name_b, strength: strength)
+            @concepts[name_b].associate(name_a, strength: strength)
+          end
+
+          def prime(name, boost: Constants::PRIME_BOOST, source: nil, spread: true)
+            concept = @concepts[name]
+            return nil unless concept
+
+            concept.prime(boost: boost, source: source)
+            spread_activation(name, boost) if spread
+            concept
+          end
+
+          def activation_for(name)
+            concept = @concepts[name]
+            concept ? concept.activation : 0.0
+          end
+
+          def primed_concepts
+            @concepts.values.select(&:primed?)
+          end
+
+          def primed_in_domain(domain)
+            @concepts.values.select { |c| c.domain == domain && c.primed? }
+          end
+
+          def decay_all
+            @concepts.each_value do |concept|
+              concept.decay_activation
+              concept.decay_associations
+            end
+          end
+
+          def neighbors(name)
+            concept = @concepts[name]
+            return [] unless concept
+
+            concept.associated_names.filter_map { |n| @concepts[n] }
+          end
+
+          def concept_count
+            @concepts.size
+          end
+
+          def active_prime_count
+            primed_concepts.size
+          end
+
+          def strongest_primes(count = 5)
+            primed_concepts.sort_by { |c| -c.activation }.first(count)
+          end
+
+          def to_h
+            {
+              concept_count:   @concepts.size,
+              active_primes:   active_prime_count,
+              primed_concepts: primed_concepts.map { |c| { name: c.name, activation: c.activation.round(4) } },
+              domains:         @concepts.values.map(&:domain).uniq
+            }
+          end
+
+          private
+
+          def spread_activation(source_name, initial_boost)
+            visited = Set.new([source_name])
+            queue = [[source_name, initial_boost, 0]]
+
+            while queue.any?
+              current_name, current_boost, depth = queue.shift
+              next if depth >= Constants::MAX_SPREAD_HOPS
+
+              concept = @concepts[current_name]
+              next unless concept
+
+              concept.associated_names.each do |neighbor_name|
+                next if visited.include?(neighbor_name)
+
+                visited.add(neighbor_name)
+                neighbor = @concepts[neighbor_name]
+                next unless neighbor
+
+                strength = concept.association_strength(neighbor_name)
+                spread_boost = current_boost * Constants::SPREAD_FACTOR * strength
+                next if spread_boost < Constants::PRIME_THRESHOLD
+
+                neighbor.prime(boost: spread_boost, source: source_name)
+                concept.strengthen_association(neighbor_name)
+                queue << [neighbor_name, spread_boost, depth + 1]
+              end
+            end
+          end
+
+          def trim_concepts
+            return unless @concepts.size > Constants::MAX_CONCEPTS
+
+            sorted = @concepts.sort_by { |_, c| c.activation }
+            excess = @concepts.size - Constants::MAX_CONCEPTS
+            sorted.first(excess).each { |name, _| @concepts.delete(name) } # rubocop:disable Style/HashEachMethods
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/priming/helpers/concept_node.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Priming
+      module Helpers
+        class ConceptNode
+          attr_reader :name, :domain, :associations
+          attr_accessor :activation, :prime_source
+
+          def initialize(name:, domain: :general)
+            @name         = name
+            @domain       = domain
+            @activation   = 0.0
+            @prime_source = nil
+            @associations = {}
+          end
+
+          def primed?
+            @activation >= Constants::PRIME_THRESHOLD
+          end
+
+          def associate(other_name, strength: Constants::DEFAULT_ASSOCIATION_STRENGTH)
+            @associations[other_name] = strength.clamp(Constants::ASSOCIATION_FLOOR, Constants::ASSOCIATION_CEILING)
+            trim_associations
+          end
+
+          def strengthen_association(other_name)
+            return unless @associations.key?(other_name)
+
+            @associations[other_name] = [
+              @associations[other_name] + Constants::ASSOCIATION_STRENGTHEN,
+              Constants::ASSOCIATION_CEILING
+            ].min
+          end
+
+          def decay_associations
+            @associations.each_key do |key|
+              @associations[key] = [
+                @associations[key] - Constants::ASSOCIATION_DECAY,
+                Constants::ASSOCIATION_FLOOR
+              ].max
+            end
+          end
+
+          def decay_activation
+            @activation = [@activation - Constants::PRIME_DECAY, 0.0].max
+            @prime_source = nil unless primed?
+          end
+
+          def prime(boost: Constants::PRIME_BOOST, source: nil)
+            @activation = [@activation + boost, 1.0].min
+            @prime_source = source
+          end
+
+          def association_strength(other_name)
+            @associations[other_name] || 0.0
+          end
+
+          def associated_names
+            @associations.keys
+          end
+
+          def to_h
+            {
+              name:         @name,
+              domain:       @domain,
+              activation:   @activation.round(4),
+              primed:       primed?,
+              prime_source: @prime_source,
+              associations: @associations.transform_values { |v| v.round(4) }
+            }
+          end
+
+          private
+
+          def trim_associations
+            return unless @associations.size > Constants::MAX_ASSOCIATIONS
+
+            sorted = @associations.sort_by { |_, v| v }
+            excess = @associations.size - Constants::MAX_ASSOCIATIONS
+            sorted.first(excess).each { |name, _| @associations.delete(name) } # rubocop:disable Style/HashEachMethods
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/priming/helpers/constants.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Priming
+      module Helpers
+        module Constants
+          # Base activation boost from a prime
+          PRIME_BOOST = 0.3
+
+          # How fast priming decays per tick
+          PRIME_DECAY = 0.08
+
+          # Spreading activation factor (each hop reduces by this ratio)
+          SPREAD_FACTOR = 0.5
+
+          # Maximum hops for spreading activation
+          MAX_SPREAD_HOPS = 3
+
+          # Minimum activation to be considered primed
+          PRIME_THRESHOLD = 0.1
+
+          # Maximum concepts in the network
+          MAX_CONCEPTS = 500
+
+          # Maximum associations per concept
+          MAX_ASSOCIATIONS = 20
+
+          # Maximum active primes at once
+          MAX_ACTIVE_PRIMES = 100
+
+          # Default association strength between new connections
+          DEFAULT_ASSOCIATION_STRENGTH = 0.5
+
+          # Strengthening factor when association is activated
+          ASSOCIATION_STRENGTHEN = 0.05
+
+          # Weakening factor for unused associations
+          ASSOCIATION_DECAY = 0.01
+
+          # Association strength floor (never fully disconnect)
+          ASSOCIATION_FLOOR = 0.05
+
+          # Association strength ceiling
+          ASSOCIATION_CEILING = 1.0
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/priming/runners/priming.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Priming
+      module Runners
+        module Priming
+          include Legion::Extensions::Helpers::Lex
+
+          def network
+            @network ||= Helpers::ActivationNetwork.new
+          end
+
+          def prime_concept(name:, boost: nil, source: nil, spread: true, **)
+            boost ||= Helpers::Constants::PRIME_BOOST
+            network.add_concept(name: name) unless network.concepts.key?(name)
+            concept = network.prime(name, boost: boost, source: source, spread: spread)
+            return { success: false, reason: :not_found } unless concept
+
+            Legion::Logging.debug "[priming] primed #{name} activation=#{concept.activation.round(4)} spread=#{spread}"
+            { success: true, concept: concept.to_h, active_primes: network.active_prime_count }
+          end
+
+          def add_concept(name:, domain: :general, **)
+            concept = network.add_concept(name: name, domain: domain)
+            { success: true, concept: concept.to_h }
+          end
+
+          def link_concepts(name_a:, name_b:, strength: nil, **)
+            strength ||= Helpers::Constants::DEFAULT_ASSOCIATION_STRENGTH
+            network.link(name_a, name_b, strength: strength)
+            Legion::Logging.debug "[priming] linked #{name_a} <-> #{name_b} strength=#{strength}"
+            { success: true, name_a: name_a, name_b: name_b, strength: strength }
+          end
+
+          def update_priming(**)
+            network.decay_all
+            primed = network.primed_concepts
+            Legion::Logging.debug "[priming] tick: concepts=#{network.concept_count} active=#{primed.size}"
+            { success: true, active_primes: primed.size, concept_count: network.concept_count }
+          end
+
+          def check_primed(name:, **)
+            activation = network.activation_for(name)
+            concept = network.concepts[name]
+            {
+              success:    true,
+              name:       name,
+              activation: activation.round(4),
+              primed:     activation >= Helpers::Constants::PRIME_THRESHOLD,
+              source:     concept&.prime_source
+            }
+          end
+
+          def primed_concepts(domain: nil, **)
+            concepts = domain ? network.primed_in_domain(domain) : network.primed_concepts
+            {
+              success:  true,
+              concepts: concepts.map { |c| { name: c.name, activation: c.activation.round(4), domain: c.domain } },
+              count:    concepts.size
+            }
+          end
+
+          def strongest_primes(count: 5, **)
+            top = network.strongest_primes(count)
+            {
+              success: true,
+              primes:  top.map { |c| { name: c.name, activation: c.activation.round(4), domain: c.domain } },
+              count:   top.size
+            }
+          end
+
+          def neighbors_for(name:, **)
+            nbrs = network.neighbors(name)
+            {
+              success:   true,
+              name:      name,
+              neighbors: nbrs.map { |c| { name: c.name, activation: c.activation.round(4), primed: c.primed? } },
+              count:     nbrs.size
+            }
+          end
+
+          def priming_stats(**)
+            { success: true, stats: network.to_h }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/priming/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Priming
+      VERSION = '0.1.0'
+    end
+  end
+end

data/lib/legion/extensions/priming.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'priming/version'
+require_relative 'priming/helpers/constants'
+require_relative 'priming/helpers/concept_node'
+require_relative 'priming/helpers/activation_network'
+require_relative 'priming/runners/priming'
+require_relative 'priming/client'
+
+module Legion
+  module Extensions
+    module Priming
+      extend Legion::Extensions::Core if defined?(Legion::Extensions::Core)
+    end
+  end
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: lex-priming
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Matthew Iverson
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: legion-gaia
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Models spreading activation in semantic networks — stimuli prime related
+  concepts, lowering their activation threshold and speeding future access.
+email:
+- matt@iverson.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/legion/extensions/priming.rb
+- lib/legion/extensions/priming/client.rb
+- lib/legion/extensions/priming/helpers/activation_network.rb
+- lib/legion/extensions/priming/helpers/concept_node.rb
+- lib/legion/extensions/priming/helpers/constants.rb
+- lib/legion/extensions/priming/runners/priming.rb
+- lib/legion/extensions/priming/version.rb
+homepage: https://github.com/LegionIO/lex-priming
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Spreading activation and priming for LegionIO
+test_files: []