lex-cognitive-apprenticeship 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9e2a7e552bc6b9ab40bf5ba2a02975c5a3306774558ab7e80e517167d058a5f8
+  data.tar.gz: 5f3bb14640b7ac611036ef4b0578abf03eb28d6521168ce5a44ac8523399f5db
+SHA512:
+  metadata.gz: 8fc0cb1baaddd2da7583f48156ab5571bd04391a52802de11ab003866d731ad00e96ad8f5ecb05c48738846a01639acc268881fc294b2e5c44ed9c8dbfc03a9f
+  data.tar.gz: 4d2162f1c7269d7dcccb302f6fad5a157ab7c3d0ee58144703487eb1f7f26f2446893593ebc0674847a500a033272871ea1a4a7b08852475debba295c62b745c

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-cognitive-apprenticeship.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_apprenticeship/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-apprenticeship'
+  spec.version       = Legion::Extensions::CognitiveApprenticeship::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Cognitive Apprenticeship'
+  spec.description   = "Collins' Cognitive Apprenticeship model for brain-modeled agentic AI: " \
+                       'guided learning through modeling, coaching, scaffolding, articulation, reflection, and exploration'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-apprenticeship'
+  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-cognitive-apprenticeship'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-cognitive-apprenticeship'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-cognitive-apprenticeship'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-cognitive-apprenticeship/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-cognitive-apprenticeship.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_apprenticeship/helpers/apprenticeship_model'
+require 'legion/extensions/cognitive_apprenticeship/helpers/apprenticeship'
+require 'legion/extensions/cognitive_apprenticeship/helpers/apprenticeship_engine'
+require 'legion/extensions/cognitive_apprenticeship/runners/cognitive_apprenticeship'
+
+module Legion
+  module Extensions
+    module CognitiveApprenticeship
+      class Client
+        include Runners::CognitiveApprenticeship
+
+        def initialize(**)
+          @engine = Helpers::ApprenticeshipEngine.new
+        end
+
+        private
+
+        attr_reader :engine
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_apprenticeship/helpers/apprenticeship.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveApprenticeship
+      module Helpers
+        class Apprenticeship
+          include ApprenticeshipModel
+
+          attr_reader :id, :skill_name, :domain, :mentor_id, :apprentice_id,
+                      :mastery, :session_count, :created_at, :last_session_at
+
+          def initialize(skill_name:, domain:, mentor_id:, apprentice_id:)
+            data = ApprenticeshipModel.new_apprenticeship(
+              skill_name:    skill_name,
+              domain:        domain,
+              mentor_id:     mentor_id,
+              apprentice_id: apprentice_id
+            )
+            @id              = data[:id]
+            @skill_name      = data[:skill_name]
+            @domain          = data[:domain]
+            @mentor_id       = data[:mentor_id]
+            @apprentice_id   = data[:apprentice_id]
+            @mastery         = data[:mastery]
+            @session_count   = data[:session_count]
+            @created_at      = data[:created_at]
+            @last_session_at = data[:last_session_at]
+          end
+
+          def current_phase
+            ApprenticeshipModel.phase_for(@mastery)
+          end
+
+          def mastery_label
+            ApprenticeshipModel.mastery_label_for(@mastery)
+          end
+
+          def graduated?
+            @mastery >= ApprenticeshipModel::MASTERY_THRESHOLD
+          end
+
+          def recommended_method
+            ApprenticeshipModel.phase_for(@mastery)
+          end
+
+          def learn!(method:, success:)
+            multiplier = case method
+                         when :exploration then ApprenticeshipModel::EXPLORATION_MULTIPLIER
+                         when :coaching    then ApprenticeshipModel::COACHING_MULTIPLIER
+                         else 1.0
+                         end
+
+            gain = success ? ApprenticeshipModel::LEARNING_GAIN * multiplier : 0.0
+            @mastery = ApprenticeshipModel.clamp_mastery(@mastery + gain)
+            @session_count += 1
+            @last_session_at = Time.now.utc
+            self
+          end
+
+          def decay!
+            @mastery = ApprenticeshipModel.clamp_mastery(@mastery - ApprenticeshipModel::DECAY_RATE)
+            self
+          end
+
+          def to_h
+            {
+              id:              @id,
+              skill_name:      @skill_name,
+              domain:          @domain,
+              mentor_id:       @mentor_id,
+              apprentice_id:   @apprentice_id,
+              mastery:         @mastery,
+              current_phase:   current_phase,
+              mastery_label:   mastery_label,
+              graduated:       graduated?,
+              session_count:   @session_count,
+              created_at:      @created_at,
+              last_session_at: @last_session_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_apprenticeship/helpers/apprenticeship_engine.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveApprenticeship
+      module Helpers
+        class ApprenticeshipEngine
+          def initialize
+            @apprenticeships = {}
+            @sessions        = []
+          end
+
+          def create_apprenticeship(skill_name:, domain:, mentor_id:, apprentice_id:)
+            return nil if @apprenticeships.size >= ApprenticeshipModel::MAX_APPRENTICESHIPS
+
+            appr = Apprenticeship.new(
+              skill_name:    skill_name,
+              domain:        domain,
+              mentor_id:     mentor_id,
+              apprentice_id: apprentice_id
+            )
+            @apprenticeships[appr.id] = appr
+            appr
+          end
+
+          def conduct_session(apprenticeship_id:, method:, success:)
+            appr = @apprenticeships[apprenticeship_id]
+            return nil unless appr
+
+            appr.learn!(method: method, success: success)
+            record_session(apprenticeship_id: apprenticeship_id, method: method, success: success)
+            appr
+          end
+
+          def recommend_method(apprenticeship_id:)
+            appr = @apprenticeships[apprenticeship_id]
+            return nil unless appr
+
+            appr.recommended_method
+          end
+
+          def graduated_apprenticeships
+            @apprenticeships.values.select(&:graduated?)
+          end
+
+          def active_apprenticeships
+            @apprenticeships.values.reject(&:graduated?)
+          end
+
+          def by_mentor(mentor_id:)
+            @apprenticeships.values.select { |a| a.mentor_id == mentor_id }
+          end
+
+          def by_apprentice(apprentice_id:)
+            @apprenticeships.values.select { |a| a.apprentice_id == apprentice_id }
+          end
+
+          def by_domain(domain:)
+            @apprenticeships.values.select { |a| a.domain == domain }
+          end
+
+          def decay_all
+            @apprenticeships.each_value(&:decay!)
+            @apprenticeships.size
+          end
+
+          def get(apprenticeship_id)
+            @apprenticeships[apprenticeship_id]
+          end
+
+          def count
+            @apprenticeships.size
+          end
+
+          def sessions
+            @sessions.dup
+          end
+
+          def to_h
+            {
+              total:     @apprenticeships.size,
+              active:    active_apprenticeships.size,
+              graduated: graduated_apprenticeships.size,
+              sessions:  @sessions.size
+            }
+          end
+
+          private
+
+          def record_session(apprenticeship_id:, method:, success:)
+            return if @sessions.size >= ApprenticeshipModel::MAX_SESSIONS
+
+            @sessions << {
+              apprenticeship_id: apprenticeship_id,
+              method:            method,
+              success:           success,
+              recorded_at:       Time.now.utc
+            }
+            @sessions.shift while @sessions.size > ApprenticeshipModel::MAX_HISTORY
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_apprenticeship/helpers/apprenticeship_model.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveApprenticeship
+      module Helpers
+        module ApprenticeshipModel
+          # Capacity limits
+          MAX_APPRENTICESHIPS = 100
+          MAX_SESSIONS        = 500
+          MAX_HISTORY         = 300
+
+          # Mastery defaults and bounds
+          DEFAULT_MASTERY  = 0.1
+          MASTERY_FLOOR    = 0.0
+          MASTERY_CEILING  = 1.0
+          MASTERY_THRESHOLD = 0.85
+          PHASE_THRESHOLD   = 0.5
+
+          # Learning dynamics
+          LEARNING_GAIN            = 0.08
+          COACHING_MULTIPLIER      = 1.5
+          EXPLORATION_MULTIPLIER   = 2.0
+          DECAY_RATE               = 0.01
+
+          # Collins' six instructional methods
+          METHODS = %i[modeling coaching scaffolding articulation reflection exploration].freeze
+
+          # Phase labels derived from mastery range
+          PHASE_LABELS = {
+            (0.0...0.2)   => :modeling,
+            (0.2...0.4)   => :coaching,
+            (0.4...0.6)   => :scaffolding,
+            (0.6...0.75)  => :articulation,
+            (0.75...0.85) => :reflection,
+            (0.85..1.0)   => :exploration
+          }.freeze
+
+          # Mastery level labels
+          MASTERY_LABELS = {
+            (0.8..)     => :expert,
+            (0.6...0.8) => :proficient,
+            (0.4...0.6) => :intermediate,
+            (0.2...0.4) => :apprentice,
+            (..0.2)     => :novice
+          }.freeze
+
+          module_function
+
+          def phase_for(mastery)
+            PHASE_LABELS.each do |range, phase|
+              return phase if range.cover?(mastery)
+            end
+            :exploration
+          end
+
+          def mastery_label_for(mastery)
+            MASTERY_LABELS.each do |range, label|
+              return label if range.cover?(mastery)
+            end
+            :expert
+          end
+
+          def clamp_mastery(value)
+            value.clamp(MASTERY_FLOOR, MASTERY_CEILING)
+          end
+
+          def new_apprenticeship(skill_name:, domain:, mentor_id:, apprentice_id:)
+            now = Time.now.utc
+            {
+              id:              SecureRandom.uuid,
+              skill_name:      skill_name,
+              domain:          domain,
+              mentor_id:       mentor_id,
+              apprentice_id:   apprentice_id,
+              mastery:         DEFAULT_MASTERY,
+              current_phase:   phase_for(DEFAULT_MASTERY),
+              session_count:   0,
+              created_at:      now,
+              last_session_at: nil
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveApprenticeship
+      module Runners
+        module CognitiveApprenticeship
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def create_apprenticeship(skill_name:, domain:, mentor_id:, apprentice_id:, **)
+            return { success: false, reason: :param_too_short } if [skill_name, domain, mentor_id, apprentice_id].any? { |p| p.to_s.length < 3 }
+
+            appr = engine.create_apprenticeship(
+              skill_name:    skill_name,
+              domain:        domain,
+              mentor_id:     mentor_id,
+              apprentice_id: apprentice_id
+            )
+
+            if appr
+              Legion::Logging.info "[cognitive_apprenticeship] created id=#{appr.id} skill=#{skill_name} domain=#{domain}"
+              { success: true, apprenticeship: appr.to_h }
+            else
+              Legion::Logging.warn '[cognitive_apprenticeship] create failed: capacity reached'
+              { success: false, reason: :capacity_reached }
+            end
+          end
+
+          def conduct_apprenticeship_session(apprenticeship_id:, method:, success:, **)
+            return { success: false, reason: :invalid_method } unless Helpers::ApprenticeshipModel::METHODS.include?(method.to_sym)
+
+            appr = engine.conduct_session(
+              apprenticeship_id: apprenticeship_id,
+              method:            method.to_sym,
+              success:           success
+            )
+
+            if appr
+              Legion::Logging.debug "[cognitive_apprenticeship] session id=#{apprenticeship_id} method=#{method} " \
+                                    "success=#{success} mastery=#{appr.mastery.round(3)}"
+              { success: true, apprenticeship: appr.to_h }
+            else
+              { success: false, reason: :not_found }
+            end
+          end
+
+          def recommend_apprenticeship_method(apprenticeship_id:, **)
+            method = engine.recommend_method(apprenticeship_id: apprenticeship_id)
+
+            if method
+              Legion::Logging.debug "[cognitive_apprenticeship] recommend id=#{apprenticeship_id} method=#{method}"
+              { success: true, apprenticeship_id: apprenticeship_id, recommended_method: method }
+            else
+              { success: false, reason: :not_found }
+            end
+          end
+
+          def graduated_apprenticeships(**)
+            list = engine.graduated_apprenticeships
+            Legion::Logging.debug "[cognitive_apprenticeship] graduated count=#{list.size}"
+            { success: true, apprenticeships: list.map(&:to_h), count: list.size }
+          end
+
+          def active_apprenticeships(**)
+            list = engine.active_apprenticeships
+            Legion::Logging.debug "[cognitive_apprenticeship] active count=#{list.size}"
+            { success: true, apprenticeships: list.map(&:to_h), count: list.size }
+          end
+
+          def mentor_apprenticeships(mentor_id:, **)
+            list = engine.by_mentor(mentor_id: mentor_id)
+            Legion::Logging.debug "[cognitive_apprenticeship] mentor=#{mentor_id} count=#{list.size}"
+            { success: true, mentor_id: mentor_id, apprenticeships: list.map(&:to_h), count: list.size }
+          end
+
+          def apprentice_apprenticeships(apprentice_id:, **)
+            list = engine.by_apprentice(apprentice_id: apprentice_id)
+            Legion::Logging.debug "[cognitive_apprenticeship] apprentice=#{apprentice_id} count=#{list.size}"
+            { success: true, apprentice_id: apprentice_id, apprenticeships: list.map(&:to_h), count: list.size }
+          end
+
+          def domain_apprenticeships(domain:, **)
+            list = engine.by_domain(domain: domain)
+            Legion::Logging.debug "[cognitive_apprenticeship] domain=#{domain} count=#{list.size}"
+            { success: true, domain: domain, apprenticeships: list.map(&:to_h), count: list.size }
+          end
+
+          def update_cognitive_apprenticeship(apprenticeship_id:, method:, success:, **)
+            conduct_apprenticeship_session(apprenticeship_id: apprenticeship_id, method: method, success: success)
+          end
+
+          def cognitive_apprenticeship_stats(**)
+            stats = engine.to_h
+            Legion::Logging.debug "[cognitive_apprenticeship] stats=#{stats.inspect}"
+            { success: true }.merge(stats)
+          end
+
+          private
+
+          def engine
+            @engine ||= Helpers::ApprenticeshipEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_apprenticeship.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_apprenticeship/version'
+require 'legion/extensions/cognitive_apprenticeship/helpers/apprenticeship_model'
+require 'legion/extensions/cognitive_apprenticeship/helpers/apprenticeship'
+require 'legion/extensions/cognitive_apprenticeship/helpers/apprenticeship_engine'
+require 'legion/extensions/cognitive_apprenticeship/runners/cognitive_apprenticeship'
+
+module Legion
+  module Extensions
+    module CognitiveApprenticeship
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_apprenticeship/client'
+
+RSpec.describe Legion::Extensions::CognitiveApprenticeship::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to all runner methods' do
+    expect(client).to respond_to(:create_apprenticeship)
+    expect(client).to respond_to(:conduct_apprenticeship_session)
+    expect(client).to respond_to(:recommend_apprenticeship_method)
+    expect(client).to respond_to(:graduated_apprenticeships)
+    expect(client).to respond_to(:active_apprenticeships)
+    expect(client).to respond_to(:mentor_apprenticeships)
+    expect(client).to respond_to(:apprentice_apprenticeships)
+    expect(client).to respond_to(:domain_apprenticeships)
+    expect(client).to respond_to(:update_cognitive_apprenticeship)
+    expect(client).to respond_to(:cognitive_apprenticeship_stats)
+  end
+end

data/spec/legion/extensions/cognitive_apprenticeship/helpers/apprenticeship_engine_spec.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveApprenticeship::Helpers::ApprenticeshipEngine do
+  let(:engine) { described_class.new }
+
+  let(:params) do
+    {
+      skill_name:    'terraform',
+      domain:        'infrastructure',
+      mentor_id:     'mentor-1',
+      apprentice_id: 'learner-1'
+    }
+  end
+
+  def create_one
+    engine.create_apprenticeship(**params)
+  end
+
+  describe '#create_apprenticeship' do
+    it 'returns a new Apprenticeship' do
+      appr = create_one
+      expect(appr).to be_a(Legion::Extensions::CognitiveApprenticeship::Helpers::Apprenticeship)
+    end
+
+    it 'stores the apprenticeship' do
+      appr = create_one
+      expect(engine.get(appr.id)).to eq(appr)
+    end
+
+    it 'increments count' do
+      expect { create_one }.to change(engine, :count).by(1)
+    end
+
+    it 'returns nil at capacity' do
+      stub_const('Legion::Extensions::CognitiveApprenticeship::Helpers::ApprenticeshipModel::MAX_APPRENTICESHIPS', 1)
+      create_one
+      expect(engine.create_apprenticeship(**params)).to be_nil
+    end
+  end
+
+  describe '#conduct_session' do
+    it 'returns the apprenticeship after learning' do
+      appr = create_one
+      result = engine.conduct_session(apprenticeship_id: appr.id, method: :modeling, success: true)
+      expect(result).to eq(appr)
+    end
+
+    it 'returns nil for unknown id' do
+      expect(engine.conduct_session(apprenticeship_id: 'nope', method: :modeling, success: true)).to be_nil
+    end
+
+    it 'records the session' do
+      appr = create_one
+      engine.conduct_session(apprenticeship_id: appr.id, method: :coaching, success: true)
+      expect(engine.sessions.size).to eq(1)
+    end
+  end
+
+  describe '#recommend_method' do
+    it 'returns the recommended method' do
+      appr = create_one
+      method = engine.recommend_method(apprenticeship_id: appr.id)
+      expect(Legion::Extensions::CognitiveApprenticeship::Helpers::ApprenticeshipModel::METHODS).to include(method)
+    end
+
+    it 'returns nil for unknown id' do
+      expect(engine.recommend_method(apprenticeship_id: 'nope')).to be_nil
+    end
+  end
+
+  describe '#graduated_apprenticeships' do
+    it 'returns apprenticeships that have graduated' do
+      appr = create_one
+      30.times { engine.conduct_session(apprenticeship_id: appr.id, method: :exploration, success: true) }
+      expect(engine.graduated_apprenticeships).to include(appr)
+    end
+
+    it 'excludes non-graduated apprenticeships' do
+      create_one
+      expect(engine.graduated_apprenticeships).to be_empty
+    end
+  end
+
+  describe '#active_apprenticeships' do
+    it 'returns non-graduated apprenticeships' do
+      create_one
+      expect(engine.active_apprenticeships.size).to eq(1)
+    end
+
+    it 'excludes graduated apprenticeships' do
+      appr = create_one
+      30.times { engine.conduct_session(apprenticeship_id: appr.id, method: :exploration, success: true) }
+      expect(engine.active_apprenticeships).to be_empty
+    end
+  end
+
+  describe '#by_mentor' do
+    it 'returns apprenticeships for the given mentor' do
+      create_one
+      result = engine.by_mentor(mentor_id: 'mentor-1')
+      expect(result.size).to eq(1)
+    end
+
+    it 'returns empty for unknown mentor' do
+      create_one
+      expect(engine.by_mentor(mentor_id: 'nobody')).to be_empty
+    end
+  end
+
+  describe '#by_apprentice' do
+    it 'returns apprenticeships for the given apprentice' do
+      create_one
+      result = engine.by_apprentice(apprentice_id: 'learner-1')
+      expect(result.size).to eq(1)
+    end
+  end
+
+  describe '#by_domain' do
+    it 'returns apprenticeships in the given domain' do
+      create_one
+      result = engine.by_domain(domain: 'infrastructure')
+      expect(result.size).to eq(1)
+    end
+
+    it 'returns empty for unknown domain' do
+      create_one
+      expect(engine.by_domain(domain: 'unknown')).to be_empty
+    end
+  end
+
+  describe '#decay_all' do
+    it 'applies decay to all apprenticeships and returns count' do
+      create_one
+      expect(engine.decay_all).to eq(1)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a summary hash' do
+      create_one
+      h = engine.to_h
+      expect(h).to include(:total, :active, :graduated, :sessions)
+      expect(h[:total]).to eq(1)
+    end
+  end
+end

data/spec/legion/extensions/cognitive_apprenticeship/helpers/apprenticeship_model_spec.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveApprenticeship::Helpers::ApprenticeshipModel do
+  subject(:model) { described_class }
+
+  describe 'constants' do
+    it 'defines METHODS with six items' do
+      expect(model::METHODS.size).to eq(6)
+      expect(model::METHODS).to include(:modeling, :coaching, :scaffolding, :articulation, :reflection, :exploration)
+    end
+
+    it 'defines MASTERY_THRESHOLD as 0.85' do
+      expect(model::MASTERY_THRESHOLD).to eq(0.85)
+    end
+
+    it 'defines LEARNING_GAIN as 0.08' do
+      expect(model::LEARNING_GAIN).to eq(0.08)
+    end
+
+    it 'defines EXPLORATION_MULTIPLIER as 2.0' do
+      expect(model::EXPLORATION_MULTIPLIER).to eq(2.0)
+    end
+
+    it 'defines COACHING_MULTIPLIER as 1.5' do
+      expect(model::COACHING_MULTIPLIER).to eq(1.5)
+    end
+
+    it 'defines DECAY_RATE as 0.01' do
+      expect(model::DECAY_RATE).to eq(0.01)
+    end
+  end
+
+  describe '.phase_for' do
+    it 'returns :modeling for mastery 0.0..0.19' do
+      expect(model.phase_for(0.0)).to eq(:modeling)
+      expect(model.phase_for(0.1)).to eq(:modeling)
+    end
+
+    it 'returns :coaching for mastery 0.2..0.39' do
+      expect(model.phase_for(0.2)).to eq(:coaching)
+      expect(model.phase_for(0.3)).to eq(:coaching)
+    end
+
+    it 'returns :scaffolding for mastery 0.4..0.59' do
+      expect(model.phase_for(0.4)).to eq(:scaffolding)
+    end
+
+    it 'returns :articulation for mastery 0.6..0.74' do
+      expect(model.phase_for(0.6)).to eq(:articulation)
+    end
+
+    it 'returns :reflection for mastery 0.75..0.84' do
+      expect(model.phase_for(0.75)).to eq(:reflection)
+    end
+
+    it 'returns :exploration for mastery >= 0.85' do
+      expect(model.phase_for(0.85)).to eq(:exploration)
+      expect(model.phase_for(1.0)).to eq(:exploration)
+    end
+  end
+
+  describe '.mastery_label_for' do
+    it 'returns :novice for mastery < 0.2' do
+      expect(model.mastery_label_for(0.1)).to eq(:novice)
+    end
+
+    it 'returns :apprentice for mastery 0.2..0.39' do
+      expect(model.mastery_label_for(0.3)).to eq(:apprentice)
+    end
+
+    it 'returns :intermediate for mastery 0.4..0.59' do
+      expect(model.mastery_label_for(0.5)).to eq(:intermediate)
+    end
+
+    it 'returns :proficient for mastery 0.6..0.79' do
+      expect(model.mastery_label_for(0.7)).to eq(:proficient)
+    end
+
+    it 'returns :expert for mastery >= 0.8' do
+      expect(model.mastery_label_for(0.9)).to eq(:expert)
+    end
+  end
+
+  describe '.clamp_mastery' do
+    it 'floors at MASTERY_FLOOR' do
+      expect(model.clamp_mastery(-0.5)).to eq(0.0)
+    end
+
+    it 'caps at MASTERY_CEILING' do
+      expect(model.clamp_mastery(1.5)).to eq(1.0)
+    end
+
+    it 'passes through valid values' do
+      expect(model.clamp_mastery(0.5)).to eq(0.5)
+    end
+  end
+
+  describe '.new_apprenticeship' do
+    let(:entry) do
+      model.new_apprenticeship(
+        skill_name:    'ruby',
+        domain:        'programming',
+        mentor_id:     'mentor-1',
+        apprentice_id: 'apprentice-1'
+      )
+    end
+
+    it 'sets default mastery' do
+      expect(entry[:mastery]).to eq(model::DEFAULT_MASTERY)
+    end
+
+    it 'sets current_phase from mastery' do
+      expect(entry[:current_phase]).to eq(model.phase_for(model::DEFAULT_MASTERY))
+    end
+
+    it 'generates a uuid id' do
+      expect(entry[:id]).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets session_count to 0' do
+      expect(entry[:session_count]).to eq(0)
+    end
+  end
+end

data/spec/legion/extensions/cognitive_apprenticeship/helpers/apprenticeship_spec.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveApprenticeship::Helpers::Apprenticeship do
+  let(:appr) do
+    described_class.new(
+      skill_name:    'ruby',
+      domain:        'programming',
+      mentor_id:     'mentor-1',
+      apprentice_id: 'apprentice-1'
+    )
+  end
+
+  describe '#initialize' do
+    it 'sets skill_name' do
+      expect(appr.skill_name).to eq('ruby')
+    end
+
+    it 'sets domain' do
+      expect(appr.domain).to eq('programming')
+    end
+
+    it 'starts at DEFAULT_MASTERY' do
+      expect(appr.mastery).to eq(Legion::Extensions::CognitiveApprenticeship::Helpers::ApprenticeshipModel::DEFAULT_MASTERY)
+    end
+
+    it 'starts with zero sessions' do
+      expect(appr.session_count).to eq(0)
+    end
+
+    it 'generates a uuid' do
+      expect(appr.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+  end
+
+  describe '#current_phase' do
+    it 'returns :modeling at default mastery' do
+      expect(appr.current_phase).to eq(:modeling)
+    end
+  end
+
+  describe '#mastery_label' do
+    it 'returns :novice at default mastery' do
+      expect(appr.mastery_label).to eq(:novice)
+    end
+  end
+
+  describe '#graduated?' do
+    it 'returns false below threshold' do
+      expect(appr.graduated?).to be false
+    end
+
+    it 'returns true at threshold' do
+      30.times { appr.learn!(method: :exploration, success: true) }
+      expect(appr.graduated?).to be true
+    end
+  end
+
+  describe '#recommended_method' do
+    it 'returns :modeling at default mastery' do
+      expect(appr.recommended_method).to eq(:modeling)
+    end
+  end
+
+  describe '#learn!' do
+    it 'increases mastery on success' do
+      before = appr.mastery
+      appr.learn!(method: :modeling, success: true)
+      expect(appr.mastery).to be > before
+    end
+
+    it 'does not increase mastery on failure' do
+      before = appr.mastery
+      appr.learn!(method: :modeling, success: false)
+      expect(appr.mastery).to eq(before)
+    end
+
+    it 'applies exploration multiplier' do
+      a1 = described_class.new(skill_name: 'skill', domain: 'dom', mentor_id: 'mtr', apprentice_id: 'app')
+      a2 = described_class.new(skill_name: 'skill', domain: 'dom', mentor_id: 'mtr', apprentice_id: 'app')
+      a1.learn!(method: :modeling, success: true)
+      a2.learn!(method: :exploration, success: true)
+      expect(a2.mastery).to be > a1.mastery
+    end
+
+    it 'applies coaching multiplier' do
+      a1 = described_class.new(skill_name: 'skill', domain: 'dom', mentor_id: 'mtr', apprentice_id: 'app')
+      a2 = described_class.new(skill_name: 'skill', domain: 'dom', mentor_id: 'mtr', apprentice_id: 'app')
+      a1.learn!(method: :modeling, success: true)
+      a2.learn!(method: :coaching, success: true)
+      expect(a2.mastery).to be > a1.mastery
+    end
+
+    it 'increments session_count' do
+      appr.learn!(method: :scaffolding, success: true)
+      expect(appr.session_count).to eq(1)
+    end
+
+    it 'clamps mastery at ceiling' do
+      100.times { appr.learn!(method: :exploration, success: true) }
+      expect(appr.mastery).to be <= 1.0
+    end
+
+    it 'updates last_session_at' do
+      appr.learn!(method: :reflection, success: true)
+      expect(appr.last_session_at).not_to be_nil
+    end
+  end
+
+  describe '#decay!' do
+    it 'reduces mastery' do
+      appr.learn!(method: :exploration, success: true)
+      before = appr.mastery
+      appr.decay!
+      expect(appr.mastery).to be < before
+    end
+
+    it 'clamps at floor' do
+      100.times { appr.decay! }
+      expect(appr.mastery).to be >= 0.0
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all expected keys' do
+      h = appr.to_h
+      expect(h).to include(:id, :skill_name, :domain, :mentor_id, :apprentice_id,
+                           :mastery, :current_phase, :mastery_label, :graduated,
+                           :session_count, :created_at, :last_session_at)
+    end
+
+    it 'reflects graduated status' do
+      30.times { appr.learn!(method: :exploration, success: true) }
+      expect(appr.to_h[:graduated]).to be true
+    end
+  end
+end

data/spec/legion/extensions/cognitive_apprenticeship/runners/cognitive_apprenticeship_spec.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_apprenticeship/client'
+
+RSpec.describe Legion::Extensions::CognitiveApprenticeship::Runners::CognitiveApprenticeship do
+  let(:client) { Legion::Extensions::CognitiveApprenticeship::Client.new }
+
+  let(:valid_params) do
+    {
+      skill_name:    'ruby',
+      domain:        'programming',
+      mentor_id:     'mentor-1',
+      apprentice_id: 'learner-1'
+    }
+  end
+
+  def create_one
+    client.create_apprenticeship(**valid_params)
+  end
+
+  describe '#create_apprenticeship' do
+    it 'returns success: true with a valid apprenticeship hash' do
+      result = create_one
+      expect(result[:success]).to be true
+      expect(result[:apprenticeship]).to include(:id, :skill_name, :mastery)
+    end
+
+    it 'returns success: false when a param is too short' do
+      result = client.create_apprenticeship(skill_name: 'ab', domain: 'dom', mentor_id: 'mtr', apprentice_id: 'app')
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:param_too_short)
+    end
+  end
+
+  describe '#conduct_apprenticeship_session' do
+    it 'returns success: true and updated mastery' do
+      created = create_one
+      id = created[:apprenticeship][:id]
+      result = client.conduct_apprenticeship_session(apprenticeship_id: id, method: :modeling, success: true)
+      expect(result[:success]).to be true
+      expect(result[:apprenticeship][:mastery]).to be > 0.1
+    end
+
+    it 'returns success: false for unknown apprenticeship' do
+      result = client.conduct_apprenticeship_session(apprenticeship_id: 'nope', method: :modeling, success: true)
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:not_found)
+    end
+
+    it 'returns success: false for invalid method' do
+      created = create_one
+      id = created[:apprenticeship][:id]
+      result = client.conduct_apprenticeship_session(apprenticeship_id: id, method: :unknown, success: true)
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:invalid_method)
+    end
+
+    it 'accepts all six valid methods' do
+      Legion::Extensions::CognitiveApprenticeship::Helpers::ApprenticeshipModel::METHODS.each do |method|
+        c = Legion::Extensions::CognitiveApprenticeship::Client.new
+        created = c.create_apprenticeship(**valid_params)
+        id = created[:apprenticeship][:id]
+        result = c.conduct_apprenticeship_session(apprenticeship_id: id, method: method, success: true)
+        expect(result[:success]).to be true
+      end
+    end
+  end
+
+  describe '#recommend_apprenticeship_method' do
+    it 'returns success: true with a valid method' do
+      created = create_one
+      id = created[:apprenticeship][:id]
+      result = client.recommend_apprenticeship_method(apprenticeship_id: id)
+      expect(result[:success]).to be true
+      expect(Legion::Extensions::CognitiveApprenticeship::Helpers::ApprenticeshipModel::METHODS).to include(result[:recommended_method])
+    end
+
+    it 'returns success: false for unknown apprenticeship' do
+      result = client.recommend_apprenticeship_method(apprenticeship_id: 'nope')
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#graduated_apprenticeships' do
+    it 'returns success: true and an empty list initially' do
+      result = client.graduated_apprenticeships
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(0)
+    end
+
+    it 'includes graduated apprenticeships' do
+      created = create_one
+      id = created[:apprenticeship][:id]
+      30.times { client.conduct_apprenticeship_session(apprenticeship_id: id, method: :exploration, success: true) }
+      result = client.graduated_apprenticeships
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#active_apprenticeships' do
+    it 'returns the newly created apprenticeship' do
+      create_one
+      result = client.active_apprenticeships
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#mentor_apprenticeships' do
+    it 'returns apprenticeships for the mentor' do
+      create_one
+      result = client.mentor_apprenticeships(mentor_id: 'mentor-1')
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#apprentice_apprenticeships' do
+    it 'returns apprenticeships for the apprentice' do
+      create_one
+      result = client.apprentice_apprenticeships(apprentice_id: 'learner-1')
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#domain_apprenticeships' do
+    it 'returns apprenticeships for the domain' do
+      create_one
+      result = client.domain_apprenticeships(domain: 'programming')
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#update_cognitive_apprenticeship' do
+    it 'delegates to conduct_apprenticeship_session' do
+      created = create_one
+      id = created[:apprenticeship][:id]
+      result = client.update_cognitive_apprenticeship(apprenticeship_id: id, method: :coaching, success: true)
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#cognitive_apprenticeship_stats' do
+    it 'returns success: true with stats' do
+      create_one
+      result = client.cognitive_apprenticeship_stats
+      expect(result[:success]).to be true
+      expect(result[:total]).to eq(1)
+      expect(result).to include(:active, :graduated, :sessions)
+    end
+  end
+end

data/spec/legion/extensions/cognitive_apprenticeship_spec.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveApprenticeship do
+  it 'has a version number' do
+    expect(Legion::Extensions::CognitiveApprenticeship::VERSION).not_to be_nil
+  end
+
+  it 'has a version that is a string' do
+    expect(Legion::Extensions::CognitiveApprenticeship::VERSION).to be_a(String)
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+module Legion
+  module Logging
+    def self.debug(_msg); end
+    def self.info(_msg); end
+    def self.warn(_msg); end
+    def self.error(_msg); end
+  end
+end
+
+require 'legion/extensions/cognitive_apprenticeship'
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = '.rspec_status'
+  config.disable_monkey_patching!
+  config.expect_with(:rspec) { |c| c.syntax = :expect }
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: lex-cognitive-apprenticeship
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Esity
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: legion-gaia
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 'Collins'' Cognitive Apprenticeship model for brain-modeled agentic AI:
+  guided learning through modeling, coaching, scaffolding, articulation, reflection,
+  and exploration'
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-cognitive-apprenticeship.gemspec
+- lib/legion/extensions/cognitive_apprenticeship.rb
+- lib/legion/extensions/cognitive_apprenticeship/client.rb
+- lib/legion/extensions/cognitive_apprenticeship/helpers/apprenticeship.rb
+- lib/legion/extensions/cognitive_apprenticeship/helpers/apprenticeship_engine.rb
+- lib/legion/extensions/cognitive_apprenticeship/helpers/apprenticeship_model.rb
+- lib/legion/extensions/cognitive_apprenticeship/runners/cognitive_apprenticeship.rb
+- lib/legion/extensions/cognitive_apprenticeship/version.rb
+- spec/legion/extensions/cognitive_apprenticeship/client_spec.rb
+- spec/legion/extensions/cognitive_apprenticeship/helpers/apprenticeship_engine_spec.rb
+- spec/legion/extensions/cognitive_apprenticeship/helpers/apprenticeship_model_spec.rb
+- spec/legion/extensions/cognitive_apprenticeship/helpers/apprenticeship_spec.rb
+- spec/legion/extensions/cognitive_apprenticeship/runners/cognitive_apprenticeship_spec.rb
+- spec/legion/extensions/cognitive_apprenticeship_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-cognitive-apprenticeship
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-cognitive-apprenticeship
+  source_code_uri: https://github.com/LegionIO/lex-cognitive-apprenticeship
+  documentation_uri: https://github.com/LegionIO/lex-cognitive-apprenticeship
+  changelog_uri: https://github.com/LegionIO/lex-cognitive-apprenticeship
+  bug_tracker_uri: https://github.com/LegionIO/lex-cognitive-apprenticeship/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: LEX Cognitive Apprenticeship
+test_files: []