lex-agentic-social 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 80ee16f8854bb04f18fc39c15b9c6b32b5332ce7ecde6f25258fe897bce3116c
+  data.tar.gz: dbff7513ce10185e77b74cf224a74550ce6bc356a1f170e33305f23190691951
+SHA512:
+  metadata.gz: 402582867dcf379985efdb90d1763448d57c1158662cd65f2862b7765ecb7767933df2deee9f24381b9197fa8ae85fe2a2191325100215ac224340f184574768
+  data.tar.gz: 5dd65fa4d350317c6fe6fe0f7e330dd507c1b678726d106f688dccd98ea4233689755e62e9dd7d42c446fb2d80c38e2df930e86964072482d7968e2929732cbb

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-18
+
+### Added
+- Initial release as domain consolidation gem
+- Consolidated source extensions into unified domain gem under `Legion::Extensions::Agentic::<Domain>`
+- All sub-modules loaded from single entry point
+- Full spec suite with zero failures
+- RuboCop compliance across all files

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Iverson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,13 @@
+# lex-agentic-social
+
+LEX agentic social domain: empathy, social cognition, theory of mind
+
+## Sub-modules
+
+*(populated as extensions are consolidated)*
+
+## Installation
+
+```ruby
+gem 'lex-agentic-social'
+```

data/lex-agentic-social.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/agentic/social/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-agentic-social'
+  spec.version       = Legion::Extensions::Agentic::Social::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Agentic Social'
+  spec.description   = 'LEX agentic social domain: empathy, social cognition, theory of mind'
+  spec.homepage      = 'https://github.com/LegionIO/lex-agentic-social'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']      = spec.homepage
+  spec.metadata['source_code_uri']   = spec.homepage
+  spec.metadata['changelog_uri']     = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir.glob('{lib,spec}/**/*.rb') + %w[lex-agentic-social.gemspec Gemfile LICENSE README.md CHANGELOG.md]
+  end
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'rspec', '~> 3.13'
+  spec.add_development_dependency 'rubocop', '~> 1.60'
+  spec.add_development_dependency 'rubocop-rspec', '~> 2.26'
+end

data/lib/legion/extensions/agentic/social/apprenticeship/client.rb

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

data/lib/legion/extensions/agentic/social/apprenticeship/helpers/apprenticeship.rb

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

data/lib/legion/extensions/agentic/social/apprenticeship/helpers/apprenticeship_engine.rb

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

data/lib/legion/extensions/agentic/social/apprenticeship/helpers/apprenticeship_model.rb

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

data/lib/legion/extensions/agentic/social/apprenticeship/runners/cognitive_apprenticeship.rb

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

data/lib/legion/extensions/agentic/social/apprenticeship/version.rb

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

data/lib/legion/extensions/agentic/social/apprenticeship.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/social/apprenticeship/version'
+require 'legion/extensions/agentic/social/apprenticeship/helpers/apprenticeship_model'
+require 'legion/extensions/agentic/social/apprenticeship/helpers/apprenticeship'
+require 'legion/extensions/agentic/social/apprenticeship/helpers/apprenticeship_engine'
+require 'legion/extensions/agentic/social/apprenticeship/runners/cognitive_apprenticeship'
+require 'legion/extensions/agentic/social/apprenticeship/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module Apprenticeship
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/social/conflict/actors/stale_check.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module Conflict
+          module Actor
+            class StaleCheck < Legion::Extensions::Actors::Every
+              def runner_class
+                Legion::Extensions::Agentic::Social::Conflict::Runners::Conflict
+              end
+
+              def runner_function
+                'check_stale_conflicts'
+              end
+
+              def time
+                3600
+              end
+
+              def run_now?
+                false
+              end
+
+              def use_runner?
+                false
+              end
+
+              def check_subtask?
+                false
+              end
+
+              def generate_task?
+                false
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/social/conflict/client.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/social/conflict/helpers/severity'
+require 'legion/extensions/agentic/social/conflict/helpers/conflict_log'
+require 'legion/extensions/agentic/social/conflict/runners/conflict'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module Conflict
+          class Client
+            include Runners::Conflict
+
+            def initialize(**)
+              @conflict_log = Helpers::ConflictLog.new
+            end
+
+            private
+
+            attr_reader :conflict_log
+          end
+        end
+      end
+    end
+  end
+end