lex-agentic-learning 0.1.0

data/lib/legion/extensions/agentic/learning/procedural/runners/procedural_learning.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Procedural
+          module Runners
+            module ProceduralLearning
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def create_skill(name:, domain:, **)
+                skill = engine.create_skill(name: name, domain: domain)
+                Legion::Logging.debug "[procedural_learning] created skill=#{name} " \
+                                      "domain=#{domain} id=#{skill.id[0..7]}"
+                { success: true, skill_id: skill.id, name: name, domain: domain,
+                  proficiency: skill.proficiency, stage: skill.stage }
+              end
+
+              def add_skill_production(skill_id:, condition:, action:, domain:, **)
+                result = engine.add_production(
+                  skill_id: skill_id, condition: condition,
+                  action: action, domain: domain
+                )
+
+                return result unless result.is_a?(Helpers::Production)
+
+                Legion::Logging.debug '[procedural_learning] production added ' \
+                                      "skill=#{skill_id[0..7]} condition=#{condition}"
+                { success: true, production_id: result.id, skill_id: skill_id }
+              end
+
+              def practice_skill(skill_id:, success:, **)
+                result = engine.practice_skill(skill_id: skill_id, success: success)
+                Legion::Logging.debug "[procedural_learning] practice skill=#{skill_id[0..7]} " \
+                                      "success=#{success} proficiency=#{result[:proficiency]&.round(3)}"
+                result
+              end
+
+              def execute_production(production_id:, success:, **)
+                result = engine.execute_production(production_id: production_id, success: success)
+                Legion::Logging.debug "[procedural_learning] execute production=#{production_id[0..7]} " \
+                                      "success=#{success}"
+                result
+              end
+
+              def skill_assessment(skill_id:, **)
+                result = engine.skill_assessment(skill_id: skill_id)
+                Legion::Logging.debug "[procedural_learning] assessment skill=#{skill_id[0..7]}"
+                result
+              end
+
+              def compiled_skills(**)
+                skills = engine.compiled_skills
+                Legion::Logging.debug "[procedural_learning] compiled count=#{skills.size}"
+                { success: true, skills: skills.map(&:to_h), count: skills.size }
+              end
+
+              def autonomous_skills(**)
+                skills = engine.autonomous_skills
+                Legion::Logging.debug "[procedural_learning] autonomous count=#{skills.size}"
+                { success: true, skills: skills.map(&:to_h), count: skills.size }
+              end
+
+              def most_practiced_skills(limit: 5, **)
+                skills = engine.most_practiced(limit: limit)
+                Legion::Logging.debug "[procedural_learning] most_practiced limit=#{limit}"
+                { success: true, skills: skills.map(&:to_h), count: skills.size }
+              end
+
+              def update_procedural_learning(**)
+                engine.decay_all
+                pruned = engine.prune_stale
+                Legion::Logging.debug "[procedural_learning] decay+prune pruned=#{pruned}"
+                { success: true, pruned: pruned }
+              end
+
+              def procedural_learning_stats(**)
+                stats = engine.to_h
+                Legion::Logging.debug "[procedural_learning] stats total=#{stats[:total_skills]}"
+                { success: true }.merge(stats)
+              end
+
+              private
+
+              def engine
+                @engine ||= Helpers::LearningEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/learning/procedural/version'
+require 'legion/extensions/agentic/learning/procedural/helpers/constants'
+require 'legion/extensions/agentic/learning/procedural/helpers/production'
+require 'legion/extensions/agentic/learning/procedural/helpers/skill'
+require 'legion/extensions/agentic/learning/procedural/helpers/learning_engine'
+require 'legion/extensions/agentic/learning/procedural/runners/procedural_learning'
+require 'legion/extensions/agentic/learning/procedural/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Procedural
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/learning/scaffolding/helpers/constants'
+require 'legion/extensions/agentic/learning/scaffolding/helpers/scaffold'
+require 'legion/extensions/agentic/learning/scaffolding/helpers/scaffolding_engine'
+require 'legion/extensions/agentic/learning/scaffolding/runners/cognitive_scaffolding'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Scaffolding
+          class Client
+            include Runners::CognitiveScaffolding
+
+            attr_reader :engine
+
+            def initialize(engine: nil, **)
+              @engine = engine || Helpers::ScaffoldingEngine.new
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Scaffolding
+          module Helpers
+            module Constants
+              MAX_SCAFFOLDS      = 100
+              MAX_TASKS          = 500
+              MAX_HISTORY        = 300
+
+              DEFAULT_COMPETENCE = 0.3
+              COMPETENCE_FLOOR   = 0.0
+              COMPETENCE_CEILING = 1.0
+
+              ZPD_LOWER = 0.3
+              ZPD_UPPER = 0.8
+
+              SUPPORT_LEVELS = %i[full guided prompted independent].freeze
+
+              FADING_RATE          = 0.1
+              MASTERY_THRESHOLD    = 0.85
+              FRUSTRATION_THRESHOLD = 0.15
+
+              LEARNING_GAIN   = 0.08
+              FAILURE_SETBACK = 0.03
+              DECAY_RATE      = 0.01
+
+              ZONE_LABELS = {
+                (0.85..)     => :mastered,
+                (0.3...0.85) => :zpd,
+                (..0.3)      => :beyond_reach
+              }.freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/learning/scaffolding/helpers/scaffold.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Scaffolding
+          module Helpers
+            class Scaffold
+              include Constants
+
+              attr_reader :id, :skill_name, :domain, :competence, :support_level,
+                          :task_history, :practice_count, :created_at, :last_practiced_at
+
+              def initialize(skill_name:, domain:, competence: DEFAULT_COMPETENCE)
+                @id               = SecureRandom.uuid
+                @skill_name       = skill_name
+                @domain           = domain
+                @competence       = competence.to_f.clamp(COMPETENCE_FLOOR, COMPETENCE_CEILING)
+                @support_level    = initial_support_level
+                @task_history     = []
+                @practice_count   = 0
+                @created_at       = Time.now.utc
+                @last_practiced_at = nil
+              end
+
+              def attempt_task(difficulty:, success:)
+                diff = difficulty.to_f.clamp(COMPETENCE_FLOOR, COMPETENCE_CEILING)
+                delta = compute_delta(difficulty: diff, success: success)
+                @competence = (@competence + delta).clamp(COMPETENCE_FLOOR, COMPETENCE_CEILING)
+                @practice_count   += 1
+                @last_practiced_at = Time.now.utc
+
+                record_task(difficulty: diff, success: success)
+                adjust_support(success)
+                @competence
+              end
+
+              def current_zone
+                ZONE_LABELS.each do |range, label|
+                  return label if range.cover?(@competence)
+                end
+                :beyond_reach
+              end
+
+              def recommended_difficulty
+                (@competence + ((ZPD_UPPER - @competence) * 0.5)).clamp(COMPETENCE_FLOOR, COMPETENCE_CEILING)
+              end
+
+              def fade_support!
+                idx = SUPPORT_LEVELS.index(@support_level) || 0
+                return if idx >= SUPPORT_LEVELS.size - 1
+
+                @support_level = SUPPORT_LEVELS[idx + 1]
+              end
+
+              def increase_support!
+                idx = SUPPORT_LEVELS.index(@support_level) || (SUPPORT_LEVELS.size - 1)
+                return if idx <= 0
+
+                @support_level = SUPPORT_LEVELS[idx - 1]
+              end
+
+              def mastered?
+                @competence >= MASTERY_THRESHOLD
+              end
+
+              def in_zpd?
+                @competence >= ZPD_LOWER && @competence < ZPD_UPPER
+              end
+
+              def to_h
+                {
+                  id:                @id,
+                  skill_name:        @skill_name,
+                  domain:            @domain,
+                  competence:        @competence.round(4),
+                  support_level:     @support_level,
+                  current_zone:      current_zone,
+                  practice_count:    @practice_count,
+                  mastered:          mastered?,
+                  in_zpd:            in_zpd?,
+                  created_at:        @created_at,
+                  last_practiced_at: @last_practiced_at,
+                  task_history_size: @task_history.size
+                }
+              end
+
+              private
+
+              def compute_delta(difficulty:, success:)
+                if success
+                  in_active_zpd = difficulty >= ZPD_LOWER && difficulty < ZPD_UPPER
+                  in_active_zpd ? LEARNING_GAIN : LEARNING_GAIN / 2.0
+                else
+                  -FAILURE_SETBACK
+                end
+              end
+
+              def adjust_support(success)
+                if success
+                  fade_support!
+                else
+                  increase_support!
+                end
+              end
+
+              def initial_support_level
+                if @competence >= ZPD_UPPER
+                  :independent
+                elsif @competence >= ZPD_LOWER
+                  :prompted
+                else
+                  :full
+                end
+              end
+
+              def record_task(difficulty:, success:)
+                @task_history << {
+                  task_id:    SecureRandom.uuid,
+                  difficulty: difficulty,
+                  success:    success,
+                  support:    @support_level,
+                  at:         Time.now.utc
+                }
+                @task_history.shift while @task_history.size > MAX_HISTORY
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/learning/scaffolding/helpers/scaffolding_engine.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Scaffolding
+          module Helpers
+            class ScaffoldingEngine
+              include Constants
+
+              attr_reader :scaffolds
+
+              def initialize
+                @scaffolds = {}
+              end
+
+              def create_scaffold(skill_name:, domain:, competence: nil)
+                trim_scaffolds if @scaffolds.size >= MAX_SCAFFOLDS
+                comp = competence.nil? ? DEFAULT_COMPETENCE : competence
+                scaffold = Scaffold.new(skill_name: skill_name, domain: domain, competence: comp)
+                @scaffolds[scaffold.id] = scaffold
+                scaffold
+              end
+
+              def attempt_scaffolded_task(scaffold_id:, difficulty:, success:)
+                scaffold = find(scaffold_id)
+                return nil unless scaffold
+
+                scaffold.attempt_task(difficulty: difficulty, success: success)
+                scaffold
+              end
+
+              def recommend_task(scaffold_id:)
+                scaffold = find(scaffold_id)
+                return nil unless scaffold
+
+                {
+                  difficulty:    scaffold.recommended_difficulty,
+                  support_level: scaffold.support_level,
+                  zone:          scaffold.current_zone
+                }
+              end
+
+              def mastered_skills
+                @scaffolds.values.select(&:mastered?)
+              end
+
+              def zpd_skills
+                @scaffolds.values.select(&:in_zpd?)
+              end
+
+              def by_domain(domain:)
+                @scaffolds.values.select { |s| s.domain == domain }
+              end
+
+              def adjust_support(scaffold_id:, direction:)
+                scaffold = find(scaffold_id)
+                return nil unless scaffold
+
+                case direction
+                when :increase then scaffold.increase_support!
+                when :decrease then scaffold.fade_support!
+                end
+
+                scaffold
+              end
+
+              def overall_competence
+                return DEFAULT_COMPETENCE if @scaffolds.empty?
+
+                @scaffolds.values.sum(&:competence) / @scaffolds.size
+              end
+
+              def decay_all
+                @scaffolds.each_value do |scaffold|
+                  next if scaffold.mastered?
+
+                  decayed = (scaffold.competence - DECAY_RATE).clamp(COMPETENCE_FLOOR, COMPETENCE_CEILING)
+                  scaffold.instance_variable_set(:@competence, decayed)
+                end
+                @scaffolds.size
+              end
+
+              def to_h
+                {
+                  total_scaffolds:    @scaffolds.size,
+                  mastered_count:     mastered_skills.size,
+                  zpd_count:          zpd_skills.size,
+                  overall_competence: overall_competence.round(4)
+                }
+              end
+
+              private
+
+              def find(scaffold_id)
+                @scaffolds[scaffold_id]
+              end
+
+              def trim_scaffolds
+                mastered = mastered_skills.sort_by(&:last_practiced_at)
+                candidates = mastered.any? ? mastered : @scaffolds.values.sort_by(&:last_practiced_at)
+                remove = candidates.first
+                @scaffolds.delete(remove.id) if remove
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/learning/scaffolding/runners/cognitive_scaffolding.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Scaffolding
+          module Runners
+            module CognitiveScaffolding
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def create_scaffold(skill_name:, domain:, competence: nil, **)
+                comp = competence || Helpers::Constants::DEFAULT_COMPETENCE
+                scaffold = engine.create_scaffold(skill_name: skill_name, domain: domain, competence: comp)
+                Legion::Logging.debug "[cognitive_scaffolding] created: skill=#{skill_name} domain=#{domain} " \
+                                      "competence=#{scaffold.competence.round(2)} zone=#{scaffold.current_zone}"
+                { success: true, scaffold: scaffold.to_h }
+              end
+
+              def attempt_scaffolded_task(scaffold_id:, difficulty:, success:, **)
+                scaffold = engine.attempt_scaffolded_task(scaffold_id: scaffold_id, difficulty: difficulty, success: success)
+                unless scaffold
+                  Legion::Logging.debug "[cognitive_scaffolding] attempt: scaffold_id=#{scaffold_id} not found"
+                  return { success: false, reason: :not_found, scaffold_id: scaffold_id }
+                end
+
+                Legion::Logging.debug "[cognitive_scaffolding] attempt: skill=#{scaffold.skill_name} " \
+                                      "difficulty=#{difficulty.round(2)} success=#{success} " \
+                                      "competence=#{scaffold.competence.round(2)} zone=#{scaffold.current_zone}"
+                { success: true, scaffold: scaffold.to_h }
+              end
+
+              def recommend_scaffolded_task(scaffold_id:, **)
+                recommendation = engine.recommend_task(scaffold_id: scaffold_id)
+                unless recommendation
+                  Legion::Logging.debug "[cognitive_scaffolding] recommend: scaffold_id=#{scaffold_id} not found"
+                  return { success: false, reason: :not_found, scaffold_id: scaffold_id }
+                end
+
+                Legion::Logging.debug "[cognitive_scaffolding] recommend: difficulty=#{recommendation[:difficulty].round(2)} " \
+                                      "support=#{recommendation[:support_level]} zone=#{recommendation[:zone]}"
+                { success: true, recommendation: recommendation }
+              end
+
+              def mastered_scaffolded_skills(**)
+                skills = engine.mastered_skills
+                Legion::Logging.debug "[cognitive_scaffolding] mastered: count=#{skills.size}"
+                { success: true, skills: skills.map(&:to_h), count: skills.size }
+              end
+
+              def zpd_skills(**)
+                skills = engine.zpd_skills
+                Legion::Logging.debug "[cognitive_scaffolding] zpd: count=#{skills.size}"
+                { success: true, skills: skills.map(&:to_h), count: skills.size }
+              end
+
+              def domain_scaffolds(domain:, **)
+                scaffolds = engine.by_domain(domain: domain)
+                Legion::Logging.debug "[cognitive_scaffolding] domain: domain=#{domain} count=#{scaffolds.size}"
+                { success: true, domain: domain, scaffolds: scaffolds.map(&:to_h), count: scaffolds.size }
+              end
+
+              def adjust_scaffold_support(scaffold_id:, direction:, **)
+                scaffold = engine.adjust_support(scaffold_id: scaffold_id, direction: direction)
+                unless scaffold
+                  Legion::Logging.debug "[cognitive_scaffolding] adjust_support: scaffold_id=#{scaffold_id} not found"
+                  return { success: false, reason: :not_found, scaffold_id: scaffold_id }
+                end
+
+                Legion::Logging.debug "[cognitive_scaffolding] adjust_support: skill=#{scaffold.skill_name} " \
+                                      "direction=#{direction} support=#{scaffold.support_level}"
+                { success: true, scaffold: scaffold.to_h }
+              end
+
+              def overall_scaffolded_competence(**)
+                overall = engine.overall_competence
+                Legion::Logging.debug "[cognitive_scaffolding] overall_competence: #{overall.round(3)}"
+                { success: true, overall_competence: overall.round(4) }
+              end
+
+              def update_cognitive_scaffolding(**)
+                count = engine.decay_all
+                overall = engine.overall_competence
+                Legion::Logging.debug "[cognitive_scaffolding] decay: scaffolds=#{count} overall=#{overall.round(3)}"
+                { success: true, action: :decay, scaffold_count: count, overall_competence: overall.round(4) }
+              end
+
+              def cognitive_scaffolding_stats(**)
+                stats = engine.to_h
+                Legion::Logging.debug "[cognitive_scaffolding] stats: total=#{stats[:total_scaffolds]} " \
+                                      "mastered=#{stats[:mastered_count]} zpd=#{stats[:zpd_count]}"
+                { success: true, stats: stats }
+              end
+
+              private
+
+              def engine
+                @engine ||= Helpers::ScaffoldingEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/learning/scaffolding/version'
+require 'legion/extensions/agentic/learning/scaffolding/helpers/constants'
+require 'legion/extensions/agentic/learning/scaffolding/helpers/scaffold'
+require 'legion/extensions/agentic/learning/scaffolding/helpers/scaffolding_engine'
+require 'legion/extensions/agentic/learning/scaffolding/runners/cognitive_scaffolding'
+require 'legion/extensions/agentic/learning/scaffolding/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Scaffolding
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'learning/version'
+require_relative 'learning/plasticity'
+require_relative 'learning/scaffolding'
+require_relative 'learning/fermentation'
+require_relative 'learning/chrysalis'
+require_relative 'learning/catalyst'
+require_relative 'learning/curiosity'
+require_relative 'learning/epistemic_curiosity'
+require_relative 'learning/habit'
+require_relative 'learning/hebbian'
+require_relative 'learning/learning_rate'
+require_relative 'learning/meta_learning'
+require_relative 'learning/preference_learning'
+require_relative 'learning/procedural'
+require_relative 'learning/anchoring'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+
+        def remote_invocable?
+          false
+        end
+      end
+    end
+  end
+end

data/spec/legion/extensions/agentic/learning/anchoring/client_spec.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/learning/anchoring/client'
+
+RSpec.describe Legion::Extensions::Agentic::Learning::Anchoring::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to all runner methods' do
+    expect(client).to respond_to(:record_anchor)
+    expect(client).to respond_to(:evaluate_estimate)
+    expect(client).to respond_to(:reference_frame)
+    expect(client).to respond_to(:de_anchor)
+    expect(client).to respond_to(:shift_reference)
+    expect(client).to respond_to(:update_anchoring)
+    expect(client).to respond_to(:domain_anchors)
+    expect(client).to respond_to(:anchoring_stats)
+  end
+
+  it 'exposes anchor_store' do
+    expect(client.anchor_store).to be_a(Legion::Extensions::Agentic::Learning::Anchoring::Helpers::AnchorStore)
+  end
+
+  it 'accepts an external anchor_store' do
+    custom_store = Legion::Extensions::Agentic::Learning::Anchoring::Helpers::AnchorStore.new
+    c = described_class.new(anchor_store: custom_store)
+    expect(c.anchor_store).to be(custom_store)
+  end
+
+  it 'accepts keyword splat arguments' do
+    expect { described_class.new(extra: :ignored) }.not_to raise_error
+  end
+end