lex-social-learning 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a099b9a518340e711699d958e1de852e7d04d420adca67b0d67f96c7ecbe92a9
+  data.tar.gz: 42bb370a5586e73d9d8ba4650103091345f915b8a952aefa5057a1afb233594c
+SHA512:
+  metadata.gz: 89887a76ef663f2d17fa65a20a78d350849791c7916a4f1c26fd14e4cd20ffc93a93fef6edfb0ec428dce93f70bd9f620e907d2a30879ca609ef54d93f87ccf5
+  data.tar.gz: 810ac3320303238b05e2b1107bb3def16f48a87cb455867b4a1abac2eadc5430de45ec1402cbe1befcd5561c050619326e5cd9b04ee07e9978a6cc20bbae1311

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-social-learning.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/social_learning/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-social-learning'
+  spec.version       = Legion::Extensions::SocialLearning::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Social Learning'
+  spec.description   = "Bandura's Social Cognitive Theory for LegionIO: vicarious learning via model observation and reproduction"
+  spec.homepage      = 'https://github.com/LegionIO/lex-social-learning'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']        = spec.homepage
+  spec.metadata['source_code_uri']     = 'https://github.com/LegionIO/lex-social-learning'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-social-learning'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-social-learning'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-social-learning/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-social-learning.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/social_learning/helpers/constants'
+require 'legion/extensions/social_learning/helpers/observed_behavior'
+require 'legion/extensions/social_learning/helpers/model_agent'
+require 'legion/extensions/social_learning/helpers/social_learning_engine'
+require 'legion/extensions/social_learning/runners/social_learning'
+
+module Legion
+  module Extensions
+    module SocialLearning
+      class Client
+        include Runners::SocialLearning
+
+        def initialize(engine: nil)
+          @engine = engine || Helpers::SocialLearningEngine.new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module SocialLearning
+      module Helpers
+        module Constants
+          MAX_MODELS      = 200
+          MAX_BEHAVIORS   = 500
+          MAX_OBSERVATIONS = 1000
+          MAX_HISTORY = 300
+
+          DEFAULT_PRESTIGE    = 0.5
+          PRESTIGE_FLOOR      = 0.0
+          PRESTIGE_CEILING    = 1.0
+          ATTENTION_THRESHOLD = 0.3
+          RETENTION_DECAY     = 0.02
+          REPRODUCTION_CONFIDENCE = 0.5
+          REINFORCEMENT_BOOST = 0.15
+          PUNISHMENT_PENALTY  = 0.2
+          PRESTIGE_LEARNING_RATE = 0.1
+          STALE_THRESHOLD = 120
+
+          OUTCOME_TYPES   = %i[positive negative neutral].freeze
+          LEARNING_STAGES = %i[attention retention reproduction motivation].freeze
+
+          MODEL_LABELS = {
+            (0.8..)     => :expert,
+            (0.6...0.8) => :proficient,
+            (0.4...0.6) => :peer,
+            (0.2...0.4) => :novice,
+            (..0.2)     => :unreliable
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/social_learning/helpers/model_agent.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module SocialLearning
+      module Helpers
+        class ModelAgent
+          include Constants
+
+          attr_reader :id, :agent_id, :domain, :observation_count,
+                      :success_count, :created_at, :last_observed_at,
+                      :observed_behaviors
+          attr_accessor :prestige
+
+          def initialize(agent_id:, domain:, prestige: Constants::DEFAULT_PRESTIGE)
+            @id                 = SecureRandom.uuid
+            @agent_id           = agent_id
+            @domain             = domain
+            @prestige           = prestige.clamp(Constants::PRESTIGE_FLOOR, Constants::PRESTIGE_CEILING)
+            @observed_behaviors = []
+            @observation_count  = 0
+            @success_count      = 0
+            @created_at         = Time.now.utc
+            @last_observed_at   = nil
+          end
+
+          def observe!(behavior:, outcome:)
+            @observation_count += 1
+            @last_observed_at = Time.now.utc
+
+            if outcome == :positive
+              @success_count += 1
+              @prestige = (@prestige + Constants::PRESTIGE_LEARNING_RATE).clamp(
+                Constants::PRESTIGE_FLOOR,
+                Constants::PRESTIGE_CEILING
+              )
+            elsif outcome == :negative
+              @prestige = (@prestige - Constants::PRESTIGE_LEARNING_RATE).clamp(
+                Constants::PRESTIGE_FLOOR,
+                Constants::PRESTIGE_CEILING
+              )
+            end
+
+            behavior
+          end
+
+          def prestige_label
+            Constants::MODEL_LABELS.find { |range, _label| range.include?(@prestige) }&.last || :unknown
+          end
+
+          def success_rate
+            return 0.0 if @observation_count.zero?
+
+            (@success_count.to_f / @observation_count).round(4)
+          end
+
+          def to_h
+            {
+              id:                @id,
+              agent_id:          @agent_id,
+              domain:            @domain,
+              prestige:          @prestige.round(4),
+              prestige_label:    prestige_label,
+              observation_count: @observation_count,
+              success_count:     @success_count,
+              success_rate:      success_rate,
+              behavior_count:    @observed_behaviors.size,
+              created_at:        @created_at,
+              last_observed_at:  @last_observed_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/social_learning/helpers/observed_behavior.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module SocialLearning
+      module Helpers
+        class ObservedBehavior
+          include Constants
+
+          attr_reader :id, :model_agent_id, :action, :domain, :context,
+                      :outcome, :created_at
+          attr_accessor :retention, :reproduced
+
+          def initialize(model_agent_id:, action:, domain:, outcome:, context: {})
+            @id             = SecureRandom.uuid
+            @model_agent_id = model_agent_id
+            @action         = action
+            @domain         = domain
+            @context        = context
+            @outcome        = outcome
+            @retention      = 1.0
+            @reproduced     = false
+            @created_at     = Time.now.utc
+          end
+
+          def decay_retention!
+            @retention = (@retention - Constants::RETENTION_DECAY).clamp(
+              Constants::PRESTIGE_FLOOR,
+              Constants::PRESTIGE_CEILING
+            )
+          end
+
+          def retained?
+            @retention >= Constants::REPRODUCTION_CONFIDENCE
+          end
+
+          def to_h
+            {
+              id:             @id,
+              model_agent_id: @model_agent_id,
+              action:         @action,
+              domain:         @domain,
+              context:        @context,
+              outcome:        @outcome,
+              retention:      @retention.round(4),
+              reproduced:     @reproduced,
+              retained:       retained?,
+              created_at:     @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/social_learning/helpers/social_learning_engine.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module SocialLearning
+      module Helpers
+        class SocialLearningEngine
+          include Constants
+
+          def initialize
+            @models     = {}  # id -> ModelAgent
+            @behaviors  = {}  # id -> ObservedBehavior
+          end
+
+          def register_model(agent_id:, domain:, prestige: Constants::DEFAULT_PRESTIGE)
+            prune_models if @models.size >= Constants::MAX_MODELS
+
+            model = ModelAgent.new(agent_id: agent_id, domain: domain, prestige: prestige)
+            @models[model.id] = model
+            model
+          end
+
+          def observe_behavior(model_id:, action:, domain:, outcome:, context: {})
+            model = @models.fetch(model_id, nil)
+            return nil unless model
+            return nil if model.prestige < Constants::ATTENTION_THRESHOLD
+
+            prune_behaviors if @behaviors.size >= Constants::MAX_BEHAVIORS
+
+            behavior = ObservedBehavior.new(
+              model_agent_id: model_id,
+              action:         action,
+              domain:         domain,
+              outcome:        outcome,
+              context:        context
+            )
+
+            model.observe!(behavior: behavior, outcome: outcome)
+            model.observed_behaviors << behavior
+            @behaviors[behavior.id] = behavior
+            behavior
+          end
+
+          def retained_behaviors(domain: nil)
+            behaviors = @behaviors.values.select(&:retained?)
+            return behaviors unless domain
+
+            behaviors.select { |beh| beh.domain == domain }
+          end
+
+          def reproducible_behaviors(domain: nil)
+            behaviors = retained_behaviors(domain: domain)
+            behaviors.select { |beh| beh.retention >= Constants::REPRODUCTION_CONFIDENCE }
+          end
+
+          def reproduce_behavior(behavior_id:)
+            behavior = @behaviors.fetch(behavior_id, nil)
+            return nil unless behavior
+            return nil unless behavior.retained?
+
+            behavior.reproduced = true
+            behavior
+          end
+
+          def reinforce_reproduction(behavior_id:, outcome:)
+            behavior = @behaviors.fetch(behavior_id, nil)
+            return nil unless behavior
+
+            model = @models.fetch(behavior.model_agent_id, nil)
+            return nil unless model
+
+            case outcome
+            when :positive
+              model.prestige = (model.prestige + Constants::REINFORCEMENT_BOOST).clamp(
+                Constants::PRESTIGE_FLOOR,
+                Constants::PRESTIGE_CEILING
+              )
+            when :negative
+              model.prestige = (model.prestige - Constants::PUNISHMENT_PENALTY).clamp(
+                Constants::PRESTIGE_FLOOR,
+                Constants::PRESTIGE_CEILING
+              )
+            end
+
+            { behavior: behavior.to_h, model_prestige: model.prestige.round(4) }
+          end
+
+          def best_models(limit: 5)
+            @models.values
+                   .sort_by { |mod| -mod.prestige }
+                   .first(limit)
+          end
+
+          def by_domain(domain:)
+            @models.values.select { |mod| mod.domain == domain }
+          end
+
+          def decay_all
+            @behaviors.each_value(&:decay_retention!)
+          end
+
+          def prune_forgotten
+            @behaviors.delete_if { |_id, beh| beh.retention < 0.05 }
+          end
+
+          def to_h
+            {
+              model_count:        @models.size,
+              behavior_count:     @behaviors.size,
+              retained_count:     retained_behaviors.size,
+              reproducible_count: reproducible_behaviors.size
+            }
+          end
+
+          private
+
+          def prune_models
+            oldest = @models.values.min_by(&:created_at)
+            @models.delete(oldest.id) if oldest
+          end
+
+          def prune_behaviors
+            oldest = @behaviors.values.min_by(&:created_at)
+            @behaviors.delete(oldest.id) if oldest
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module SocialLearning
+      module Runners
+        module SocialLearning
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def register_model_agent(agent_id:, domain:, prestige: nil, **)
+            init_prestige = prestige || Helpers::Constants::DEFAULT_PRESTIGE
+            Legion::Logging.debug "[social_learning] register_model agent=#{agent_id} domain=#{domain} prestige=#{init_prestige}"
+            model = engine.register_model(agent_id: agent_id, domain: domain, prestige: init_prestige)
+            { success: true, model: model.to_h }
+          end
+
+          def observe_agent_behavior(model_id:, action:, domain:, outcome:, context: {}, **)
+            Legion::Logging.debug "[social_learning] observe model=#{model_id} action=#{action} domain=#{domain} outcome=#{outcome}"
+            behavior = engine.observe_behavior(
+              model_id: model_id,
+              action:   action,
+              domain:   domain,
+              outcome:  outcome,
+              context:  context
+            )
+            if behavior
+              { success: true, behavior: behavior.to_h }
+            else
+              { success: false, reason: 'model not found or below attention threshold' }
+            end
+          end
+
+          def retained_behaviors(domain: nil, **)
+            Legion::Logging.debug "[social_learning] retained_behaviors domain=#{domain.inspect}"
+            behaviors = engine.retained_behaviors(domain: domain)
+            { success: true, behaviors: behaviors.map(&:to_h), count: behaviors.size }
+          end
+
+          def reproducible_behaviors(domain: nil, **)
+            Legion::Logging.debug "[social_learning] reproducible_behaviors domain=#{domain.inspect}"
+            behaviors = engine.reproducible_behaviors(domain: domain)
+            { success: true, behaviors: behaviors.map(&:to_h), count: behaviors.size }
+          end
+
+          def reproduce_observed_behavior(behavior_id:, **)
+            Legion::Logging.debug "[social_learning] reproduce behavior_id=#{behavior_id}"
+            behavior = engine.reproduce_behavior(behavior_id: behavior_id)
+            if behavior
+              { success: true, behavior: behavior.to_h }
+            else
+              { success: false, reason: 'behavior not found or retention too low' }
+            end
+          end
+
+          def reinforce_reproduction(behavior_id:, outcome:, **)
+            Legion::Logging.debug "[social_learning] reinforce behavior_id=#{behavior_id} outcome=#{outcome}"
+            result = engine.reinforce_reproduction(behavior_id: behavior_id, outcome: outcome)
+            if result
+              { success: true }.merge(result)
+            else
+              { success: false, reason: 'behavior or model not found' }
+            end
+          end
+
+          def best_model_agents(limit: 5, **)
+            lim = limit.to_i
+            Legion::Logging.debug "[social_learning] best_model_agents limit=#{lim}"
+            models = engine.best_models(limit: lim)
+            { success: true, models: models.map(&:to_h), count: models.size }
+          end
+
+          def domain_models(domain:, **)
+            Legion::Logging.debug "[social_learning] domain_models domain=#{domain}"
+            models = engine.by_domain(domain: domain)
+            { success: true, models: models.map(&:to_h), count: models.size }
+          end
+
+          def update_social_learning(**)
+            Legion::Logging.debug '[social_learning] update_social_learning decay+prune cycle'
+            engine.decay_all
+            engine.prune_forgotten
+            stats = engine.to_h
+            { success: true }.merge(stats)
+          end
+
+          def social_learning_stats(**)
+            Legion::Logging.debug '[social_learning] social_learning_stats'
+            { success: true }.merge(engine.to_h)
+          end
+
+          private
+
+          def engine
+            @engine ||= Helpers::SocialLearningEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/social_learning.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/social_learning/version'
+require 'legion/extensions/social_learning/helpers/constants'
+require 'legion/extensions/social_learning/helpers/observed_behavior'
+require 'legion/extensions/social_learning/helpers/model_agent'
+require 'legion/extensions/social_learning/helpers/social_learning_engine'
+require 'legion/extensions/social_learning/runners/social_learning'
+require 'legion/extensions/social_learning/client'
+
+module Legion
+  module Extensions
+    module SocialLearning
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::SocialLearning::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to all runner methods' do
+    expect(client).to respond_to(:register_model_agent)
+    expect(client).to respond_to(:observe_agent_behavior)
+    expect(client).to respond_to(:retained_behaviors)
+    expect(client).to respond_to(:reproducible_behaviors)
+    expect(client).to respond_to(:reproduce_observed_behavior)
+    expect(client).to respond_to(:reinforce_reproduction)
+    expect(client).to respond_to(:best_model_agents)
+    expect(client).to respond_to(:domain_models)
+    expect(client).to respond_to(:update_social_learning)
+    expect(client).to respond_to(:social_learning_stats)
+  end
+
+  it 'accepts an injected engine' do
+    engine = Legion::Extensions::SocialLearning::Helpers::SocialLearningEngine.new
+    injected_client = described_class.new(engine: engine)
+    result = injected_client.social_learning_stats
+    expect(result[:success]).to be true
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::SocialLearning::Helpers::Constants do
+  it 'defines MAX_MODELS' do
+    expect(described_module::MAX_MODELS).to eq(200)
+  end
+
+  it 'defines MAX_BEHAVIORS' do
+    expect(described_module::MAX_BEHAVIORS).to eq(500)
+  end
+
+  it 'defines ATTENTION_THRESHOLD' do
+    expect(described_module::ATTENTION_THRESHOLD).to eq(0.3)
+  end
+
+  it 'defines REPRODUCTION_CONFIDENCE' do
+    expect(described_module::REPRODUCTION_CONFIDENCE).to eq(0.5)
+  end
+
+  it 'defines OUTCOME_TYPES' do
+    expect(described_module::OUTCOME_TYPES).to eq(%i[positive negative neutral])
+  end
+
+  it 'defines LEARNING_STAGES' do
+    expect(described_module::LEARNING_STAGES).to eq(%i[attention retention reproduction motivation])
+  end
+
+  it 'defines MODEL_LABELS mapping' do
+    expect(described_module::MODEL_LABELS).to be_a(Hash)
+    expect(described_module::MODEL_LABELS.size).to eq(5)
+  end
+
+  it 'PRESTIGE_FLOOR is 0.0' do
+    expect(described_module::PRESTIGE_FLOOR).to eq(0.0)
+  end
+
+  it 'PRESTIGE_CEILING is 1.0' do
+    expect(described_module::PRESTIGE_CEILING).to eq(1.0)
+  end
+
+  def described_module
+    Legion::Extensions::SocialLearning::Helpers::Constants
+  end
+end

data/spec/legion/extensions/social_learning/helpers/model_agent_spec.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::SocialLearning::Helpers::ModelAgent do
+  subject(:model) do
+    described_class.new(agent_id: 'agent-abc', domain: :ops, prestige: 0.5)
+  end
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(model.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets the agent_id' do
+      expect(model.agent_id).to eq('agent-abc')
+    end
+
+    it 'sets prestige' do
+      expect(model.prestige).to eq(0.5)
+    end
+
+    it 'starts with zero observation_count' do
+      expect(model.observation_count).to eq(0)
+    end
+
+    it 'starts with empty observed_behaviors' do
+      expect(model.observed_behaviors).to be_empty
+    end
+
+    it 'clamps prestige above ceiling to 1.0' do
+      m = described_class.new(agent_id: 'x', domain: :test, prestige: 5.0)
+      expect(m.prestige).to eq(1.0)
+    end
+
+    it 'clamps prestige below floor to 0.0' do
+      m = described_class.new(agent_id: 'x', domain: :test, prestige: -1.0)
+      expect(m.prestige).to eq(0.0)
+    end
+  end
+
+  describe '#observe!' do
+    let(:fake_behavior) { double('ObservedBehavior') }
+
+    it 'increments observation_count' do
+      expect { model.observe!(behavior: fake_behavior, outcome: :neutral) }
+        .to change(model, :observation_count).by(1)
+    end
+
+    it 'increases prestige on positive outcome' do
+      before = model.prestige
+      model.observe!(behavior: fake_behavior, outcome: :positive)
+      expect(model.prestige).to be > before
+    end
+
+    it 'decreases prestige on negative outcome' do
+      before = model.prestige
+      model.observe!(behavior: fake_behavior, outcome: :negative)
+      expect(model.prestige).to be < before
+    end
+
+    it 'does not change prestige on neutral outcome' do
+      before = model.prestige
+      model.observe!(behavior: fake_behavior, outcome: :neutral)
+      expect(model.prestige).to eq(before)
+    end
+
+    it 'tracks success_count for positive outcomes' do
+      model.observe!(behavior: fake_behavior, outcome: :positive)
+      expect(model.success_count).to eq(1)
+    end
+  end
+
+  describe '#prestige_label' do
+    it 'returns :expert for prestige >= 0.8' do
+      model.prestige = 0.9
+      expect(model.prestige_label).to eq(:expert)
+    end
+
+    it 'returns :proficient for prestige in 0.6...0.8' do
+      model.prestige = 0.7
+      expect(model.prestige_label).to eq(:proficient)
+    end
+
+    it 'returns :peer for prestige in 0.4...0.6' do
+      model.prestige = 0.5
+      expect(model.prestige_label).to eq(:peer)
+    end
+
+    it 'returns :novice for prestige in 0.2...0.4' do
+      model.prestige = 0.3
+      expect(model.prestige_label).to eq(:novice)
+    end
+
+    it 'returns :unreliable for prestige below 0.2' do
+      model.prestige = 0.1
+      expect(model.prestige_label).to eq(:unreliable)
+    end
+  end
+
+  describe '#success_rate' do
+    it 'returns 0.0 with no observations' do
+      expect(model.success_rate).to eq(0.0)
+    end
+
+    it 'returns correct ratio after observations' do
+      fake_behavior = double('ObservedBehavior')
+      model.observe!(behavior: fake_behavior, outcome: :positive)
+      model.observe!(behavior: fake_behavior, outcome: :negative)
+      expect(model.success_rate).to eq(0.5)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with expected keys' do
+      hash = model.to_h
+      expect(hash).to include(:id, :agent_id, :domain, :prestige, :prestige_label,
+                              :observation_count, :success_count, :success_rate,
+                              :behavior_count, :created_at)
+    end
+  end
+end

data/spec/legion/extensions/social_learning/helpers/observed_behavior_spec.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::SocialLearning::Helpers::ObservedBehavior do
+  subject(:behavior) do
+    described_class.new(
+      model_agent_id: 'model-123',
+      action:         'write_test',
+      domain:         :coding,
+      outcome:        :positive,
+      context:        { language: 'ruby' }
+    )
+  end
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(behavior.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets retention to 1.0' do
+      expect(behavior.retention).to eq(1.0)
+    end
+
+    it 'sets reproduced to false' do
+      expect(behavior.reproduced).to be false
+    end
+
+    it 'stores the action' do
+      expect(behavior.action).to eq('write_test')
+    end
+
+    it 'stores the domain' do
+      expect(behavior.domain).to eq(:coding)
+    end
+
+    it 'stores the outcome' do
+      expect(behavior.outcome).to eq(:positive)
+    end
+
+    it 'stores context' do
+      expect(behavior.context).to eq({ language: 'ruby' })
+    end
+  end
+
+  describe '#decay_retention!' do
+    it 'reduces retention by RETENTION_DECAY' do
+      before = behavior.retention
+      behavior.decay_retention!
+      expect(behavior.retention).to be < before
+    end
+
+    it 'does not go below 0.0' do
+      50.times { behavior.decay_retention! }
+      expect(behavior.retention).to be >= 0.0
+    end
+  end
+
+  describe '#retained?' do
+    it 'returns true when retention is above REPRODUCTION_CONFIDENCE' do
+      expect(behavior.retained?).to be true
+    end
+
+    it 'returns false when retention has decayed below threshold' do
+      behavior.retention = 0.4
+      expect(behavior.retained?).to be false
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with expected keys' do
+      hash = behavior.to_h
+      expect(hash).to include(:id, :model_agent_id, :action, :domain, :outcome,
+                              :retention, :reproduced, :retained, :created_at)
+    end
+
+    it 'rounds retention to 4 decimal places' do
+      behavior.decay_retention!
+      hash = behavior.to_h
+      expect(hash[:retention].to_s.split('.').last.length).to be <= 4
+    end
+  end
+end

data/spec/legion/extensions/social_learning/helpers/social_learning_engine_spec.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::SocialLearning::Helpers::SocialLearningEngine do
+  subject(:engine) { described_class.new }
+
+  let(:model) { engine.register_model(agent_id: 'agent-1', domain: :coding) }
+
+  describe '#register_model' do
+    it 'returns a ModelAgent' do
+      expect(model).to be_a(Legion::Extensions::SocialLearning::Helpers::ModelAgent)
+    end
+
+    it 'assigns agent_id and domain' do
+      expect(model.agent_id).to eq('agent-1')
+      expect(model.domain).to eq(:coding)
+    end
+
+    it 'uses DEFAULT_PRESTIGE when none given' do
+      expect(model.prestige).to eq(Legion::Extensions::SocialLearning::Helpers::Constants::DEFAULT_PRESTIGE)
+    end
+  end
+
+  describe '#observe_behavior' do
+    it 'returns nil for unknown model' do
+      result = engine.observe_behavior(
+        model_id: 'nonexistent', action: 'do_thing', domain: :coding, outcome: :positive
+      )
+      expect(result).to be_nil
+    end
+
+    it 'returns nil when model prestige is below ATTENTION_THRESHOLD' do
+      low_model = engine.register_model(agent_id: 'low', domain: :coding, prestige: 0.1)
+      result = engine.observe_behavior(
+        model_id: low_model.id, action: 'do_thing', domain: :coding, outcome: :positive
+      )
+      expect(result).to be_nil
+    end
+
+    it 'returns an ObservedBehavior when model passes attention threshold' do
+      behavior = engine.observe_behavior(
+        model_id: model.id, action: 'write_test', domain: :coding, outcome: :positive
+      )
+      expect(behavior).to be_a(Legion::Extensions::SocialLearning::Helpers::ObservedBehavior)
+    end
+
+    it 'updates model prestige on positive outcome' do
+      before = model.prestige
+      engine.observe_behavior(
+        model_id: model.id, action: 'write_test', domain: :coding, outcome: :positive
+      )
+      expect(model.prestige).to be > before
+    end
+  end
+
+  describe '#retained_behaviors' do
+    before do
+      engine.observe_behavior(
+        model_id: model.id, action: 'action_a', domain: :coding, outcome: :positive
+      )
+    end
+
+    it 'returns behaviors with retention above REPRODUCTION_CONFIDENCE' do
+      result = engine.retained_behaviors
+      expect(result).not_to be_empty
+    end
+
+    it 'filters by domain when given' do
+      engine.observe_behavior(
+        model_id: model.id, action: 'action_b', domain: :ops, outcome: :positive
+      )
+      result = engine.retained_behaviors(domain: :coding)
+      expect(result.all? { |beh| beh.domain == :coding }).to be true
+    end
+  end
+
+  describe '#reproducible_behaviors' do
+    it 'returns behaviors above REPRODUCTION_CONFIDENCE' do
+      engine.observe_behavior(
+        model_id: model.id, action: 'write_test', domain: :coding, outcome: :positive
+      )
+      result = engine.reproducible_behaviors
+      expect(result).not_to be_empty
+    end
+  end
+
+  describe '#reproduce_behavior' do
+    let(:behavior) do
+      engine.observe_behavior(
+        model_id: model.id, action: 'write_test', domain: :coding, outcome: :positive
+      )
+    end
+
+    it 'marks the behavior as reproduced' do
+      engine.reproduce_behavior(behavior_id: behavior.id)
+      expect(behavior.reproduced).to be true
+    end
+
+    it 'returns nil for unknown behavior_id' do
+      result = engine.reproduce_behavior(behavior_id: 'nonexistent')
+      expect(result).to be_nil
+    end
+  end
+
+  describe '#reinforce_reproduction' do
+    let(:behavior) do
+      engine.observe_behavior(
+        model_id: model.id, action: 'write_test', domain: :coding, outcome: :positive
+      )
+    end
+
+    it 'boosts model prestige on positive outcome' do
+      before = model.prestige
+      engine.reinforce_reproduction(behavior_id: behavior.id, outcome: :positive)
+      expect(model.prestige).to be > before
+    end
+
+    it 'penalizes model prestige on negative outcome' do
+      before = model.prestige
+      engine.reinforce_reproduction(behavior_id: behavior.id, outcome: :negative)
+      expect(model.prestige).to be < before
+    end
+
+    it 'returns nil for unknown behavior_id' do
+      result = engine.reinforce_reproduction(behavior_id: 'nonexistent', outcome: :positive)
+      expect(result).to be_nil
+    end
+
+    it 'returns a hash with behavior and model_prestige' do
+      result = engine.reinforce_reproduction(behavior_id: behavior.id, outcome: :positive)
+      expect(result).to include(:behavior, :model_prestige)
+    end
+  end
+
+  describe '#best_models' do
+    before do
+      engine.register_model(agent_id: 'agent-2', domain: :ops,    prestige: 0.9)
+      engine.register_model(agent_id: 'agent-3', domain: :coding, prestige: 0.3)
+    end
+
+    it 'returns models sorted by prestige descending' do
+      models = engine.best_models(limit: 3)
+      prestiges = models.map(&:prestige)
+      expect(prestiges).to eq(prestiges.sort.reverse)
+    end
+
+    it 'respects the limit' do
+      models = engine.best_models(limit: 2)
+      expect(models.size).to be <= 2
+    end
+  end
+
+  describe '#by_domain' do
+    before do
+      engine.register_model(agent_id: 'agent-ops', domain: :ops)
+    end
+
+    it 'returns only models in the given domain' do
+      result = engine.by_domain(domain: :ops)
+      expect(result.all? { |mod| mod.domain == :ops }).to be true
+    end
+
+    it 'returns empty array for unknown domain' do
+      result = engine.by_domain(domain: :unknown_domain)
+      expect(result).to be_empty
+    end
+  end
+
+  describe '#decay_all' do
+    it 'decays retention on all behaviors' do
+      behavior = engine.observe_behavior(
+        model_id: model.id, action: 'write_test', domain: :coding, outcome: :positive
+      )
+      before = behavior.retention
+      engine.decay_all
+      expect(behavior.retention).to be < before
+    end
+  end
+
+  describe '#prune_forgotten' do
+    it 'removes behaviors below 0.05 retention' do
+      behavior = engine.observe_behavior(
+        model_id: model.id, action: 'write_test', domain: :coding, outcome: :positive
+      )
+      behavior.retention = 0.04
+      engine.prune_forgotten
+      expect(engine.retained_behaviors).not_to include(behavior)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns stats hash' do
+      result = engine.to_h
+      expect(result).to include(:model_count, :behavior_count, :retained_count, :reproducible_count)
+    end
+  end
+end

data/spec/legion/extensions/social_learning/runners/social_learning_spec.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::SocialLearning::Runners::SocialLearning do
+  let(:client) { Legion::Extensions::SocialLearning::Client.new }
+
+  describe '#register_model_agent' do
+    it 'returns success with model hash' do
+      result = client.register_model_agent(agent_id: 'agent-1', domain: :coding)
+      expect(result[:success]).to be true
+      expect(result[:model]).to include(:id, :agent_id, :domain, :prestige)
+    end
+
+    it 'accepts custom prestige' do
+      result = client.register_model_agent(agent_id: 'agent-1', domain: :coding, prestige: 0.8)
+      expect(result[:model][:prestige]).to eq(0.8)
+    end
+  end
+
+  describe '#observe_agent_behavior' do
+    let(:model_id) do
+      client.register_model_agent(agent_id: 'agent-1', domain: :coding)[:model][:id]
+    end
+
+    it 'returns success with behavior hash when model passes attention threshold' do
+      result = client.observe_agent_behavior(
+        model_id: model_id, action: 'write_test', domain: :coding, outcome: :positive
+      )
+      expect(result[:success]).to be true
+      expect(result[:behavior]).to include(:id, :action, :retention)
+    end
+
+    it 'returns success: false for unknown model_id' do
+      result = client.observe_agent_behavior(
+        model_id: 'nonexistent', action: 'do_thing', domain: :coding, outcome: :positive
+      )
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#retained_behaviors' do
+    before do
+      model_id = client.register_model_agent(agent_id: 'agent-1', domain: :coding)[:model][:id]
+      client.observe_agent_behavior(
+        model_id: model_id, action: 'write_test', domain: :coding, outcome: :positive
+      )
+    end
+
+    it 'returns behaviors with count' do
+      result = client.retained_behaviors
+      expect(result[:success]).to be true
+      expect(result).to include(:behaviors, :count)
+    end
+
+    it 'filters by domain' do
+      result = client.retained_behaviors(domain: :coding)
+      expect(result[:behaviors].all? { |beh| beh[:domain] == :coding }).to be true
+    end
+  end
+
+  describe '#reproducible_behaviors' do
+    it 'returns success: true with behaviors list' do
+      result = client.reproducible_behaviors
+      expect(result[:success]).to be true
+      expect(result).to include(:behaviors, :count)
+    end
+  end
+
+  describe '#reproduce_observed_behavior' do
+    let(:behavior_id) do
+      model_id = client.register_model_agent(agent_id: 'agent-1', domain: :coding)[:model][:id]
+      client.observe_agent_behavior(
+        model_id: model_id, action: 'write_test', domain: :coding, outcome: :positive
+      )[:behavior][:id]
+    end
+
+    it 'returns success with reproduced behavior' do
+      result = client.reproduce_observed_behavior(behavior_id: behavior_id)
+      expect(result[:success]).to be true
+      expect(result[:behavior][:reproduced]).to be true
+    end
+
+    it 'returns success: false for unknown behavior_id' do
+      result = client.reproduce_observed_behavior(behavior_id: 'nonexistent')
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#reinforce_reproduction' do
+    let(:behavior_id) do
+      model_id = client.register_model_agent(agent_id: 'agent-1', domain: :coding)[:model][:id]
+      client.observe_agent_behavior(
+        model_id: model_id, action: 'write_test', domain: :coding, outcome: :positive
+      )[:behavior][:id]
+    end
+
+    it 'returns success with model_prestige on positive outcome' do
+      result = client.reinforce_reproduction(behavior_id: behavior_id, outcome: :positive)
+      expect(result[:success]).to be true
+      expect(result[:model_prestige]).to be_a(Float)
+    end
+
+    it 'returns success: false for unknown behavior_id' do
+      result = client.reinforce_reproduction(behavior_id: 'nonexistent', outcome: :positive)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#best_model_agents' do
+    before do
+      client.register_model_agent(agent_id: 'agent-1', domain: :coding, prestige: 0.9)
+      client.register_model_agent(agent_id: 'agent-2', domain: :ops,    prestige: 0.4)
+    end
+
+    it 'returns models sorted by prestige' do
+      result = client.best_model_agents(limit: 2)
+      expect(result[:success]).to be true
+      prestiges = result[:models].map { |mod| mod[:prestige] }
+      expect(prestiges).to eq(prestiges.sort.reverse)
+    end
+  end
+
+  describe '#domain_models' do
+    before do
+      client.register_model_agent(agent_id: 'agent-1', domain: :coding)
+      client.register_model_agent(agent_id: 'agent-2', domain: :ops)
+    end
+
+    it 'returns only models for the given domain' do
+      result = client.domain_models(domain: :coding)
+      expect(result[:success]).to be true
+      expect(result[:models].all? { |mod| mod[:domain] == :coding }).to be true
+    end
+  end
+
+  describe '#update_social_learning' do
+    it 'returns success with stats' do
+      result = client.update_social_learning
+      expect(result[:success]).to be true
+      expect(result).to include(:model_count, :behavior_count)
+    end
+  end
+
+  describe '#social_learning_stats' do
+    it 'returns success with stats hash' do
+      result = client.social_learning_stats
+      expect(result[:success]).to be true
+      expect(result).to include(:model_count, :behavior_count, :retained_count, :reproducible_count)
+    end
+  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/social_learning'
+
+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-social-learning
+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: 'Bandura''s Social Cognitive Theory for LegionIO: vicarious learning
+  via model observation and reproduction'
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-social-learning.gemspec
+- lib/legion/extensions/social_learning.rb
+- lib/legion/extensions/social_learning/client.rb
+- lib/legion/extensions/social_learning/helpers/constants.rb
+- lib/legion/extensions/social_learning/helpers/model_agent.rb
+- lib/legion/extensions/social_learning/helpers/observed_behavior.rb
+- lib/legion/extensions/social_learning/helpers/social_learning_engine.rb
+- lib/legion/extensions/social_learning/runners/social_learning.rb
+- lib/legion/extensions/social_learning/version.rb
+- spec/legion/extensions/social_learning/client_spec.rb
+- spec/legion/extensions/social_learning/helpers/constants_spec.rb
+- spec/legion/extensions/social_learning/helpers/model_agent_spec.rb
+- spec/legion/extensions/social_learning/helpers/observed_behavior_spec.rb
+- spec/legion/extensions/social_learning/helpers/social_learning_engine_spec.rb
+- spec/legion/extensions/social_learning/runners/social_learning_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-social-learning
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-social-learning
+  source_code_uri: https://github.com/LegionIO/lex-social-learning
+  documentation_uri: https://github.com/LegionIO/lex-social-learning
+  changelog_uri: https://github.com/LegionIO/lex-social-learning
+  bug_tracker_uri: https://github.com/LegionIO/lex-social-learning/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 Social Learning
+test_files: []