lex-agentic-learning 0.1.0

data/lib/legion/extensions/agentic/learning/hebbian/helpers/assembly_network.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Hebbian
+          module Helpers
+            class AssemblyNetwork
+              include Constants
+
+              attr_reader :units, :assemblies, :activation_history
+
+              def initialize
+                @units              = {}
+                @assemblies         = {}
+                @activation_history = []
+                @assembly_counter   = 0
+              end
+
+              def add_unit(id:, domain: :general)
+                return @units[id] if @units.key?(id)
+                return nil if @units.size >= MAX_UNITS
+
+                @units[id] = Unit.new(id: id, domain: domain)
+              end
+
+              def activate_unit(id:, level: 1.0)
+                ensure_unit(id)
+                unit = @units[id]
+                unit.activate(level: level)
+                record_activation(id)
+                hebbian_update(id)
+                detect_assemblies
+                unit
+              end
+
+              def co_activate(ids:, level: 1.0)
+                ids = Array(ids)
+                ids.each do |id|
+                  ensure_unit(id)
+                  @units[id].activate(level: level)
+                  record_activation(id)
+                end
+
+                ids.combination(2).each do |a, b|
+                  ensure_connection(a, b)
+                  @units[a].strengthen(b)
+                  @units[b].strengthen(a)
+                end
+
+                detect_assemblies
+                ids.map { |id| @units[id].to_h }
+              end
+
+              def query_weight(from:, to:)
+                return 0.0 unless @units.key?(from)
+
+                @units[from].weight_to(to)
+              end
+
+              def query_assembly(id:)
+                @assemblies[id]
+              end
+
+              def assemblies_containing(unit_id:)
+                @assemblies.values.select { |a| a.includes?(unit_id) }
+              end
+
+              def pattern_complete(partial_ids:)
+                partial = Array(partial_ids)
+                candidates = partial.flat_map { |uid| assemblies_containing(unit_id: uid) }.uniq(&:id)
+                return nil if candidates.empty?
+
+                best = candidates.max_by { |a| (partial & a.member_ids).size }
+                missing = best.member_ids - partial
+                { assembly_id: best.id, known: partial & best.member_ids, predicted: missing, coherence: best.coherence }
+              end
+
+              def strongest_units(count = 10)
+                @units.values
+                      .sort_by { |u| -u.activation_count }
+                      .first(count)
+                      .map(&:to_h)
+              end
+
+              def decay_all
+                @units.each_value(&:decay_weights)
+                @assemblies.each_value(&:decay)
+                @assemblies.reject! { |_, a| a.dissolving? }
+              end
+
+              def unit_count
+                @units.size
+              end
+
+              def assembly_count
+                @assemblies.size
+              end
+
+              def to_h
+                {
+                  units:             @units.size,
+                  assemblies:        @assemblies.size,
+                  total_connections: @units.values.sum(&:connection_count),
+                  history_size:      @activation_history.size,
+                  active_units:      @units.values.count(&:active?)
+                }
+              end
+
+              private
+
+              def ensure_unit(id)
+                add_unit(id: id) unless @units.key?(id)
+              end
+
+              def ensure_connection(src, dst)
+                @units[src].connect(dst) unless @units[src].connections.key?(dst)
+                @units[dst].connect(src) unless @units[dst].connections.key?(src)
+              end
+
+              def record_activation(id)
+                @activation_history << { unit_id: id, at: Time.now.utc }
+                @activation_history.shift while @activation_history.size > MAX_ACTIVATION_HISTORY
+              end
+
+              def hebbian_update(active_id)
+                recent_window = Time.now.utc - CO_ACTIVATION_WINDOW
+                recent_ids = @activation_history
+                             .select { |h| h[:at] >= recent_window && h[:unit_id] != active_id }
+                             .map { |h| h[:unit_id] }
+                             .uniq
+
+                recent_ids.each do |other_id|
+                  next unless @units.key?(other_id) && @units[other_id].active?
+
+                  ensure_connection(active_id, other_id)
+                  @units[active_id].strengthen(other_id)
+                  @units[other_id].strengthen(active_id)
+                end
+              end
+
+              def detect_assemblies
+                strongly_connected = find_strongly_connected
+                return if strongly_connected.size < ASSEMBLY_THRESHOLD
+
+                existing = find_matching_assembly(strongly_connected)
+                existing ? reinforce_assembly(existing) : create_assembly(strongly_connected)
+              end
+
+              def find_strongly_connected
+                active_ids = @units.values.select(&:active?).map(&:id)
+                return [] if active_ids.size < ASSEMBLY_THRESHOLD
+
+                active_ids.select do |uid|
+                  peers = active_ids - [uid]
+                  peers.count { |p| @units[uid].weight_to(p) >= ASSEMBLY_MIN_WEIGHT } >= (ASSEMBLY_THRESHOLD - 1)
+                end
+              end
+
+              def find_matching_assembly(member_ids)
+                @assemblies.values.find do |a|
+                  (member_ids - a.member_ids).empty? && (a.member_ids - member_ids).empty?
+                end
+              end
+
+              def reinforce_assembly(assembly)
+                assembly.activate
+                assembly.consolidate
+              end
+
+              def create_assembly(member_ids)
+                @assembly_counter += 1
+                id = :"assembly_#{@assembly_counter}"
+                @assemblies[id] = Assembly.new(id: id, member_ids: member_ids)
+                @assemblies[id].activate
+                prune_assemblies if @assemblies.size > MAX_ASSEMBLIES
+              end
+
+              def prune_assemblies
+                weakest = @assemblies.min_by { |_, a| a.coherence }&.first
+                @assemblies.delete(weakest) if weakest
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/learning/hebbian/helpers/constants.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Hebbian
+          module Helpers
+            module Constants
+              MAX_UNITS = 500
+              MAX_ASSEMBLIES = 100
+              MAX_CONNECTIONS_PER_UNIT = 30
+              MAX_ACTIVATION_HISTORY = 200
+
+              DEFAULT_WEIGHT = 0.1
+              WEIGHT_FLOOR = 0.01
+              MAX_WEIGHT = 1.0
+              LEARNING_RATE = 0.05
+              WEIGHT_DECAY = 0.002
+
+              ACTIVATION_THRESHOLD = 0.3
+              CO_ACTIVATION_WINDOW = 5
+              ASSEMBLY_THRESHOLD = 3
+              ASSEMBLY_MIN_WEIGHT = 0.3
+
+              CONSOLIDATION_BOOST = 0.02
+              COMPETITION_FACTOR = 0.01
+
+              WEIGHT_LABELS = {
+                (0.8..)     => :bonded,
+                (0.6...0.8) => :strong,
+                (0.4...0.6) => :moderate,
+                (0.2...0.4) => :weak,
+                (..0.2)     => :nascent
+              }.freeze
+
+              ASSEMBLY_STATE_LABELS = {
+                active:     'assembly currently firing',
+                primed:     'assembly recently active',
+                dormant:    'assembly stable but inactive',
+                forming:    'assembly still consolidating',
+                dissolving: 'assembly losing coherence'
+              }.freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/learning/hebbian/helpers/unit.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Hebbian
+          module Helpers
+            class Unit
+              include Constants
+
+              attr_reader :id, :domain, :connections, :activation_count, :last_activated
+              attr_accessor :activation_level
+
+              def initialize(id:, domain: :general)
+                @id               = id
+                @domain           = domain
+                @activation_level = 0.0
+                @connections      = {}
+                @activation_count = 0
+                @last_activated   = nil
+              end
+
+              def activate(level: 1.0)
+                @activation_level = level.to_f.clamp(0.0, 1.0)
+                @activation_count += 1
+                @last_activated = Time.now.utc
+              end
+
+              def active?
+                @activation_level >= ACTIVATION_THRESHOLD
+              end
+
+              def connect(other_id, weight: DEFAULT_WEIGHT)
+                return if @connections.size >= MAX_CONNECTIONS_PER_UNIT && !@connections.key?(other_id)
+
+                @connections[other_id] = weight.to_f.clamp(WEIGHT_FLOOR, MAX_WEIGHT)
+              end
+
+              def strengthen(other_id, amount: LEARNING_RATE)
+                return unless @connections.key?(other_id)
+
+                @connections[other_id] = [@connections[other_id] + amount, MAX_WEIGHT].min
+              end
+
+              def weaken(other_id, amount: COMPETITION_FACTOR)
+                return unless @connections.key?(other_id)
+
+                @connections[other_id] = [@connections[other_id] - amount, WEIGHT_FLOOR].max
+              end
+
+              def weight_to(other_id)
+                @connections[other_id] || 0.0
+              end
+
+              def weight_label(other_id)
+                w = weight_to(other_id)
+                WEIGHT_LABELS.each { |range, lbl| return lbl if range.cover?(w) }
+                :nascent
+              end
+
+              def decay_weights
+                @connections.each do |k, w|
+                  @connections[k] = [w - WEIGHT_DECAY, WEIGHT_FLOOR].max
+                end
+                @connections.reject! { |_, w| w <= WEIGHT_FLOOR }
+              end
+
+              def connection_count
+                @connections.size
+              end
+
+              def strongest_connections(count = 5)
+                @connections.sort_by { |_, w| -w }.first(count).to_h
+              end
+
+              def to_h
+                {
+                  id:               @id,
+                  domain:           @domain,
+                  activation_level: @activation_level.round(4),
+                  active:           active?,
+                  connections:      @connections.size,
+                  activation_count: @activation_count,
+                  last_activated:   @last_activated
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/learning/hebbian/runners/hebbian_assembly.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Hebbian
+          module Runners
+            module HebbianAssembly
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def activate_unit(id:, level: 1.0, domain: :general, **)
+                Legion::Logging.debug "[hebbian] activate: id=#{id} level=#{level}"
+                network.add_unit(id: id, domain: domain)
+                unit = network.activate_unit(id: id, level: level)
+                { success: true, unit: unit.to_h, assemblies: network.assembly_count }
+              end
+
+              def co_activate_units(ids:, level: 1.0, **)
+                Legion::Logging.debug "[hebbian] co_activate: ids=#{ids}"
+                results = network.co_activate(ids: ids, level: level)
+                { success: true, units: results, assemblies: network.assembly_count }
+              end
+
+              def query_weight(from:, to:, **)
+                w = network.query_weight(from: from, to: to)
+                label = Helpers::Constants::WEIGHT_LABELS.each { |range, l| break l if range.cover?(w) }
+                label = :nascent unless label.is_a?(Symbol)
+                Legion::Logging.debug "[hebbian] weight: #{from}->#{to} = #{w}"
+                { success: true, from: from, to: to, weight: w.round(4), label: label }
+              end
+
+              def list_assemblies(**)
+                assemblies = network.assemblies.values.map(&:to_h)
+                Legion::Logging.debug "[hebbian] list_assemblies: #{assemblies.size}"
+                { success: true, assemblies: assemblies, count: assemblies.size }
+              end
+
+              def query_assembly(id:, **)
+                asm = network.query_assembly(id: id.to_sym)
+                Legion::Logging.debug "[hebbian] query_assembly: id=#{id} found=#{!asm.nil?}"
+                if asm
+                  { success: true, assembly: asm.to_h }
+                else
+                  { success: false, reason: :not_found }
+                end
+              end
+
+              def pattern_complete(partial_ids:, **)
+                Legion::Logging.debug "[hebbian] pattern_complete: partial=#{partial_ids}"
+                result = network.pattern_complete(partial_ids: partial_ids)
+                if result
+                  { success: true, completion: result }
+                else
+                  { success: false, reason: :no_matching_assembly }
+                end
+              end
+
+              def strongest_units(limit: 10, **)
+                units = network.strongest_units(limit.to_i)
+                Legion::Logging.debug "[hebbian] strongest_units: #{units.size}"
+                { success: true, units: units }
+              end
+
+              def assemblies_for(unit_id:, **)
+                asms = network.assemblies_containing(unit_id: unit_id).map(&:to_h)
+                Legion::Logging.debug "[hebbian] assemblies_for: unit=#{unit_id} count=#{asms.size}"
+                { success: true, assemblies: asms, count: asms.size }
+              end
+
+              def update_hebbian(**)
+                Legion::Logging.debug '[hebbian] decay tick'
+                network.decay_all
+                { success: true, units: network.unit_count, assemblies: network.assembly_count }
+              end
+
+              def hebbian_stats(**)
+                Legion::Logging.debug '[hebbian] stats'
+                { success: true, stats: network.to_h }
+              end
+
+              private
+
+              def network
+                @network ||= Helpers::AssemblyNetwork.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/learning/hebbian/version.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Hebbian
+          VERSION = '0.1.0'
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/learning/hebbian.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/learning/hebbian/version'
+require 'legion/extensions/agentic/learning/hebbian/helpers/constants'
+require 'legion/extensions/agentic/learning/hebbian/helpers/unit'
+require 'legion/extensions/agentic/learning/hebbian/helpers/assembly'
+require 'legion/extensions/agentic/learning/hebbian/helpers/assembly_network'
+require 'legion/extensions/agentic/learning/hebbian/runners/hebbian_assembly'
+require 'legion/extensions/agentic/learning/hebbian/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Hebbian
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/learning/learning_rate/client.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/learning/learning_rate/helpers/constants'
+require 'legion/extensions/agentic/learning/learning_rate/helpers/rate_model'
+require 'legion/extensions/agentic/learning/learning_rate/runners/learning_rate'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module LearningRate
+          class Client
+            include Runners::LearningRate
+
+            attr_reader :rate_model
+
+            def initialize(rate_model: nil, **)
+              @rate_model = rate_model || Helpers::RateModel.new
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/learning/learning_rate/helpers/constants.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module LearningRate
+          module Helpers
+            module Constants
+              DEFAULT_RATE         = 0.15
+              MIN_RATE             = 0.01
+              MAX_RATE             = 0.5
+              RATE_INCREASE        = 0.03
+              RATE_DECREASE        = 0.02
+              RATE_DECAY           = 0.005
+              ACCURACY_WINDOW      = 20
+              SURPRISE_BOOST       = 0.05
+              ERROR_BOOST          = 0.04
+              CONFIDENCE_DAMPENING = 0.03
+              MAX_DOMAINS          = 50
+              MAX_RATE_HISTORY     = 200
+
+              RATE_LABELS = {
+                (0.3..)       => :fast_learning,
+                (0.15...0.3)  => :moderate_learning,
+                (0.05...0.15) => :slow_learning,
+                (..0.05)      => :consolidated
+              }.freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/learning/learning_rate/helpers/rate_model.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module LearningRate
+          module Helpers
+            class RateModel
+              include Constants
+
+              attr_reader :rates, :accuracy_buffers, :rate_history
+
+              def initialize
+                @rates            = {}
+                @accuracy_buffers = {}
+                @rate_history     = []
+              end
+
+              def rate_for(domain)
+                @rates.fetch(domain, DEFAULT_RATE)
+              end
+
+              def record_prediction(domain:, correct:)
+                ensure_domain(domain)
+                @accuracy_buffers[domain] << (correct ? 1.0 : 0.0)
+                @accuracy_buffers[domain].shift while @accuracy_buffers[domain].size > ACCURACY_WINDOW
+                adjust_rate(domain, correct: correct)
+              end
+
+              def record_surprise(domain:, magnitude:)
+                ensure_domain(domain)
+                boost = magnitude * SURPRISE_BOOST
+                @rates[domain] = (@rates[domain] + boost).clamp(MIN_RATE, MAX_RATE)
+                record_event(domain, :surprise, @rates[domain])
+              end
+
+              def record_error(domain:, magnitude:)
+                ensure_domain(domain)
+                boost = magnitude * ERROR_BOOST
+                @rates[domain] = (@rates[domain] + boost).clamp(MIN_RATE, MAX_RATE)
+                record_event(domain, :error, @rates[domain])
+              end
+
+              def accuracy_for(domain)
+                buffer = @accuracy_buffers.fetch(domain, [])
+                return 0.0 if buffer.empty?
+
+                buffer.sum / buffer.size
+              end
+
+              def decay
+                @rates.each_key do |domain|
+                  current = @rates[domain]
+                  delta = (current - DEFAULT_RATE) * RATE_DECAY
+                  @rates[domain] = (current - delta).clamp(MIN_RATE, MAX_RATE)
+                end
+              end
+
+              def label_for(domain)
+                rate = rate_for(domain)
+                RATE_LABELS.each do |range, lbl|
+                  return lbl if range.cover?(rate)
+                end
+                :consolidated
+              end
+
+              def fastest_domains(count = 5)
+                @rates.sort_by { |_, r| -r }.first(count).to_h
+              end
+
+              def slowest_domains(count = 5)
+                @rates.sort_by { |_, r| r }.first(count).to_h
+              end
+
+              def overall_rate
+                return DEFAULT_RATE if @rates.empty?
+
+                @rates.values.sum / @rates.size
+              end
+
+              def domain_count
+                @rates.size
+              end
+
+              def to_h
+                {
+                  domain_count: @rates.size,
+                  overall_rate: overall_rate.round(4),
+                  rates:        @rates.dup,
+                  history_size: @rate_history.size
+                }
+              end
+
+              private
+
+              def ensure_domain(domain)
+                @rates[domain] ||= DEFAULT_RATE
+                @accuracy_buffers[domain] ||= []
+                trim_domains(protect: domain) if @rates.size > MAX_DOMAINS
+              end
+
+              def adjust_rate(domain, correct:)
+                @rates[domain] = if correct
+                                   (@rates[domain] - RATE_DECREASE).clamp(MIN_RATE, MAX_RATE)
+                                 else
+                                   (@rates[domain] + RATE_INCREASE).clamp(MIN_RATE, MAX_RATE)
+                                 end
+                record_event(domain, correct ? :correct : :incorrect, @rates[domain])
+              end
+
+              def record_event(domain, event_type, rate)
+                @rate_history << { domain: domain, event: event_type, rate: rate, at: Time.now.utc }
+                @rate_history.shift while @rate_history.size > MAX_RATE_HISTORY
+              end
+
+              def trim_domains(protect: nil)
+                candidates = @rates.reject { |k, _| k == protect }
+                sorted = candidates.sort_by { |_, r| (r - DEFAULT_RATE).abs }
+                excess = @rates.size - MAX_DOMAINS
+                remove_keys = sorted.first(excess).map(&:first)
+                remove_keys.each do |key|
+                  @rates.delete(key)
+                  @accuracy_buffers.delete(key)
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end