lex-meta-learning 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8a759f0665914754bffed745ff2c13f7f2ec290e1c8093a35b725acdd8959578
+  data.tar.gz: 6a05f278f9a31fc145394fc9b5f599c997f0d0dcd03f7edb90bd1b6a07fe585f
+SHA512:
+  metadata.gz: 9b9bddd16d9dac71aed816ad189205954f4568fb5b381f96dfd134db58a71fc3b2d210562d250a30352fcab2fc71a659eedcd95f7eaf35a05fd0427728173a24
+  data.tar.gz: 2784c2e50db877ab19b9c8234a317732394356917ad5e380b60a52fe49eaf2515074026ec3d9fe67882326413c94f2a869eca0f924e71f80e48bfd26fa7c68c3

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rspec', '~> 3.13'
+gem 'rubocop', '~> 1.75', require: false
+gem 'rubocop-rspec', require: false
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/lex-meta-learning.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/meta_learning/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-meta-learning'
+  spec.version       = Legion::Extensions::MetaLearning::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Meta-Learning'
+  spec.description   = 'Meta-learning engine for brain-modeled agentic AI — tracks learning efficiency, ' \
+                       'adapts learning rates, and selects strategies based on past performance'
+  spec.homepage      = 'https://github.com/LegionIO/lex-meta-learning'
+  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-meta-learning'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-meta-learning'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-meta-learning'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-meta-learning/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-meta-learning.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/meta_learning/helpers/constants'
+require 'legion/extensions/meta_learning/helpers/learning_domain'
+require 'legion/extensions/meta_learning/helpers/strategy'
+require 'legion/extensions/meta_learning/helpers/meta_learning_engine'
+require 'legion/extensions/meta_learning/runners/meta_learning'
+
+module Legion
+  module Extensions
+    module MetaLearning
+      class Client
+        include Runners::MetaLearning
+
+        private
+
+        def engine
+          @engine ||= Helpers::MetaLearningEngine.new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module MetaLearning
+      module Helpers
+        module Constants
+          MAX_DOMAINS    = 100
+          MAX_STRATEGIES = 50
+          MAX_EPISODES   = 1000
+
+          DEFAULT_LEARNING_RATE = 0.1
+          RATE_BOOST            = 0.02
+          RATE_DECAY            = 0.01
+          TRANSFER_BONUS        = 0.05
+
+          PROFICIENCY_LABELS = {
+            (0.8..)     => :expert,
+            (0.6...0.8) => :proficient,
+            (0.4...0.6) => :intermediate,
+            (0.2...0.4) => :novice,
+            (..0.2)     => :beginner
+          }.freeze
+
+          EFFICIENCY_LABELS = {
+            (0.8..)     => :highly_efficient,
+            (0.6...0.8) => :efficient,
+            (0.4...0.6) => :moderate,
+            (0.2...0.4) => :slow,
+            (..0.2)     => :struggling
+          }.freeze
+
+          STRATEGY_TYPES = %i[
+            repetition elaboration analogy decomposition
+            pattern_matching trial_and_error observation
+            interleaving spaced_practice retrieval_practice
+          ].freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/meta_learning/helpers/learning_domain.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module MetaLearning
+      module Helpers
+        class LearningDomain
+          include Constants
+
+          attr_accessor :preferred_strategy
+          attr_reader :id, :name, :proficiency, :learning_rate, :episodes_count, :successes, :failures, :related_domains, :created_at
+
+          def initialize(name:, learning_rate: DEFAULT_LEARNING_RATE, related_domains: [])
+            @id               = SecureRandom.uuid
+            @name             = name
+            @proficiency      = 0.0
+            @learning_rate    = learning_rate.clamp(0.001, 1.0)
+            @episodes_count   = 0
+            @successes        = 0
+            @failures         = 0
+            @preferred_strategy = nil
+            @related_domains  = Array(related_domains).dup
+            @created_at       = Time.now.utc
+          end
+
+          def record_success!
+            @successes      += 1
+            @episodes_count += 1
+            @proficiency     = (@proficiency + @learning_rate).clamp(0.0, 1.0).round(10)
+          end
+
+          def record_failure!
+            @failures       += 1
+            @episodes_count += 1
+            penalty          = (@learning_rate * 0.5).round(10)
+            @proficiency     = (@proficiency - penalty).clamp(0.0, 1.0).round(10)
+          end
+
+          def efficiency
+            total = @successes + @failures
+            return 0.0 if total.zero?
+
+            (@successes.to_f / total).round(10)
+          end
+
+          def efficiency_label
+            EFFICIENCY_LABELS.find { |range, _| range.cover?(efficiency) }&.last || :struggling
+          end
+
+          def proficiency_label
+            PROFICIENCY_LABELS.find { |range, _| range.cover?(@proficiency) }&.last || :beginner
+          end
+
+          def adapt_rate!(delta:)
+            @learning_rate = (@learning_rate + delta).clamp(0.001, 1.0).round(10)
+          end
+
+          def to_h
+            {
+              id:                 @id,
+              name:               @name,
+              proficiency:        @proficiency,
+              proficiency_label:  proficiency_label,
+              learning_rate:      @learning_rate,
+              episodes_count:     @episodes_count,
+              successes:          @successes,
+              failures:           @failures,
+              efficiency:         efficiency,
+              efficiency_label:   efficiency_label,
+              preferred_strategy: @preferred_strategy,
+              related_domains:    @related_domains,
+              created_at:         @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/meta_learning/helpers/meta_learning_engine.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module MetaLearning
+      module Helpers
+        class MetaLearningEngine
+          include Constants
+
+          attr_reader :domains, :strategies, :episodes
+
+          def initialize
+            @domains    = {}
+            @strategies = {}
+            @episodes   = []
+          end
+
+          def create_domain(name:, learning_rate: DEFAULT_LEARNING_RATE, related_domains: [])
+            return { error: :limit_reached } if @domains.size >= MAX_DOMAINS
+
+            domain = LearningDomain.new(name: name, learning_rate: learning_rate, related_domains: related_domains)
+            @domains[domain.id] = domain
+            domain
+          end
+
+          def create_strategy(name:, strategy_type:)
+            return { error: :limit_reached } if @strategies.size >= MAX_STRATEGIES
+            return { error: :invalid_strategy_type } unless STRATEGY_TYPES.include?(strategy_type)
+
+            strategy = Strategy.new(name: name, strategy_type: strategy_type)
+            @strategies[strategy.id] = strategy
+            strategy
+          end
+
+          def record_episode(domain_id:, success:, strategy_id: nil)
+            domain = @domains[domain_id]
+            return { error: :domain_not_found } unless domain
+
+            success ? domain.record_success! : domain.record_failure!
+
+            strategy = @strategies[strategy_id] if strategy_id
+            strategy&.use!(success: success, domain_name: domain.name)
+
+            if strategy && success
+              current_preferred_rate = preferred_strategy_rate_for(domain)
+              domain.preferred_strategy = strategy.name if strategy.success_rate > current_preferred_rate
+            end
+
+            episode = build_episode(domain, strategy_id, success)
+            @episodes << episode
+            @episodes.shift while @episodes.size > MAX_EPISODES
+
+            check_transfer_opportunities(domain)
+
+            episode
+          end
+
+          def recommend_strategy(domain_id:)
+            domain = @domains[domain_id]
+            return { error: :domain_not_found } unless domain
+
+            candidate = best_strategy_for_domain(domain)
+            return { recommendation: nil, reason: :no_data } if candidate.nil?
+
+            { recommendation: candidate.name, strategy_id: candidate.id, success_rate: candidate.success_rate }
+          end
+
+          def transfer_check(source_domain_id:, target_domain_id:)
+            source = @domains[source_domain_id]
+            target = @domains[target_domain_id]
+            return { error: :domain_not_found } unless source && target
+
+            eligible = source.proficiency >= 0.6 && target.related_domains.include?(source.name)
+            { eligible: eligible, source_proficiency: source.proficiency, target_domain: target.name }
+          end
+
+          def apply_transfer(source_domain_id:, target_domain_id:)
+            source = @domains[source_domain_id]
+            target = @domains[target_domain_id]
+            return { error: :domain_not_found } unless source && target
+
+            check = transfer_check(source_domain_id: source_domain_id, target_domain_id: target_domain_id)
+            return { applied: false, reason: :not_eligible } unless check[:eligible]
+
+            target.adapt_rate!(delta: TRANSFER_BONUS)
+            { applied: true, target_domain: target.name, new_learning_rate: target.learning_rate }
+          end
+
+          def domain_ranking(limit: 10)
+            @domains.values
+                    .sort_by { |d| -d.proficiency }
+                    .first(limit)
+                    .map(&:to_h)
+          end
+
+          def strategy_ranking(limit: 10)
+            @strategies.values
+                       .sort_by { |s| -s.success_rate }
+                       .first(limit)
+                       .map(&:to_h)
+          end
+
+          def overall_efficiency
+            return 0.0 if @domains.empty?
+
+            total = @domains.values.sum(&:efficiency)
+            (total / @domains.size).round(10)
+          end
+
+          def learning_curve(domain_id:)
+            domain = @domains[domain_id]
+            return { error: :domain_not_found } unless domain
+
+            domain_episodes = @episodes.select { |e| e[:domain_id] == domain_id }
+            { domain: domain.name, curve: domain_episodes }
+          end
+
+          def adapt_rates
+            adapted = []
+            @domains.each_value do |domain|
+              next if domain.episodes_count.zero?
+
+              if domain.efficiency >= 0.8
+                domain.adapt_rate!(delta: RATE_BOOST)
+                adapted << { domain: domain.name, direction: :boost, new_rate: domain.learning_rate }
+              elsif domain.efficiency < 0.2
+                domain.adapt_rate!(delta: -RATE_DECAY)
+                adapted << { domain: domain.name, direction: :decay, new_rate: domain.learning_rate }
+              end
+            end
+            { adapted: adapted, count: adapted.size }
+          end
+
+          def prune_stale_domains(min_episodes: 1)
+            before = @domains.size
+            @domains.reject! { |_, d| d.episodes_count < min_episodes }
+            pruned = before - @domains.size
+            { pruned: pruned, remaining: @domains.size }
+          end
+
+          def to_h
+            {
+              domain_count:       @domains.size,
+              strategy_count:     @strategies.size,
+              episode_count:      @episodes.size,
+              overall_efficiency: overall_efficiency,
+              top_domain:         @domains.values.max_by(&:proficiency)&.name,
+              top_strategy:       @strategies.values.max_by(&:success_rate)&.name
+            }
+          end
+
+          private
+
+          def build_episode(domain, strategy_id, success)
+            {
+              id:          SecureRandom.uuid,
+              domain_id:   domain.id,
+              domain_name: domain.name,
+              strategy_id: strategy_id,
+              success:     success,
+              proficiency: domain.proficiency,
+              recorded_at: Time.now.utc
+            }
+          end
+
+          def preferred_strategy_rate_for(domain)
+            return 0.0 unless domain.preferred_strategy
+
+            strategy = @strategies.values.find { |s| s.name == domain.preferred_strategy }
+            strategy&.success_rate || 0.0
+          end
+
+          def best_strategy_for_domain(domain)
+            direct = strategies_used_in_domain(domain.name)
+            return direct.max_by(&:success_rate) if direct.any?
+
+            related_strategies = domain.related_domains.flat_map { |rname| strategies_used_in_domain(rname) }.uniq
+            related_strategies.max_by(&:success_rate)
+          end
+
+          def strategies_used_in_domain(domain_name)
+            @strategies.values.select { |s| s.domains_used.include?(domain_name) }
+          end
+
+          def check_transfer_opportunities(domain)
+            @domains.each_value do |target|
+              next if target.id == domain.id
+              next unless target.related_domains.include?(domain.name)
+
+              check = transfer_check(source_domain_id: domain.id, target_domain_id: target.id)
+              apply_transfer(source_domain_id: domain.id, target_domain_id: target.id) if check[:eligible]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/meta_learning/helpers/strategy.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module MetaLearning
+      module Helpers
+        class Strategy
+          include Constants
+
+          attr_reader :id, :name, :strategy_type, :usage_count,
+                      :success_count, :domains_used, :created_at
+
+          def initialize(name:, strategy_type:)
+            @id             = SecureRandom.uuid
+            @name           = name
+            @strategy_type  = strategy_type
+            @usage_count    = 0
+            @success_count  = 0
+            @domains_used   = []
+            @created_at     = Time.now.utc
+          end
+
+          def use!(success:, domain_name: nil)
+            @usage_count += 1
+            @success_count += 1 if success
+            @domains_used << domain_name if domain_name && !@domains_used.include?(domain_name)
+          end
+
+          def success_rate
+            return 0.0 if @usage_count.zero?
+
+            (@success_count.to_f / @usage_count).round(10)
+          end
+
+          def versatility
+            @domains_used.uniq.size
+          end
+
+          def to_h
+            {
+              id:            @id,
+              name:          @name,
+              strategy_type: @strategy_type,
+              usage_count:   @usage_count,
+              success_count: @success_count,
+              success_rate:  success_rate,
+              versatility:   versatility,
+              domains_used:  @domains_used,
+              created_at:    @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module MetaLearning
+      module Runners
+        module MetaLearning
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def create_learning_domain(name:, learning_rate: Helpers::Constants::DEFAULT_LEARNING_RATE,
+                                     related_domains: [], **)
+            result = engine.create_domain(name: name, learning_rate: learning_rate, related_domains: related_domains)
+            if result.is_a?(Hash) && result[:error]
+              Legion::Logging.warn "[meta_learning] create_domain failed: #{result[:error]}"
+              return result
+            end
+
+            Legion::Logging.debug "[meta_learning] domain created: #{result.name} id=#{result.id[0..7]}"
+            result.to_h
+          end
+
+          def register_learning_strategy(name:, strategy_type:, **)
+            result = engine.create_strategy(name: name, strategy_type: strategy_type)
+            if result.is_a?(Hash) && result[:error]
+              Legion::Logging.warn "[meta_learning] create_strategy failed: #{result[:error]}"
+              return result
+            end
+
+            Legion::Logging.debug "[meta_learning] strategy registered: #{result.name} type=#{result.strategy_type}"
+            result.to_h
+          end
+
+          def record_learning_episode(domain_id:, success:, strategy_id: nil, **)
+            result = engine.record_episode(domain_id: domain_id, strategy_id: strategy_id, success: success)
+            if result.is_a?(Hash) && result[:error]
+              Legion::Logging.warn "[meta_learning] record_episode failed: #{result[:error]}"
+              return result
+            end
+
+            Legion::Logging.debug "[meta_learning] episode recorded domain=#{result[:domain_name]} " \
+                                  "success=#{success} proficiency=#{result[:proficiency].round(4)}"
+            result
+          end
+
+          def recommend_learning_strategy(domain_id:, **)
+            result = engine.recommend_strategy(domain_id: domain_id)
+            Legion::Logging.debug "[meta_learning] strategy recommendation domain=#{domain_id[0..7]} " \
+                                  "recommendation=#{result[:recommendation]}"
+            result
+          end
+
+          def check_transfer_learning(source_domain_id:, target_domain_id:, **)
+            result = engine.transfer_check(source_domain_id: source_domain_id, target_domain_id: target_domain_id)
+            Legion::Logging.debug "[meta_learning] transfer check eligible=#{result[:eligible]}"
+            result
+          end
+
+          def apply_transfer_bonus(source_domain_id:, target_domain_id:, **)
+            result = engine.apply_transfer(source_domain_id: source_domain_id, target_domain_id: target_domain_id)
+            Legion::Logging.info "[meta_learning] transfer applied=#{result[:applied]}"
+            result
+          end
+
+          def learning_domain_ranking(limit: 10, **)
+            ranking = engine.domain_ranking(limit: limit)
+            Legion::Logging.debug "[meta_learning] domain ranking returned #{ranking.size} domains"
+            { ranking: ranking, count: ranking.size }
+          end
+
+          def learning_strategy_ranking(limit: 10, **)
+            ranking = engine.strategy_ranking(limit: limit)
+            Legion::Logging.debug "[meta_learning] strategy ranking returned #{ranking.size} strategies"
+            { ranking: ranking, count: ranking.size }
+          end
+
+          def learning_curve_report(domain_id:, **)
+            result = engine.learning_curve(domain_id: domain_id)
+            if result.is_a?(Hash) && result[:error]
+              Legion::Logging.warn "[meta_learning] learning_curve failed: #{result[:error]}"
+              return result
+            end
+
+            Legion::Logging.debug "[meta_learning] learning curve domain=#{result[:domain]} " \
+                                  "episodes=#{result[:curve].size}"
+            result
+          end
+
+          def update_meta_learning(**)
+            adapt_result = engine.adapt_rates
+            prune_result = engine.prune_stale_domains
+            stats        = engine.to_h
+            Legion::Logging.info "[meta_learning] update: adapted=#{adapt_result[:count]} " \
+                                 "pruned=#{prune_result[:pruned]} domains=#{stats[:domain_count]}"
+            { adapt: adapt_result, prune: prune_result, stats: stats }
+          end
+
+          def meta_learning_stats(**)
+            stats = engine.to_h
+            Legion::Logging.debug "[meta_learning] stats domains=#{stats[:domain_count]} " \
+                                  "strategies=#{stats[:strategy_count]} efficiency=#{stats[:overall_efficiency]}"
+            stats
+          end
+
+          private
+
+          def engine
+            @engine ||= Helpers::MetaLearningEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/meta_learning.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/meta_learning/version'
+require 'legion/extensions/meta_learning/helpers/constants'
+require 'legion/extensions/meta_learning/helpers/learning_domain'
+require 'legion/extensions/meta_learning/helpers/strategy'
+require 'legion/extensions/meta_learning/helpers/meta_learning_engine'
+require 'legion/extensions/meta_learning/runners/meta_learning'
+require 'legion/extensions/meta_learning/client'
+
+module Legion
+  module Extensions
+    module MetaLearning
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

data/spec/legion/extensions/meta_learning/client_spec.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/meta_learning/client'
+
+RSpec.describe Legion::Extensions::MetaLearning::Client do
+  it 'responds to all runner methods' do
+    client = described_class.new
+    expect(client).to respond_to(:create_learning_domain)
+    expect(client).to respond_to(:register_learning_strategy)
+    expect(client).to respond_to(:record_learning_episode)
+    expect(client).to respond_to(:recommend_learning_strategy)
+    expect(client).to respond_to(:check_transfer_learning)
+    expect(client).to respond_to(:apply_transfer_bonus)
+    expect(client).to respond_to(:learning_domain_ranking)
+    expect(client).to respond_to(:learning_strategy_ranking)
+    expect(client).to respond_to(:learning_curve_report)
+    expect(client).to respond_to(:update_meta_learning)
+    expect(client).to respond_to(:meta_learning_stats)
+  end
+
+  it 'maintains isolated state per instance' do
+    c1 = described_class.new
+    c2 = described_class.new
+    c1.create_learning_domain(name: 'ruby')
+    expect(c2.meta_learning_stats[:domain_count]).to eq(0)
+  end
+end

data/spec/legion/extensions/meta_learning/helpers/constants_spec.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::MetaLearning::Helpers::Constants do
+  it 'defines MAX_DOMAINS as 100' do
+    expect(described_module::MAX_DOMAINS).to eq(100)
+  end
+
+  it 'defines MAX_STRATEGIES as 50' do
+    expect(described_module::MAX_STRATEGIES).to eq(50)
+  end
+
+  it 'defines MAX_EPISODES as 1000' do
+    expect(described_module::MAX_EPISODES).to eq(1000)
+  end
+
+  it 'defines DEFAULT_LEARNING_RATE as 0.1' do
+    expect(described_module::DEFAULT_LEARNING_RATE).to eq(0.1)
+  end
+
+  it 'defines STRATEGY_TYPES as an array of symbols' do
+    expect(described_module::STRATEGY_TYPES).to be_an(Array)
+    expect(described_module::STRATEGY_TYPES).to all(be_a(Symbol))
+    expect(described_module::STRATEGY_TYPES).to include(:repetition, :elaboration, :retrieval_practice)
+  end
+
+  it 'defines PROFICIENCY_LABELS covering full 0..1 range' do
+    labels = [0.0, 0.1, 0.25, 0.45, 0.65, 0.85].map do |v|
+      described_module::PROFICIENCY_LABELS.find { |range, _| range.cover?(v) }&.last
+    end
+    expect(labels).to all(be_a(Symbol))
+  end
+
+  it 'defines EFFICIENCY_LABELS covering full 0..1 range' do
+    labels = [0.0, 0.1, 0.25, 0.45, 0.65, 0.85].map do |v|
+      described_module::EFFICIENCY_LABELS.find { |range, _| range.cover?(v) }&.last
+    end
+    expect(labels).to all(be_a(Symbol))
+  end
+
+  def described_module
+    Legion::Extensions::MetaLearning::Helpers::Constants
+  end
+end