lex-semantic-priming 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4e40ba76b2f97ab9c12a1b004d3e7cdb577caaf2153fb8f6e189fa873fde8651
+  data.tar.gz: 353c181dddb932afd5c1c48cfcbc15bd01ab22a0da68b2b9368d21ea645170cd
+SHA512:
+  metadata.gz: c8a442c55e237f69d9d172830f9f492a6236263d96620cb499e7e2361c325718166aadf31e5ffd849ae5bb25bc467fc7a6e1989db195fb7b64143358aca71ef9
+  data.tar.gz: ef60c29517d3e90cae46466fa73fc98248ed4af5619d5abaf2507b664b5951b5b8bb8890462194d698568f610cbf4d31658adecf52164f60e5db7d529d6e0a73

data/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ci:
+    uses: LegionIO/.github/.github/workflows/ci.yml@main
+
+  release:
+    needs: ci
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    uses: LegionIO/.github/.github/workflows/release.yml@main
+    secrets:
+      rubygems-api-key: ${{ secrets.RUBYGEMS_API_KEY }}

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.gem
+Gemfile.lock
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color

data/.rubocop.yml

@@ -0,0 +1,34 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.4
+
+Style/Documentation:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/AbcSize:
+  Max: 25
+
+Metrics/ParameterLists:
+  Max: 8
+  MaxOptionalParameters: 8
+
+Layout/HashAlignment:
+  EnforcedColonStyle: table
+  EnforcedHashRocketStyle: table
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+
+Style/OneClassPerFile:
+  Exclude:
+    - 'spec/spec_helper.rb'

data/CLAUDE.md

@@ -0,0 +1,138 @@
+# lex-semantic-priming
+
+**Level 3 Leaf Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-agentic/CLAUDE.md`
+- **Gem**: `lex-semantic-priming`
+- **Version**: `0.1.0`
+- **Namespace**: `Legion::Extensions::SemanticPriming`
+
+## Purpose
+
+Implements spreading activation across a weighted semantic network. Nodes represent concepts; connections carry directional weights that grow stronger each time they are traversed (Hebbian reinforcement). When a seed concept is primed, activation spreads outward through connected nodes with both a per-hop decay factor and a weight-attenuated spread amount. Distinct from `lex-semantic-memory` (which stores named concept definitions with typed relations) — this stores activation states and connection weights for dynamic priming behavior.
+
+## Gem Info
+
+- **Gem name**: `lex-semantic-priming`
+- **License**: MIT
+- **Ruby**: >= 3.4
+- **No runtime dependencies** beyond the Legion framework
+
+## File Structure
+
+```
+lib/legion/extensions/semantic_priming/
+  version.rb                         # VERSION = '0.1.0'
+  helpers/
+    constants.rb                     # limits, activation params, weight params, node types
+    semantic_node.rb                 # SemanticNode class — concept node with activation state
+    connection.rb                    # Connection class — weighted directional edge, Hebbian traversal
+    priming_network.rb               # PrimingNetwork class — full network with BFS spreading activation
+  runners/
+    semantic_priming.rb              # Runners::SemanticPriming module — all public runner methods
+  client.rb                          # Client class including Runners::SemanticPriming
+```
+
+## Key Constants
+
+| Constant | Value | Purpose |
+|---|---|---|
+| `MAX_NODES` | 500 | Maximum nodes in the network |
+| `MAX_CONNECTIONS` | 2000 | Maximum edges |
+| `ACTIVATION_DECAY` | 0.05 | Per-tick activation decrease for all nodes |
+| `SPREADING_FACTOR` | 0.6 | Base fraction of activation that spreads per hop |
+| `PRIMING_BOOST` | 0.3 | Direct boost applied to a node when primed |
+| `ACTIVATION_THRESHOLD` | 0.1 | Minimum activation to be considered active |
+| `DEFAULT_WEIGHT` | 0.5 | Starting connection weight for new edges |
+| `WEIGHT_GROWTH_RATE` | 0.02 | Weight increase on each traversal (Hebbian) |
+| `WEIGHT_DECAY_RATE` | 0.01 | Weight decrease per decay cycle |
+| `MIN_WEIGHT` | 0.05 | Floor for connection weights; pruned at or below |
+| `MAX_SPREAD_DEPTH` | 3 | Maximum BFS hops during spreading activation |
+| `DEPTH_DECAY_FACTOR` | 0.5 | Activation multiplier per depth level |
+| `NODE_TYPES` | 7 symbols | `:concept`, `:entity`, `:action`, `:property`, `:relation`, `:event`, `:context` |
+
+## Helpers
+
+### `Helpers::SemanticNode`
+
+Concept node with activation state and metadata.
+
+- `initialize(id:, label:, node_type: :concept, domain: :general)` — initial activation = 0.0
+- `prime!(amount = PRIMING_BOOST)` — boosts activation by amount, clamps to 1.0
+- `decay!(rate = ACTIVATION_DECAY)` — decrements activation; floors at 0.0
+- `access!` — records last_accessed timestamp
+- `reset!` — sets activation back to 0.0
+- `primed?` — activation >= 0.4
+- `active?` — activation > ACTIVATION_THRESHOLD
+- `activation_label` — `:dormant`, `:trace`, `:weak`, `:moderate`, `:strong`, `:peak` based on activation value
+
+### `Helpers::Connection`
+
+Weighted directional edge between two nodes.
+
+- `initialize(source_id:, target_id:, weight: DEFAULT_WEIGHT)` — assigned UUID
+- `strengthen!(amount = WEIGHT_GROWTH_RATE)` — increases weight, clamps to 1.0
+- `weaken!(amount = WEIGHT_DECAY_RATE)` — decreases weight; removes when at or below MIN_WEIGHT
+- `traverse!(source_activation)` — calls `strengthen!` (Hebbian) and returns `spreading_amount`
+- `spreading_amount(source_activation)` — `source_activation * weight * SPREADING_FACTOR`
+- `weight_label` — `:negligible`, `:weak`, `:moderate`, `:strong`, `:dominant`
+
+### `Helpers::PrimingNetwork`
+
+Full network with BFS spreading activation.
+
+- `initialize` — empty nodes hash, connections hash (keyed by `source_id:target_id`)
+- `add_node(label:, node_type: :concept, domain: :general)` — returns nil if at MAX_NODES
+- `remove_node(node_id)` — removes node and all connections to/from it
+- `connect(source_id:, target_id:, weight: DEFAULT_WEIGHT)` — creates or returns existing connection; returns nil if at MAX_CONNECTIONS
+- `prime_node(node_id, amount: PRIMING_BOOST)` — calls `node.prime!`
+- `spread_activation(node_id, depth: MAX_SPREAD_DEPTH, visited: {})` — recursive BFS; each level multiplied by `DEPTH_DECAY_FACTOR`; each edge traversal calls `connection.traverse!` for Hebbian strengthening
+- `prime_and_spread(node_id, amount: PRIMING_BOOST, depth: MAX_SPREAD_DEPTH)` — primes seed, then spreads
+- `decay_all!` — decays all node activations; weakens all connection weights (prunes at MIN_WEIGHT)
+- `reset_all!` — resets all node activations to 0.0
+- `find_node_by_label(label)` — substring or exact match search
+- `neighbors(node_id)` — returns all outgoing connections
+- `connection_between(source_id, target_id)` — direct lookup
+- `primed_nodes` — nodes with `primed? == true`
+- `active_nodes` — nodes with `active? == true`
+- `most_primed(limit: 5)` — sorted by activation descending
+- `strongest_connections(limit: 10)` — sorted by weight descending
+- `average_activation` — mean activation across all nodes
+- `network_density` — `connections.size.to_f / [nodes.size * (nodes.size - 1), 1].max`
+- `priming_report` — summary hash including active/primed counts, average activation, density, top nodes
+
+## Runners
+
+All runners are in `Runners::SemanticPriming`. Callers may pass an optional `engine:` parameter to operate on a non-default network instance.
+
+| Runner | Parameters | Returns |
+|---|---|---|
+| `add_node` | `label:, node_type: :concept, domain: :general` | `{ success:, node_id:, label:, node_type: }` |
+| `remove_node` | `node_id:` | `{ success: }` |
+| `connect_nodes` | `source_id:, target_id:, weight: DEFAULT_WEIGHT` | `{ success:, connection_id:, source_id:, target_id:, weight: }` |
+| `prime` | `node_id:, amount: PRIMING_BOOST` | `{ success:, node_id:, activation: }` |
+| `prime_and_spread` | `node_id:, amount: PRIMING_BOOST, depth: MAX_SPREAD_DEPTH` | `{ success:, node_id:, activation:, spread_count: }` |
+| `spread_activation` | `node_id:, depth: MAX_SPREAD_DEPTH` | `{ success:, node_id:, spread_count: }` |
+| `decay` | (none) | `{ success:, active_nodes:, pruned_connections: }` |
+| `reset` | (none) | `{ success: }` |
+| `find_node` | `label:` | `{ success:, found:, node: }` |
+| `neighbors` | `node_id:` | `{ success:, node_id:, neighbors:, count: }` |
+| `primed_nodes` | (none) | `{ success:, nodes:, count: }` |
+| `most_primed` | `limit: 5` | `{ success:, nodes:, count: }` |
+| `priming_report` | (none) | Full `PrimingNetwork#priming_report` hash |
+| `status` | (none) | Node count, connection count, average activation, density |
+
+## Integration Points
+
+- **lex-semantic-memory**: semantic-memory stores named concept definitions with relational structure; semantic-priming stores transient activation state and connection weights. They are complementary — semantic-memory provides the schema; semantic-priming provides the dynamic activation surface
+- **lex-dream**: association walking in the dream cycle can use `prime_and_spread` to find conceptually adjacent concepts for contradiction resolution and agenda synthesis
+- **lex-tick / lex-cortex**: `prime_and_spread` or `decay` can be wired as a tick phase handler for ongoing network maintenance
+- **lex-memory**: when a memory trace is retrieved, its associated concept nodes can be primed to model recency effects on conceptual accessibility
+
+## Development Notes
+
+- Spreading activation is recursive, not iterative; depth is tracked via `visited` hash to prevent re-activation of already-visited nodes in the same spread call
+- Each `traverse!` call on a connection triggers Hebbian strengthening — frequent traversals produce stronger connections over time, modeling use-dependent accessibility
+- `DEPTH_DECAY_FACTOR = 0.5` means activation at depth 2 is 25% of the seed's activation; at depth 3, 12.5%
+- `spreading_amount` = `source_activation * weight * SPREADING_FACTOR`; this triple-product means low-weight connections transmit very little even with high source activation
+- `decay_all!` weaken-and-prune connections in the same pass; connections at or below `MIN_WEIGHT` are deleted
+- The optional `engine:` parameter on all runners supports multiple independent networks in a single process

data/Gemfile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :development, :test do
+  gem 'rspec', '~> 3.13'
+  gem 'rubocop', '~> 1.75'
+  gem 'rubocop-rspec'
+end
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/README.md

@@ -0,0 +1,62 @@
+# lex-semantic-priming
+
+Spreading activation network for LegionIO cognitive agents. Nodes represent concepts; connections carry weights that strengthen each time they are traversed (Hebbian reinforcement).
+
+## What It Does
+
+`lex-semantic-priming` maintains a weighted semantic network where priming one concept causes activation to spread to related concepts with depth-attenuated strength. The network learns from use: every edge traversal during spreading activation calls `strengthen!` on that connection, gradually building stronger pathways for frequently co-activated concepts.
+
+- **Nodes**: typed concept nodes (`:concept`, `:entity`, `:action`, `:property`, `:relation`, `:event`, `:context`)
+- **Connections**: directional weighted edges; weights grow on traversal (Hebbian), decay over time
+- **Spreading activation**: BFS from a seed node across outgoing connections; activation decays by `DEPTH_DECAY_FACTOR` (0.5) per hop and by `weight * SPREADING_FACTOR` (0.6) per edge
+- **Decay**: all node activations and connection weights decay each tick; connections pruned at MIN_WEIGHT (0.05)
+- **Primed nodes**: activation >= 0.4; active nodes: activation > 0.1
+
+## Usage
+
+```ruby
+require 'legion/extensions/semantic_priming'
+
+client = Legion::Extensions::SemanticPriming::Client.new
+
+# Add concept nodes
+ruby_id   = client.add_node(label: 'ruby', node_type: :concept, domain: :programming)[:node_id]
+oop_id    = client.add_node(label: 'object_oriented', node_type: :concept, domain: :programming)[:node_id]
+class_id  = client.add_node(label: 'class', node_type: :concept, domain: :programming)[:node_id]
+
+# Connect them
+client.connect_nodes(source_id: ruby_id, target_id: oop_id)
+client.connect_nodes(source_id: oop_id, target_id: class_id)
+
+# Prime a seed and spread activation
+result = client.prime_and_spread(node_id: ruby_id)
+# => { success: true, node_id: ..., activation: 0.3, spread_count: 2 }
+
+# See which nodes are primed (activation >= 0.4)
+client.primed_nodes
+# => { success: true, nodes: [...], count: 1 }
+
+# Most activated nodes
+client.most_primed(limit: 5)
+# => { success: true, nodes: [{ label: 'ruby', activation: 0.3, ... }, ...], count: ... }
+
+# Per-tick decay (call each cognitive cycle)
+client.decay
+# => { success: true, active_nodes: 2, pruned_connections: 0 }
+
+# Network summary
+client.priming_report
+# => { node_count:, connection_count:, active_count:, primed_count:, average_activation:, density:, ... }
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-semantic-priming.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/semantic_priming/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-semantic-priming'
+  spec.version       = Legion::Extensions::SemanticPriming::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'Semantic priming and spreading activation network for LegionIO'
+  spec.description   = 'Models spreading activation in semantic networks - priming one concept activates related ' \
+                       'concepts with distance-based decay for rapid associative retrieval.'
+  spec.homepage      = 'https://github.com/LegionIO/lex-semantic-priming'
+  spec.license       = 'MIT'
+
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']      = spec.homepage
+  spec.metadata['source_code_uri']   = 'https://github.com/LegionIO/lex-semantic-priming'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-semantic-priming/blob/master/README.md'
+  spec.metadata['changelog_uri']     = 'https://github.com/LegionIO/lex-semantic-priming/blob/master/CHANGELOG.md'
+  spec.metadata['bug_tracker_uri']   = 'https://github.com/LegionIO/lex-semantic-priming/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module SemanticPriming
+      class Client
+        include Runners::SemanticPriming
+
+        def initialize(engine: nil)
+          @default_engine = engine || Helpers::PrimingNetwork.new
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/semantic_priming/helpers/connection.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module SemanticPriming
+      module Helpers
+        class Connection
+          include Constants
+
+          attr_reader :id, :source_id, :target_id, :weight, :traversal_count, :created_at
+
+          def initialize(source_id:, target_id:, weight: DEFAULT_WEIGHT)
+            @id              = SecureRandom.uuid
+            @source_id       = source_id
+            @target_id       = target_id
+            @weight          = weight.to_f.clamp(MIN_WEIGHT, 1.0).round(10)
+            @traversal_count = 0
+            @created_at      = Time.now.utc
+          end
+
+          def strengthen!(amount: WEIGHT_GROWTH_RATE)
+            @weight = (@weight + amount).clamp(MIN_WEIGHT, 1.0).round(10)
+            self
+          end
+
+          def weaken!(amount: WEIGHT_DECAY_RATE)
+            @weight = (@weight - amount).clamp(MIN_WEIGHT, 1.0).round(10)
+            self
+          end
+
+          def traverse!
+            @traversal_count += 1
+            strengthen!(amount: WEIGHT_GROWTH_RATE)
+            self
+          end
+
+          def strong?
+            @weight >= 0.7
+          end
+
+          def weak?
+            @weight <= 0.2
+          end
+
+          def spreading_amount(source_activation)
+            (source_activation * @weight * SPREADING_FACTOR).round(10)
+          end
+
+          def weight_label
+            match = WEIGHT_LABELS.find { |range, _| range.cover?(@weight) }
+            match ? match.last : :very_weak
+          end
+
+          def to_h
+            {
+              id:              @id,
+              source_id:       @source_id,
+              target_id:       @target_id,
+              weight:          @weight,
+              weight_label:    weight_label,
+              strong:          strong?,
+              weak:            weak?,
+              traversal_count: @traversal_count,
+              created_at:      @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module SemanticPriming
+      module Helpers
+        module Constants
+          # Network limits
+          MAX_NODES = 500
+          MAX_CONNECTIONS = 2000
+
+          # Activation dynamics
+          DEFAULT_ACTIVATION = 0.0
+          RESTING_ACTIVATION = 0.0
+          MAX_ACTIVATION = 1.0
+          ACTIVATION_DECAY = 0.05
+          SPREADING_FACTOR = 0.6
+          PRIMING_BOOST = 0.3
+          ACTIVATION_THRESHOLD = 0.1
+
+          # Connection properties
+          DEFAULT_WEIGHT = 0.5
+          WEIGHT_GROWTH_RATE = 0.02
+          WEIGHT_DECAY_RATE = 0.01
+          MIN_WEIGHT = 0.05
+
+          # Spreading activation
+          MAX_SPREAD_DEPTH = 3
+          DEPTH_DECAY_FACTOR = 0.5
+
+          # Node types
+          NODE_TYPES = %i[concept category feature relation action emotion context].freeze
+
+          # Activation labels
+          ACTIVATION_LABELS = {
+            (0.8..)     => :highly_primed,
+            (0.6...0.8) => :primed,
+            (0.4...0.6) => :partially_primed,
+            (0.2...0.4) => :weakly_primed,
+            (..0.2)     => :unprimed
+          }.freeze
+
+          # Connection strength labels
+          WEIGHT_LABELS = {
+            (0.8..)     => :very_strong,
+            (0.6...0.8) => :strong,
+            (0.4...0.6) => :moderate,
+            (0.2...0.4) => :weak,
+            (..0.2)     => :very_weak
+          }.freeze
+
+          # Priming effect labels
+          PRIMING_LABELS = {
+            (0.8..)     => :massive,
+            (0.6...0.8) => :strong,
+            (0.4...0.6) => :moderate,
+            (0.2...0.4) => :mild,
+            (..0.2)     => :negligible
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/semantic_priming/helpers/priming_network.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module SemanticPriming
+      module Helpers
+        class PrimingNetwork
+          include Constants
+
+          def initialize
+            @nodes       = {}
+            @connections = {}
+            @adjacency   = Hash.new { |h, k| h[k] = [] }
+          end
+
+          def add_node(label:, node_type: :concept)
+            prune_nodes_if_needed
+            node = SemanticNode.new(label: label, node_type: node_type)
+            @nodes[node.id] = node
+            node
+          end
+
+          def remove_node(node_id:)
+            node = @nodes.delete(node_id)
+            return nil unless node
+
+            @adjacency.delete(node_id)
+            @adjacency.each_value { |list| list.reject! { |cid| connection_involves?(cid, node_id) } }
+            @connections.reject! { |_, c| c.source_id == node_id || c.target_id == node_id }
+            node
+          end
+
+          def connect(source_id:, target_id:, weight: DEFAULT_WEIGHT)
+            return nil unless @nodes[source_id] && @nodes[target_id]
+            return nil if source_id == target_id
+
+            prune_connections_if_needed
+            conn = Connection.new(source_id: source_id, target_id: target_id, weight: weight)
+            @connections[conn.id] = conn
+            @adjacency[source_id] << conn.id
+            @adjacency[target_id] << conn.id
+            conn
+          end
+
+          def prime_node(node_id:, amount: PRIMING_BOOST)
+            node = @nodes[node_id]
+            return nil unless node
+
+            node.prime!(amount: amount)
+            node
+          end
+
+          def spread_activation(source_id:, depth: MAX_SPREAD_DEPTH)
+            source = @nodes[source_id]
+            return nil unless source
+
+            activated = {}
+            spread_recursive(source_id, source.activation, depth, 0, activated)
+            activated.map { |nid, amount| { node_id: nid, label: @nodes[nid]&.label, activation_added: amount } }
+          end
+
+          def prime_and_spread(node_id:, amount: PRIMING_BOOST, depth: MAX_SPREAD_DEPTH)
+            node = prime_node(node_id: node_id, amount: amount)
+            return nil unless node
+
+            node.access!
+            spread = spread_activation(source_id: node_id, depth: depth)
+            { primed_node: node.to_h, spread: spread }
+          end
+
+          def decay_all!
+            @nodes.each_value(&:decay!)
+            @connections.each_value { |c| c.weaken!(amount: WEIGHT_DECAY_RATE) }
+            prune_weak_connections
+            { nodes_decayed: @nodes.size, connections_remaining: @connections.size }
+          end
+
+          def reset_all! = @nodes.each_value(&:reset!) && { nodes_reset: @nodes.size }
+          def find_node_by_label(label:) = @nodes.values.find { |n| n.label == label.to_s }
+
+          def neighbors(node_id:)
+            conn_ids = @adjacency[node_id] || []
+            conn_ids.filter_map do |cid|
+              conn = @connections[cid]
+              next unless conn
+
+              other_id = conn.source_id == node_id ? conn.target_id : conn.source_id
+              @nodes[other_id]
+            end
+          end
+
+          def connection_between(source_id:, target_id:)
+            @connections.values.find do |c|
+              (c.source_id == source_id && c.target_id == target_id) ||
+                (c.source_id == target_id && c.target_id == source_id)
+            end
+          end
+
+          def primed_nodes = @nodes.values.select(&:primed?)
+          def active_nodes = @nodes.values.select(&:active?)
+          def most_primed(limit: 5) = @nodes.values.sort_by { |n| -n.activation }.first(limit)
+          def strongest_connections(limit: 5) = @connections.values.sort_by { |c| -c.weight }.first(limit)
+
+          def average_activation
+            return DEFAULT_ACTIVATION if @nodes.empty?
+
+            vals = @nodes.values.map(&:activation)
+            (vals.sum / vals.size).round(10)
+          end
+
+          def average_connection_weight
+            return DEFAULT_WEIGHT if @connections.empty?
+
+            vals = @connections.values.map(&:weight)
+            (vals.sum / vals.size).round(10)
+          end
+
+          def network_density
+            return 0.0 if @nodes.size < 2
+
+            (@connections.size.to_f / (@nodes.size * (@nodes.size - 1) / 2)).round(10)
+          end
+
+          def priming_report
+            to_h.merge(
+              average_weight:        average_connection_weight,
+              most_primed:           most_primed(limit: 3).map(&:to_h),
+              strongest_connections: strongest_connections(limit: 3).map(&:to_h)
+            )
+          end
+
+          def to_h
+            {
+              total_nodes:        @nodes.size,
+              total_connections:  @connections.size,
+              primed_count:       primed_nodes.size,
+              active_count:       active_nodes.size,
+              average_activation: average_activation,
+              network_density:    network_density
+            }
+          end
+
+          private
+
+          def spread_recursive(node_id, activation, max_depth, current_depth, activated)
+            return if current_depth >= max_depth || activation < ACTIVATION_THRESHOLD
+
+            each_neighbor(node_id) do |conn, other_id, target_node|
+              next if activated.key?(other_id)
+
+              amount = (conn.spreading_amount(activation) * (DEPTH_DECAY_FACTOR**current_depth)).round(10)
+              next if amount < ACTIVATION_THRESHOLD
+
+              conn.traverse!
+              target_node.prime!(amount: amount)
+              activated[other_id] = amount
+              spread_recursive(other_id, amount, max_depth, current_depth + 1, activated)
+            end
+          end
+
+          def each_neighbor(node_id)
+            (@adjacency[node_id] || []).each do |cid|
+              conn = @connections[cid]
+              next unless conn
+
+              other_id = conn.source_id == node_id ? conn.target_id : conn.source_id
+              target_node = @nodes[other_id]
+              yield conn, other_id, target_node if target_node
+            end
+          end
+
+          def connection_involves?(cid, nid)
+            (c = @connections[cid]) && (c.source_id == nid || c.target_id == nid)
+          end
+
+          def prune_nodes_if_needed
+            return if @nodes.size < MAX_NODES
+
+            remove_node(node_id: @nodes.values.min_by(&:activation).id)
+          end
+
+          def prune_connections_if_needed
+            return if @connections.size < MAX_CONNECTIONS
+
+            remove_connection(@connections.values.min_by(&:weight).id)
+          end
+
+          def prune_weak_connections
+            @connections.each { |id, c| remove_connection(id) if c.weight <= MIN_WEIGHT }
+          end
+
+          def remove_connection(conn_id)
+            return unless (conn = @connections.delete(conn_id))
+
+            @adjacency[conn.source_id]&.delete(conn_id)
+            @adjacency[conn.target_id]&.delete(conn_id)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/semantic_priming/helpers/semantic_node.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module SemanticPriming
+      module Helpers
+        class SemanticNode
+          include Constants
+
+          attr_reader :id, :label, :node_type, :activation, :prime_count,
+                      :access_count, :created_at
+
+          def initialize(label:, node_type: :concept, activation: DEFAULT_ACTIVATION)
+            @id           = SecureRandom.uuid
+            @label        = label.to_s
+            @node_type    = node_type.to_sym
+            @activation   = activation.to_f.clamp(0.0, MAX_ACTIVATION).round(10)
+            @prime_count  = 0
+            @access_count = 0
+            @created_at   = Time.now.utc
+          end
+
+          def prime!(amount: PRIMING_BOOST)
+            @activation = (@activation + amount).clamp(0.0, MAX_ACTIVATION).round(10)
+            @prime_count += 1
+            self
+          end
+
+          def decay!
+            @activation = (@activation - ACTIVATION_DECAY).clamp(0.0, MAX_ACTIVATION).round(10)
+            self
+          end
+
+          def access!
+            @access_count += 1
+            self
+          end
+
+          def reset!
+            @activation = RESTING_ACTIVATION
+            self
+          end
+
+          def primed?
+            @activation >= 0.4
+          end
+
+          def active?
+            @activation > ACTIVATION_THRESHOLD
+          end
+
+          def activation_label
+            match = ACTIVATION_LABELS.find { |range, _| range.cover?(@activation) }
+            match ? match.last : :unprimed
+          end
+
+          def to_h
+            {
+              id:               @id,
+              label:            @label,
+              node_type:        @node_type,
+              activation:       @activation,
+              activation_label: activation_label,
+              primed:           primed?,
+              active:           active?,
+              prime_count:      @prime_count,
+              access_count:     @access_count,
+              created_at:       @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module SemanticPriming
+      module Runners
+        module SemanticPriming
+          include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+          def add_node(label:, node_type: :concept, engine: nil, **)
+            eng = engine || default_engine
+            node = eng.add_node(label: label, node_type: node_type)
+            { success: true, node: node.to_h }
+          end
+
+          def remove_node(node_id:, engine: nil, **)
+            eng = engine || default_engine
+            node = eng.remove_node(node_id: node_id)
+            return { success: false, error: 'node not found' } unless node
+
+            { success: true, removed: node.to_h }
+          end
+
+          def connect_nodes(source_id:, target_id:, weight: nil, engine: nil, **)
+            eng = engine || default_engine
+            w = weight || Helpers::Constants::DEFAULT_WEIGHT
+            conn = eng.connect(source_id: source_id, target_id: target_id, weight: w)
+            return { success: false, error: 'invalid nodes or self-connection' } unless conn
+
+            { success: true, connection: conn.to_h }
+          end
+
+          def prime(node_id:, amount: nil, engine: nil, **)
+            eng = engine || default_engine
+            amt = amount || Helpers::Constants::PRIMING_BOOST
+            node = eng.prime_node(node_id: node_id, amount: amt)
+            return { success: false, error: 'node not found' } unless node
+
+            { success: true, node: node.to_h }
+          end
+
+          def prime_and_spread(node_id:, amount: nil, depth: nil, engine: nil, **)
+            eng = engine || default_engine
+            amt = amount || Helpers::Constants::PRIMING_BOOST
+            d = depth || Helpers::Constants::MAX_SPREAD_DEPTH
+            result = eng.prime_and_spread(node_id: node_id, amount: amt, depth: d)
+            return { success: false, error: 'node not found' } unless result
+
+            { success: true, **result }
+          end
+
+          def spread_activation(source_id:, depth: nil, engine: nil, **)
+            eng = engine || default_engine
+            d = depth || Helpers::Constants::MAX_SPREAD_DEPTH
+            result = eng.spread_activation(source_id: source_id, depth: d)
+            return { success: false, error: 'node not found' } unless result
+
+            { success: true, activated: result }
+          end
+
+          def decay(engine: nil, **)
+            eng = engine || default_engine
+            result = eng.decay_all!
+            { success: true, **result }
+          end
+
+          def reset(engine: nil, **)
+            eng = engine || default_engine
+            result = eng.reset_all!
+            { success: true, **result }
+          end
+
+          def find_node(label:, engine: nil, **)
+            eng = engine || default_engine
+            node = eng.find_node_by_label(label: label)
+            return { success: false, error: 'node not found' } unless node
+
+            { success: true, node: node.to_h }
+          end
+
+          def neighbors(node_id:, engine: nil, **)
+            eng = engine || default_engine
+            nodes = eng.neighbors(node_id: node_id)
+            { success: true, neighbors: nodes.map(&:to_h) }
+          end
+
+          def primed_nodes(engine: nil, **)
+            eng = engine || default_engine
+            { success: true, nodes: eng.primed_nodes.map(&:to_h) }
+          end
+
+          def most_primed(limit: 5, engine: nil, **)
+            eng = engine || default_engine
+            { success: true, nodes: eng.most_primed(limit: limit).map(&:to_h) }
+          end
+
+          def priming_report(engine: nil, **)
+            eng = engine || default_engine
+            { success: true, report: eng.priming_report }
+          end
+
+          def status(engine: nil, **)
+            eng = engine || default_engine
+            { success: true, **eng.to_h }
+          end
+
+          private
+
+          def default_engine
+            @default_engine ||= Helpers::PrimingNetwork.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/semantic_priming.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative 'semantic_priming/version'
+require_relative 'semantic_priming/helpers/constants'
+require_relative 'semantic_priming/helpers/semantic_node'
+require_relative 'semantic_priming/helpers/connection'
+require_relative 'semantic_priming/helpers/priming_network'
+require_relative 'semantic_priming/runners/semantic_priming'
+require_relative 'semantic_priming/client'
+
+module Legion
+  module Extensions
+    module SemanticPriming
+      extend Legion::Extensions::Core if defined?(Legion::Extensions::Core)
+    end
+  end
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: lex-semantic-priming
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Esity
+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 - priming one concept
+  activates related concepts with distance-based decay for rapid associative retrieval.
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- CLAUDE.md
+- Gemfile
+- README.md
+- lex-semantic-priming.gemspec
+- lib/legion/extensions/semantic_priming.rb
+- lib/legion/extensions/semantic_priming/client.rb
+- lib/legion/extensions/semantic_priming/helpers/connection.rb
+- lib/legion/extensions/semantic_priming/helpers/constants.rb
+- lib/legion/extensions/semantic_priming/helpers/priming_network.rb
+- lib/legion/extensions/semantic_priming/helpers/semantic_node.rb
+- lib/legion/extensions/semantic_priming/runners/semantic_priming.rb
+- lib/legion/extensions/semantic_priming/version.rb
+homepage: https://github.com/LegionIO/lex-semantic-priming
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-semantic-priming
+  source_code_uri: https://github.com/LegionIO/lex-semantic-priming
+  documentation_uri: https://github.com/LegionIO/lex-semantic-priming/blob/master/README.md
+  changelog_uri: https://github.com/LegionIO/lex-semantic-priming/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/LegionIO/lex-semantic-priming/issues
+  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: Semantic priming and spreading activation network for LegionIO
+test_files: []