lex-agentic-learning 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 14ead87d8b9aba4266580c17d9f8ece03e76d64f15375e8ef3b89f078aa1eb20
+  data.tar.gz: b9ca7ce1d976b330e1f66ed9bf8dc00cd2d4cedc7bd1adf45f161b356a5c87f9
+SHA512:
+  metadata.gz: ff8f094be6c42376441676ae52450b091b42cfbd44ea39ff15631ce0a17cdc9b8e9a49e62b538c06813bf0712f6da9f902fd38305491384069dd196fee7220f5
+  data.tar.gz: 1e1d0819d02c30a65b1c59de7c4822592eb6047b64fda08ccbb60782c836a3a35a444fd4afbccd430ac86346ceb1cd9be47f21ba4f9cfea1aaedbc203eabad02

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-18
+
+### Added
+- Initial release as domain consolidation gem
+- Consolidated source extensions into unified domain gem under `Legion::Extensions::Agentic::<Domain>`
+- All sub-modules loaded from single entry point
+- Full spec suite with zero failures
+- RuboCop compliance across all files

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

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,13 @@
+# lex-agentic-learning
+
+LEX agentic learning domain: adaptation, memory consolidation, skill acquisition
+
+## Sub-modules
+
+*(populated as extensions are consolidated)*
+
+## Installation
+
+```ruby
+gem 'lex-agentic-learning'
+```

data/lex-agentic-learning.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/agentic/learning/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-agentic-learning'
+  spec.version       = Legion::Extensions::Agentic::Learning::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Agentic Learning'
+  spec.description   = 'LEX agentic learning domain: adaptation, memory consolidation, skill acquisition'
+  spec.homepage      = 'https://github.com/LegionIO/lex-agentic-learning'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']      = spec.homepage
+  spec.metadata['source_code_uri']   = spec.homepage
+  spec.metadata['changelog_uri']     = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir.glob('{lib,spec}/**/*.rb') + %w[lex-agentic-learning.gemspec Gemfile LICENSE README.md CHANGELOG.md]
+  end
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'rspec', '~> 3.13'
+  spec.add_development_dependency 'rubocop', '~> 1.60'
+  spec.add_development_dependency 'rubocop-rspec', '~> 2.26'
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/learning/anchoring/helpers/constants'
+require 'legion/extensions/agentic/learning/anchoring/helpers/anchor'
+require 'legion/extensions/agentic/learning/anchoring/helpers/anchor_store'
+require 'legion/extensions/agentic/learning/anchoring/runners/anchoring'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Anchoring
+          class Client
+            include Runners::Anchoring
+
+            attr_reader :anchor_store
+
+            def initialize(anchor_store: nil, **)
+              @anchor_store = anchor_store || Helpers::AnchorStore.new
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/learning/anchoring/helpers/anchor.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Anchoring
+          module Helpers
+            class Anchor
+              include Constants
+
+              attr_reader :id, :value, :domain, :strength, :created_at, :last_accessed
+
+              def initialize(value:, domain: :general)
+                @id            = SecureRandom.uuid
+                @value         = value.to_f
+                @domain        = domain.to_sym
+                @strength      = 1.0
+                @created_at    = Time.now.utc
+                @last_accessed = Time.now.utc
+              end
+
+              def decay
+                @strength = [(@strength - Constants::ANCHOR_DECAY), 0.0].max
+              end
+
+              def reinforce(observed_value:)
+                @last_accessed = Time.now.utc
+                alpha          = Constants::ADJUSTMENT_RATE
+                @value         = ((1.0 - alpha) * @value) + (alpha * observed_value.to_f)
+                @strength      = [@strength + 0.1, 1.0].min
+              end
+
+              def pull(estimate:)
+                weight = @strength * Constants::DEFAULT_ANCHOR_WEIGHT
+                (weight * @value) + ((1.0 - weight) * estimate.to_f)
+              end
+
+              def label
+                Constants::ANCHOR_LABELS.each do |range, lbl|
+                  return lbl if range.cover?(@strength)
+                end
+                :fading
+              end
+
+              def to_h
+                {
+                  id:            @id,
+                  value:         @value,
+                  domain:        @domain,
+                  strength:      @strength,
+                  label:         label,
+                  created_at:    @created_at,
+                  last_accessed: @last_accessed
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/learning/anchoring/helpers/anchor_store.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Anchoring
+          module Helpers
+            class AnchorStore
+              include Constants
+
+              def initialize
+                @anchors    = {} # domain (Symbol) -> Array<Anchor>
+                @references = {} # domain (Symbol) -> Float (explicit reference point)
+              end
+
+              def add(value:, domain: :general)
+                domain = domain.to_sym
+                @anchors[domain] ||= []
+
+                anchor = Anchor.new(value: value, domain: domain)
+                @anchors[domain] << anchor
+
+                if @anchors[domain].size > Constants::MAX_ANCHORS_PER_DOMAIN
+                  @anchors[domain] = @anchors[domain].sort_by(&:strength).last(Constants::MAX_ANCHORS_PER_DOMAIN)
+                end
+
+                prune_domains
+                anchor
+              end
+
+              def strongest(domain: :general)
+                domain   = domain.to_sym
+                anchors  = @anchors[domain]
+                return nil if anchors.nil? || anchors.empty?
+
+                anchors.max_by(&:strength)
+              end
+
+              def find(id:)
+                @anchors.each_value do |arr|
+                  arr.each { |a| return a if a.id == id }
+                end
+                nil
+              end
+
+              def evaluate(estimate:, domain: :general)
+                domain  = domain.to_sym
+                anchor  = strongest(domain: domain)
+                return { anchored_estimate: estimate.to_f, pull_strength: 0.0, anchor_value: nil, correction: 0.0 } if anchor.nil?
+
+                anchored  = anchor.pull(estimate: estimate)
+                pull_str  = anchor.strength * Constants::DEFAULT_ANCHOR_WEIGHT
+                correction = estimate.to_f - anchored
+
+                anchor.reinforce(observed_value: estimate)
+
+                {
+                  anchored_estimate: anchored,
+                  pull_strength:     pull_str,
+                  anchor_value:      anchor.value,
+                  correction:        correction
+                }
+              end
+
+              def reference_frame(value:, domain: :general)
+                domain    = domain.to_sym
+                reference = @references[domain] || strongest(domain: domain)&.value
+                return { perceived_value: value.to_f, gain_or_loss: :neutral, magnitude: 0.0 } if reference.nil?
+
+                diff       = value.to_f - reference
+                gain_loss  = diff >= 0 ? :gain : :loss
+                raw_mag    = diff.abs
+                magnitude  = gain_loss == :loss ? raw_mag * Constants::LOSS_AVERSION_FACTOR : raw_mag
+
+                { perceived_value: value.to_f, gain_or_loss: gain_loss, magnitude: magnitude, reference: reference, raw_diff: diff }
+              end
+
+              def decay_all
+                pruned = 0
+                @anchors.each_value do |arr|
+                  arr.each(&:decay)
+                  before = arr.size
+                  arr.reject! { |a| a.strength < Constants::ANCHOR_FLOOR }
+                  pruned += (before - arr.size)
+                end
+                @anchors.reject! { |_, arr| arr.empty? }
+                pruned
+              end
+
+              def shift_reference(domain:, new_reference:)
+                domain              = domain.to_sym
+                old                 = @references[domain]
+                @references[domain] = new_reference.to_f
+
+                diff = (new_reference.to_f - old.to_f).abs
+                significant = diff >= Constants::REFERENCE_SHIFT_THRESHOLD
+
+                { domain: domain, old_reference: old, new_reference: new_reference.to_f, significant: significant }
+              end
+
+              def domains
+                @anchors.keys.select { |d| @anchors[d]&.any? }
+              end
+
+              def to_h
+                total_anchors = @anchors.values.flatten.size
+                domain_count  = domains.size
+
+                {
+                  total_anchors: total_anchors,
+                  domain_count:  domain_count,
+                  domains:       domains,
+                  references:    @references.dup
+                }
+              end
+
+              private
+
+              def prune_domains
+                return unless @anchors.size > Constants::MAX_DOMAINS
+
+                oldest_domain = @anchors.min_by { |_, arr| arr.map(&:last_accessed).min }&.first
+                @anchors.delete(oldest_domain) if oldest_domain
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Anchoring
+          module Helpers
+            module Constants
+              DEFAULT_ANCHOR_WEIGHT        = 0.6    # How much the anchor pulls toward itself
+              ADJUSTMENT_RATE              = 0.1    # EMA alpha for updating anchors
+              ANCHOR_DECAY                 = 0.02   # Per-tick decay of anchor strength
+              ANCHOR_FLOOR                 = 0.05   # Minimum anchor strength before pruning
+              MAX_ANCHORS_PER_DOMAIN       = 20     # Cap per domain
+              MAX_DOMAINS                  = 50     # Cap total domains
+              REFERENCE_SHIFT_THRESHOLD    = 0.3    # Gap needed to shift reference point
+              LOSS_AVERSION_FACTOR         = 2.25   # Losses weighted 2.25x vs gains (prospect theory)
+
+              ANCHOR_LABELS = {
+                (0.8..)     => :strong,
+                (0.5...0.8) => :moderate,
+                (0.2...0.5) => :weak,
+                (..0.2)     => :fading
+              }.freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/learning/anchoring/runners/anchoring.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Anchoring
+          module Runners
+            module Anchoring
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def record_anchor(value:, domain: :general, **)
+                anchor = anchor_store.add(value: value, domain: domain)
+                Legion::Logging.debug "[anchoring] record_anchor domain=#{domain} value=#{value} id=#{anchor.id}"
+                { success: true, anchor: anchor.to_h }
+              end
+
+              def evaluate_estimate(estimate:, domain: :general, **)
+                result = anchor_store.evaluate(estimate: estimate, domain: domain)
+                Legion::Logging.debug "[anchoring] evaluate_estimate domain=#{domain} estimate=#{estimate} " \
+                                      "anchored=#{result[:anchored_estimate].round(4)} pull=#{result[:pull_strength].round(4)}"
+                { success: true }.merge(result)
+              end
+
+              def reference_frame(value:, domain: :general, **)
+                result = anchor_store.reference_frame(value: value, domain: domain)
+                Legion::Logging.debug "[anchoring] reference_frame domain=#{domain} value=#{value} " \
+                                      "gain_or_loss=#{result[:gain_or_loss]}"
+                { success: true }.merge(result)
+              end
+
+              def de_anchor(estimate:, domain: :general, **)
+                anchor = anchor_store.strongest(domain: domain)
+                if anchor.nil?
+                  Legion::Logging.debug "[anchoring] de_anchor domain=#{domain} no anchor found"
+                  return { success: true, corrected_estimate: estimate.to_f, anchor_bias: 0.0, domain: domain }
+                end
+
+                biased    = anchor.pull(estimate: estimate)
+                bias      = biased - estimate.to_f
+                corrected = estimate.to_f - bias
+
+                Legion::Logging.debug "[anchoring] de_anchor domain=#{domain} estimate=#{estimate} " \
+                                      "corrected=#{corrected.round(4)} bias=#{bias.round(4)}"
+
+                {
+                  success:            true,
+                  corrected_estimate: corrected,
+                  original_estimate:  estimate.to_f,
+                  anchor_bias:        bias,
+                  anchor_value:       anchor.value,
+                  domain:             domain
+                }
+              end
+
+              def shift_reference(domain:, new_reference:, **)
+                result = anchor_store.shift_reference(domain: domain, new_reference: new_reference)
+                Legion::Logging.info "[anchoring] shift_reference domain=#{domain} new=#{new_reference} significant=#{result[:significant]}"
+                { success: true }.merge(result)
+              end
+
+              def update_anchoring(**)
+                pruned = anchor_store.decay_all
+                Legion::Logging.debug "[anchoring] update_anchoring pruned=#{pruned}"
+                { success: true, pruned: pruned }
+              end
+
+              def domain_anchors(domain:, **)
+                domain   = domain.to_sym
+                anchor   = anchor_store.strongest(domain: domain)
+                all_list = anchor_store.instance_variable_get(:@anchors)[domain] || []
+                Legion::Logging.debug "[anchoring] domain_anchors domain=#{domain} count=#{all_list.size}"
+                {
+                  success:   true,
+                  domain:    domain,
+                  count:     all_list.size,
+                  strongest: anchor&.to_h,
+                  anchors:   all_list.map(&:to_h)
+                }
+              end
+
+              def anchoring_stats(**)
+                stats = anchor_store.to_h
+                Legion::Logging.debug "[anchoring] stats domains=#{stats[:domain_count]} total=#{stats[:total_anchors]}"
+                { success: true }.merge(stats)
+              end
+
+              private
+
+              def anchor_store
+                @anchor_store ||= Helpers::AnchorStore.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/learning/anchoring/version'
+require 'legion/extensions/agentic/learning/anchoring/helpers/constants'
+require 'legion/extensions/agentic/learning/anchoring/helpers/anchor'
+require 'legion/extensions/agentic/learning/anchoring/helpers/anchor_store'
+require 'legion/extensions/agentic/learning/anchoring/runners/anchoring'
+require 'legion/extensions/agentic/learning/anchoring/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Anchoring
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Catalyst
+          class Client
+            include Runners::CognitiveCatalyst
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/learning/catalyst/helpers/catalyst.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Catalyst
+          module Helpers
+            class Catalyst
+              include Constants
+
+              attr_reader :id, :catalyst_type, :domain, :potency, :specificity,
+                          :uses_count, :created_at
+
+              def initialize(catalyst_type:, domain:, potency: 0.5, specificity: 0.5)
+                @id            = SecureRandom.uuid
+                @catalyst_type = catalyst_type
+                @domain        = domain
+                @potency       = potency.clamp(0.0, 1.0)
+                @specificity   = specificity.clamp(0.0, 1.0)
+                @uses_count    = 0
+                @created_at    = Time.now.utc
+              end
+
+              # Apply this catalyst to a reaction — increments uses_count but does NOT reduce potency
+              # Catalysts are not consumed by use; they are reusable accelerators
+              # Returns activation_reduction = potency * specificity
+              def catalyze!(_reaction_type)
+                @uses_count += 1
+                (@potency * @specificity).round(10)
+              end
+
+              # Degrade from environmental wear (not from use)
+              def degrade!
+                @potency = (@potency - POTENCY_DECAY).clamp(0.0, 1.0).round(10)
+              end
+
+              # Recharge by increasing potency
+              def recharge!(amount)
+                @potency = (@potency + amount).clamp(0.0, 1.0).round(10)
+              end
+
+              def powerful?
+                @potency >= 0.8
+              end
+
+              def inert?
+                @potency < 0.2
+              end
+
+              def specific?
+                @specificity >= 0.7
+              end
+
+              def broad?
+                @specificity < 0.3
+              end
+
+              def potency_label
+                POTENCY_LABELS.find { |range, _| range.cover?(@potency) }&.last || :inert
+              end
+
+              def to_h
+                {
+                  id:            @id,
+                  catalyst_type: @catalyst_type,
+                  domain:        @domain,
+                  potency:       @potency,
+                  specificity:   @specificity,
+                  uses_count:    @uses_count,
+                  potency_label: potency_label,
+                  powerful:      powerful?,
+                  inert:         inert?,
+                  specific:      specific?,
+                  broad:         broad?,
+                  created_at:    @created_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end