lex-agentic-learning 0.1.0

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module LearningRate
+          module Runners
+            module LearningRate
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def record_prediction(correct:, domain: :general, **)
+                rate_model.record_prediction(domain: domain, correct: correct)
+                rate = rate_model.rate_for(domain)
+                accuracy = rate_model.accuracy_for(domain)
+                Legion::Logging.debug "[learning_rate] prediction: domain=#{domain} correct=#{correct} rate=#{rate.round(3)} accuracy=#{accuracy.round(3)}"
+                {
+                  success:  true,
+                  domain:   domain,
+                  rate:     rate,
+                  accuracy: accuracy,
+                  label:    rate_model.label_for(domain)
+                }
+              end
+
+              def record_surprise(magnitude:, domain: :general, **)
+                rate_model.record_surprise(domain: domain, magnitude: magnitude)
+                rate = rate_model.rate_for(domain)
+                Legion::Logging.debug "[learning_rate] surprise: domain=#{domain} magnitude=#{magnitude.round(3)} rate=#{rate.round(3)}"
+                { success: true, domain: domain, rate: rate, label: rate_model.label_for(domain) }
+              end
+
+              def record_error(magnitude:, domain: :general, **)
+                rate_model.record_error(domain: domain, magnitude: magnitude)
+                rate = rate_model.rate_for(domain)
+                Legion::Logging.debug "[learning_rate] error: domain=#{domain} magnitude=#{magnitude.round(3)} rate=#{rate.round(3)}"
+                { success: true, domain: domain, rate: rate, label: rate_model.label_for(domain) }
+              end
+
+              def current_rate(domain: :general, **)
+                rate = rate_model.rate_for(domain)
+                accuracy = rate_model.accuracy_for(domain)
+                {
+                  success:  true,
+                  domain:   domain,
+                  rate:     rate,
+                  accuracy: accuracy,
+                  label:    rate_model.label_for(domain)
+                }
+              end
+
+              def fastest_domains(count: 5, **)
+                domains = rate_model.fastest_domains(count)
+                { success: true, domains: domains, count: domains.size }
+              end
+
+              def slowest_domains(count: 5, **)
+                domains = rate_model.slowest_domains(count)
+                { success: true, domains: domains, count: domains.size }
+              end
+
+              def update_learning_rate(**)
+                rate_model.decay
+                overall = rate_model.overall_rate
+                Legion::Logging.debug "[learning_rate] tick: domains=#{rate_model.domain_count} overall=#{overall.round(3)}"
+                { success: true, domain_count: rate_model.domain_count, overall_rate: overall }
+              end
+
+              def learning_rate_stats(**)
+                { success: true, stats: rate_model.to_h }
+              end
+
+              private
+
+              def rate_model
+                @rate_model ||= Helpers::RateModel.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/learning/learning_rate/version'
+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'
+require 'legion/extensions/agentic/learning/learning_rate/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module LearningRate
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        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
+  end
+end

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        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
+  end
+end

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

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        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
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        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
+  end
+end

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

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        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
+  end
+end

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

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