lex-agentic-learning 0.1.0

data/lib/legion/extensions/agentic/learning/preference_learning/helpers/preference_engine.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module PreferenceLearning
+          module Helpers
+            class PreferenceEngine
+              def initialize
+                @options      = {} # id => Option
+                @comparisons  = 0
+              end
+
+              def register_option(label:, domain: :general)
+                return { error: 'max options reached' } if @options.size >= Constants::MAX_OPTIONS
+
+                option = Option.new(label: label, domain: domain)
+                @options[option.id] = option
+                option.to_h
+              end
+
+              def record_comparison(winner_id:, loser_id:)
+                winner = @options[winner_id]
+                loser  = @options[loser_id]
+                return { error: 'option not found' } unless winner && loser
+
+                @comparisons += 1
+                winner.win!
+                loser.lose!
+
+                {
+                  winner_id:    winner_id,
+                  loser_id:     loser_id,
+                  comparisons:  @comparisons,
+                  winner_score: winner.preference_score,
+                  loser_score:  loser.preference_score
+                }
+              end
+
+              def predict_preference(option_a_id:, option_b_id:)
+                a = @options[option_a_id]
+                b = @options[option_b_id]
+                return { error: 'option not found' } unless a && b
+
+                diff       = (a.preference_score - b.preference_score).abs
+                confidence = diff.clamp(0.0, 1.0)
+                preferred  = a.preference_score >= b.preference_score ? a : b
+
+                {
+                  preferred_id:    preferred.id,
+                  preferred_label: preferred.label,
+                  confidence:      confidence,
+                  score_a:         a.preference_score,
+                  score_b:         b.preference_score
+                }
+              end
+
+              def top_preferences(domain: nil, limit: 5)
+                filtered(domain).sort_by { |o| -o.preference_score }.first(limit).map(&:to_h)
+              end
+
+              def bottom_preferences(domain: nil, limit: 5)
+                filtered(domain).sort_by(&:preference_score).first(limit).map(&:to_h)
+              end
+
+              def preferences_by_domain(domain:)
+                @options.values
+                        .select { |o| o.domain == domain }
+                        .sort_by { |o| -o.preference_score }
+                        .map(&:to_h)
+              end
+
+              def preference_stability
+                scores = @options.values.map(&:preference_score)
+                return 0.0 if scores.size < 2
+
+                mean = scores.sum / scores.size.to_f
+                variance = scores.sum { |s| (s - mean)**2 } / scores.size.to_f
+                Math.sqrt(variance)
+              end
+
+              def most_compared(limit: 10)
+                @options.values
+                        .sort_by { |o| -o.times_seen }
+                        .first(limit)
+                        .map(&:to_h)
+              end
+
+              def decay_all
+                @options.each_value do |option|
+                  delta = (option.preference_score - Constants::DEFAULT_PREFERENCE) * Constants::DECAY_RATE
+                  option.preference_score = (option.preference_score - delta)
+                                            .clamp(Constants::PREFERENCE_FLOOR, Constants::PREFERENCE_CEILING)
+                end
+                @options.size
+              end
+
+              def to_h
+                {
+                  total_options: @options.size,
+                  comparisons:   @comparisons,
+                  stability:     preference_stability,
+                  options:       @options.values.map(&:to_h)
+                }
+              end
+
+              private
+
+              def filtered(domain)
+                return @options.values if domain.nil?
+
+                @options.values.select { |o| o.domain == domain }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module PreferenceLearning
+          module Runners
+            module PreferenceLearning
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def register_preference_option(label:, domain: :general, **)
+                result = preference_engine.register_option(label: label, domain: domain)
+                if result[:error]
+                  Legion::Logging.warn "[preference_learning] register failed: #{result[:error]}"
+                else
+                  Legion::Logging.debug "[preference_learning] registered option id=#{result[:id]} label=#{label} domain=#{domain}"
+                end
+                result
+              end
+
+              def record_preference_comparison(winner_id:, loser_id:, **)
+                result = preference_engine.record_comparison(winner_id: winner_id, loser_id: loser_id)
+                if result[:error]
+                  Legion::Logging.warn "[preference_learning] comparison failed: #{result[:error]}"
+                else
+                  Legion::Logging.info "[preference_learning] comparison: winner=#{winner_id} loser=#{loser_id} total=#{result[:comparisons]}"
+                end
+                result
+              end
+
+              def predict_preference_outcome(option_a_id:, option_b_id:, **)
+                result = preference_engine.predict_preference(option_a_id: option_a_id, option_b_id: option_b_id)
+                if result[:error]
+                  Legion::Logging.warn "[preference_learning] predict failed: #{result[:error]}"
+                else
+                  Legion::Logging.debug "[preference_learning] predict: preferred=#{result[:preferred_label]} confidence=#{result[:confidence].round(2)}"
+                end
+                result
+              end
+
+              def top_preferences_report(domain: nil, limit: 5, **)
+                options = preference_engine.top_preferences(domain: domain, limit: limit)
+                Legion::Logging.debug "[preference_learning] top #{limit} preferences domain=#{domain.inspect} count=#{options.size}"
+                { domain: domain, limit: limit, options: options }
+              end
+
+              def preference_stability_report(**)
+                stability = preference_engine.preference_stability
+                label     = stability < 0.1 ? :stable : :variable
+                Legion::Logging.debug "[preference_learning] stability=#{stability.round(4)} label=#{label}"
+                { stability: stability, label: label }
+              end
+
+              def update_preference_learning(**)
+                count = preference_engine.decay_all
+                Legion::Logging.debug "[preference_learning] decay cycle: options_updated=#{count}"
+                { decayed: count }
+              end
+
+              def preference_learning_stats(**)
+                engine_hash = preference_engine.to_h
+                Legion::Logging.debug "[preference_learning] stats: total_options=#{engine_hash[:total_options]} comparisons=#{engine_hash[:comparisons]}"
+                engine_hash.merge(stability_label: preference_engine_stability_label)
+              end
+
+              private
+
+              def preference_engine
+                @preference_engine ||= Helpers::PreferenceEngine.new
+              end
+
+              def preference_engine_stability_label
+                stability = preference_engine.preference_stability
+                stability < 0.1 ? :stable : :variable
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/learning/preference_learning/version'
+require 'legion/extensions/agentic/learning/preference_learning/helpers/constants'
+require 'legion/extensions/agentic/learning/preference_learning/helpers/option'
+require 'legion/extensions/agentic/learning/preference_learning/helpers/preference_engine'
+require 'legion/extensions/agentic/learning/preference_learning/runners/preference_learning'
+require 'legion/extensions/agentic/learning/preference_learning/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module PreferenceLearning
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Procedural
+          class Client
+            include Runners::ProceduralLearning
+
+            def initialize(engine: nil)
+              @engine = engine || Helpers::LearningEngine.new
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Procedural
+          module Helpers
+            module Constants
+              MAX_SKILLS = 200
+              MAX_PRODUCTIONS = 500
+              MAX_HISTORY = 300
+
+              DEFAULT_PROFICIENCY = 0.1
+              PROFICIENCY_FLOOR = 0.0
+              PROFICIENCY_CEILING = 1.0
+
+              PRACTICE_GAIN = 0.08
+              COMPILATION_THRESHOLD = 0.6
+              AUTOMATION_THRESHOLD = 0.85
+              DECAY_RATE = 0.01
+              STALE_THRESHOLD = 300
+
+              SKILL_STAGES = %i[declarative associative autonomous].freeze
+
+              STAGE_LABELS = {
+                (0.0...0.3)  => :declarative,
+                (0.3...0.6)  => :associative,
+                (0.6...0.85) => :compiled,
+                (0.85..1.0)  => :autonomous
+              }.freeze
+
+              PROFICIENCY_LABELS = {
+                (0.8..)     => :expert,
+                (0.6...0.8) => :proficient,
+                (0.4...0.6) => :intermediate,
+                (0.2...0.4) => :beginner,
+                (..0.2)     => :novice
+              }.freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/learning/procedural/helpers/learning_engine.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Procedural
+          module Helpers
+            class LearningEngine
+              include Constants
+
+              attr_reader :history
+
+              def initialize
+                @skills      = {}
+                @productions = {}
+                @history     = []
+              end
+
+              def create_skill(name:, domain:)
+                evict_oldest_skill if @skills.size >= MAX_SKILLS
+
+                skill = Skill.new(name: name, domain: domain)
+                @skills[skill.id] = skill
+                record_history(:skill_created, skill.id)
+                skill
+              end
+
+              def add_production(skill_id:, condition:, action:, domain:)
+                skill = @skills[skill_id]
+                return { success: false, reason: :skill_not_found } unless skill
+                return { success: false, reason: :max_productions } if @productions.size >= MAX_PRODUCTIONS
+
+                production = Production.new(
+                  condition: condition, action: action,
+                  domain: domain, skill_id: skill_id
+                )
+                @productions[production.id] = production
+                skill.add_production(production.id)
+                record_history(:production_added, production.id)
+                production
+              end
+
+              def practice_skill(skill_id:, success:)
+                skill = @skills[skill_id]
+                return { success: false, reason: :not_found } unless skill
+
+                skill.practice!(success: success)
+                record_history(:practiced, skill_id)
+                build_practice_result(skill)
+              end
+
+              def execute_production(production_id:, success:)
+                production = @productions[production_id]
+                return { success: false, reason: :not_found } unless production
+
+                production.execute!(success: success)
+                record_history(:production_executed, production_id)
+                { success: true, production_id: production_id, success_rate: production.success_rate }
+              end
+
+              def skill_assessment(skill_id:)
+                skill = @skills[skill_id]
+                return { success: false, reason: :not_found } unless skill
+
+                productions = skill.productions.filter_map { |pid| @productions[pid] }
+                build_assessment(skill, productions)
+              end
+
+              def compiled_skills
+                @skills.values.select(&:compiled?)
+              end
+
+              def autonomous_skills
+                @skills.values.select(&:autonomous?)
+              end
+
+              def by_domain(domain:)
+                @skills.values.select { |s| s.domain == domain }
+              end
+
+              def most_practiced(limit: 5)
+                @skills.values.sort_by { |s| -s.practice_count }.first(limit)
+              end
+
+              def decay_all
+                @skills.each_value(&:decay!)
+              end
+
+              def prune_stale
+                stale_ids = @skills.select { |_id, s| s.proficiency <= 0.02 }.keys
+                stale_ids.each do |sid|
+                  remove_skill_productions(sid)
+                  @skills.delete(sid)
+                end
+                stale_ids.size
+              end
+
+              def to_h
+                {
+                  total_skills:      @skills.size,
+                  total_productions: @productions.size,
+                  compiled_count:    compiled_skills.size,
+                  autonomous_count:  autonomous_skills.size,
+                  history_count:     @history.size,
+                  stage_counts:      stage_counts
+                }
+              end
+
+              private
+
+              def build_practice_result(skill)
+                {
+                  success:     true,
+                  skill_id:    skill.id,
+                  proficiency: skill.proficiency,
+                  stage:       skill.stage,
+                  stage_label: skill.stage_label
+                }
+              end
+
+              def build_assessment(skill, productions)
+                {
+                  success:          true,
+                  skill:            skill.to_h,
+                  productions:      productions.map(&:to_h),
+                  reliable_count:   productions.count(&:reliable?),
+                  total_executions: productions.sum(&:execution_count)
+                }
+              end
+
+              def remove_skill_productions(skill_id)
+                @productions.delete_if { |_id, prod| prod.skill_id == skill_id }
+              end
+
+              def evict_oldest_skill
+                oldest_id = @skills.min_by { |_id, s| s.last_practiced_at }&.first
+                return unless oldest_id
+
+                remove_skill_productions(oldest_id)
+                @skills.delete(oldest_id)
+              end
+
+              def record_history(event, subject_id)
+                @history << { event: event, subject_id: subject_id, at: Time.now.utc }
+                @history.shift while @history.size > MAX_HISTORY
+              end
+
+              def stage_counts
+                @skills.values.each_with_object(Hash.new(0)) do |skill, counts|
+                  counts[skill.stage] += 1
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/learning/procedural/helpers/production.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Procedural
+          module Helpers
+            class Production
+              include Constants
+
+              attr_reader :id, :condition, :action, :domain, :skill_id,
+                          :execution_count, :success_count, :created_at, :last_executed_at
+
+              def initialize(condition:, action:, domain:, skill_id:)
+                @id               = SecureRandom.uuid
+                @condition        = condition
+                @action           = action
+                @domain           = domain
+                @skill_id         = skill_id
+                @execution_count  = 0
+                @success_count    = 0
+                @created_at       = Time.now.utc
+                @last_executed_at = @created_at
+              end
+
+              def execute!(success:)
+                @execution_count  += 1
+                @success_count    += 1 if success
+                @last_executed_at  = Time.now.utc
+              end
+
+              def success_rate
+                return 0.0 if @execution_count.zero?
+
+                @success_count.to_f / @execution_count
+              end
+
+              def reliable?
+                success_rate >= 0.7 && @execution_count >= 3
+              end
+
+              def to_h
+                {
+                  id:               @id,
+                  condition:        @condition,
+                  action:           @action,
+                  domain:           @domain,
+                  skill_id:         @skill_id,
+                  execution_count:  @execution_count,
+                  success_count:    @success_count,
+                  success_rate:     success_rate,
+                  reliable:         reliable?,
+                  created_at:       @created_at,
+                  last_executed_at: @last_executed_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/learning/procedural/helpers/skill.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Procedural
+          module Helpers
+            class Skill
+              include Constants
+
+              attr_reader :id, :name, :domain, :proficiency, :practice_count,
+                          :stage, :productions, :created_at, :last_practiced_at
+
+              def initialize(name:, domain:)
+                @id               = SecureRandom.uuid
+                @name             = name
+                @domain           = domain
+                @proficiency      = DEFAULT_PROFICIENCY
+                @practice_count   = 0
+                @stage            = :declarative
+                @productions      = []
+                @created_at       = Time.now.utc
+                @last_practiced_at = @created_at
+              end
+
+              def practice!(success:)
+                @practice_count    += 1
+                @last_practiced_at  = Time.now.utc
+                gain = success ? PRACTICE_GAIN : PRACTICE_GAIN * 0.3
+                @proficiency = (@proficiency + gain).clamp(PROFICIENCY_FLOOR, PROFICIENCY_CEILING)
+                update_stage
+              end
+
+              def add_production(production_id)
+                @productions << production_id unless @productions.include?(production_id)
+              end
+
+              def compiled?
+                @proficiency >= COMPILATION_THRESHOLD
+              end
+
+              def autonomous?
+                @proficiency >= AUTOMATION_THRESHOLD
+              end
+
+              def stage_label
+                STAGE_LABELS.find { |range, _| range.cover?(@proficiency) }&.last || :declarative
+              end
+
+              def proficiency_label
+                PROFICIENCY_LABELS.find { |range, _| range.cover?(@proficiency) }&.last || :novice
+              end
+
+              def decay!
+                @proficiency = (@proficiency - DECAY_RATE).clamp(PROFICIENCY_FLOOR, PROFICIENCY_CEILING)
+                update_stage
+              end
+
+              def stale?
+                (Time.now.utc - @last_practiced_at) > STALE_THRESHOLD
+              end
+
+              def to_h
+                {
+                  id:                @id,
+                  name:              @name,
+                  domain:            @domain,
+                  proficiency:       @proficiency,
+                  proficiency_label: proficiency_label,
+                  stage:             @stage,
+                  stage_label:       stage_label,
+                  practice_count:    @practice_count,
+                  production_count:  @productions.size,
+                  compiled:          compiled?,
+                  autonomous:        autonomous?,
+                  created_at:        @created_at,
+                  last_practiced_at: @last_practiced_at
+                }
+              end
+
+              private
+
+              def update_stage
+                @stage = if autonomous?
+                           :autonomous
+                         elsif compiled?
+                           :associative
+                         else
+                           :declarative
+                         end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end