lex-agentic-social 0.1.0

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

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

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

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

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/social/social_learning/version'
+require 'legion/extensions/agentic/social/social_learning/helpers/constants'
+require 'legion/extensions/agentic/social/social_learning/helpers/observed_behavior'
+require 'legion/extensions/agentic/social/social_learning/helpers/model_agent'
+require 'legion/extensions/agentic/social/social_learning/helpers/social_learning_engine'
+require 'legion/extensions/agentic/social/social_learning/runners/social_learning'
+require 'legion/extensions/agentic/social/social_learning/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module SocialLearning
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module Symbiosis
+          class Client
+            include Runners::CognitiveSymbiosis
+
+            def initialize(**)
+              @default_engine = Helpers::SymbiosisEngine.new
+            end
+
+            private
+
+            attr_reader :default_engine
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/social/symbiosis/helpers/constants.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module Symbiosis
+          module Helpers
+            module Constants
+              RELATIONSHIP_TYPES = %i[mutualistic parasitic commensal].freeze
+
+              INTERACTION_STRENGTHS = {
+                0.0..0.2 => :dormant,
+                0.2..0.4 => :weak,
+                0.4..0.6 => :moderate,
+                0.6..0.8 => :strong,
+                0.8..1.0 => :dominant
+              }.freeze
+
+              MAX_BONDS       = 200
+              BOND_DECAY      = 0.02
+              STRONG_THRESHOLD = 0.6
+              DORMANT_THRESHOLD = 0.05
+              MIN_STRENGTH    = 0.0
+              MAX_STRENGTH    = 1.0
+              DEFAULT_STRENGTH = 0.3
+
+              # Mutualism: both gain, benefit_ratio > 0
+              # Parasitism: one drains the other, benefit_ratio < 0
+              # Commensalism: one benefits, other unaffected, benefit_ratio ~0 for host
+              BENEFIT_RATIO_RANGES = {
+                mutualistic: (0.1..1.0),
+                parasitic:   (-1.0..-0.1),
+                commensal:   (-0.05..0.05)
+              }.freeze
+
+              ECOSYSTEM_HEALTH_LABELS = {
+                0.0..0.2 => :critical,
+                0.2..0.4 => :stressed,
+                0.4..0.6 => :balanced,
+                0.6..0.8 => :thriving,
+                0.8..1.0 => :flourishing
+              }.freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/social/symbiosis/helpers/ecosystem.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module Symbiosis
+          module Helpers
+            class Ecosystem
+              def initialize
+                @bonds = {}
+              end
+
+              def register_bond(bond)
+                raise ArgumentError, 'bond must be a SymbioticBond' unless bond.is_a?(SymbioticBond)
+                raise ArgumentError, "MAX_BONDS (#{Constants::MAX_BONDS}) exceeded" if @bonds.size >= Constants::MAX_BONDS
+
+                @bonds[bond.bond_id] = bond
+                bond
+              end
+
+              def activate_bond(bond_id, amount: 0.05)
+                bond = @bonds[bond_id]
+                return { found: false, bond_id: bond_id } unless bond
+
+                bond.activate!(amount: amount)
+                { found: true, bond_id: bond_id, strength: bond.strength, activation_count: bond.activation_count }
+              end
+
+              def measure_health
+                return 0.0 if @bonds.empty?
+
+                active = @bonds.values.reject(&:dormant?)
+                return 0.0 if active.empty?
+
+                mutualistic = active.count { |b| b.relationship_type == :mutualistic }
+                parasitic   = active.count { |b| b.relationship_type == :parasitic }
+                total_active = active.size
+
+                mutualistic_ratio = mutualistic.to_f / total_active
+                parasite_penalty  = parasitic.to_f / total_active * 0.5
+
+                (mutualistic_ratio - parasite_penalty).clamp(0.0, 1.0).round(10)
+              end
+
+              def health_label
+                score = measure_health
+                Constants::ECOSYSTEM_HEALTH_LABELS.each do |range, label|
+                  return label if range.cover?(score)
+                end
+                :critical
+              end
+
+              def most_beneficial
+                @bonds.values
+                      .select { |b| b.relationship_type == :mutualistic && !b.dormant? }
+                      .max_by { |b| b.benefit_ratio * b.strength }
+              end
+
+              def most_parasitic
+                @bonds.values
+                      .select { |b| b.relationship_type == :parasitic && !b.dormant? }
+                      .min_by { |b| b.benefit_ratio * b.strength }
+              end
+
+              def decay_all!
+                decayed = 0
+                @bonds.each_value do |bond|
+                  bond.decay!
+                  decayed += 1
+                end
+                decayed
+              end
+
+              def network_density
+                return 0.0 if @bonds.empty?
+
+                active = @bonds.values.reject(&:dormant?)
+                return 0.0 if active.empty?
+
+                avg_strength = active.sum(&:strength) / active.size.to_f
+                avg_strength.clamp(0.0, 1.0).round(10)
+              end
+
+              def symbiotic_web(subsystem_id)
+                @bonds.values.select { |b| b.involves?(subsystem_id) }
+              end
+
+              def find_bond(subsystem_a, subsystem_b)
+                @bonds.values.find do |b|
+                  (b.subsystem_a == subsystem_a && b.subsystem_b == subsystem_b) ||
+                    (b.subsystem_a == subsystem_b && b.subsystem_b == subsystem_a)
+                end
+              end
+
+              def all_bonds
+                @bonds.values
+              end
+
+              def bond_count
+                @bonds.size
+              end
+
+              def active_bonds
+                @bonds.values.reject(&:dormant?)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/social/symbiosis/helpers/symbiosis_engine.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module Symbiosis
+          module Helpers
+            class SymbiosisEngine
+              def initialize
+                @ecosystem = Ecosystem.new
+              end
+
+              def create_bond(subsystem_a:, subsystem_b:, relationship_type:, strength: nil, benefit_ratio: nil)
+                existing = @ecosystem.find_bond(subsystem_a, subsystem_b)
+                return { created: false, reason: :already_exists, bond: existing.to_h } if existing
+
+                bond = SymbioticBond.new(
+                  subsystem_a:       subsystem_a,
+                  subsystem_b:       subsystem_b,
+                  relationship_type: relationship_type,
+                  strength:          strength,
+                  benefit_ratio:     benefit_ratio
+                )
+                @ecosystem.register_bond(bond)
+                { created: true, bond: bond.to_h }
+              rescue ArgumentError => e
+                { created: false, reason: :invalid_arguments, error: e.message }
+              end
+
+              def activate_interaction(subsystem_a:, subsystem_b:, amount: 0.05)
+                bond = @ecosystem.find_bond(subsystem_a, subsystem_b)
+                return { found: false, subsystem_a: subsystem_a, subsystem_b: subsystem_b } unless bond
+
+                result = @ecosystem.activate_bond(bond.bond_id, amount: amount)
+                result.merge(
+                  relationship_type: bond.relationship_type,
+                  benefit_ratio:     bond.benefit_ratio
+                )
+              end
+
+              def measure_ecosystem_health
+                score = @ecosystem.measure_health
+                {
+                  score:           score,
+                  label:           @ecosystem.health_label,
+                  bond_count:      @ecosystem.bond_count,
+                  active_bonds:    @ecosystem.active_bonds.size,
+                  network_density: @ecosystem.network_density
+                }
+              end
+
+              def find_partners(subsystem_id, min_benefit_ratio: 0.0)
+                @ecosystem.symbiotic_web(subsystem_id)
+                          .reject(&:dormant?)
+                          .select { |b| b.benefit_ratio >= min_benefit_ratio }
+                          .sort_by { |b| -b.strength }
+                          .map do |b|
+                            b.to_h.merge(partner: b.partner_of(subsystem_id))
+                          end
+              end
+
+              def detect_parasites(strength_threshold: 0.0)
+                @ecosystem.all_bonds
+                          .select { |b| b.relationship_type == :parasitic }
+                          .reject(&:dormant?)
+                          .select { |b| b.strength >= strength_threshold }
+                          .sort_by(&:benefit_ratio)
+                          .map(&:to_h)
+              end
+
+              def ecosystem_report
+                bonds_by_type = Constants::RELATIONSHIP_TYPES.to_h do |type|
+                  count = @ecosystem.all_bonds.count { |b| b.relationship_type == type && !b.dormant? }
+                  [type, count]
+                end
+
+                health    = measure_ecosystem_health
+                strongest = @ecosystem.most_beneficial&.to_h
+                weakest   = @ecosystem.most_parasitic&.to_h
+
+                {
+                  health:          health,
+                  bonds_by_type:   bonds_by_type,
+                  most_beneficial: strongest,
+                  most_parasitic:  weakest,
+                  total_bonds:     @ecosystem.bond_count,
+                  dormant_bonds:   @ecosystem.all_bonds.count(&:dormant?)
+                }
+              end
+
+              def decay_all
+                decayed = @ecosystem.decay_all!
+                { decayed: decayed, health_after: measure_ecosystem_health }
+              end
+
+              attr_reader :ecosystem
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/social/symbiosis/helpers/symbiotic_bond.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'time'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module Symbiosis
+          module Helpers
+            class SymbioticBond
+              attr_reader :bond_id, :subsystem_a, :subsystem_b, :relationship_type,
+                          :benefit_ratio, :activation_count, :created_at, :last_activated_at
+
+              def initialize(subsystem_a:, subsystem_b:, relationship_type:, strength: nil, benefit_ratio: nil)
+                validate_relationship_type!(relationship_type)
+
+                @bond_id           = SecureRandom.uuid
+                @subsystem_a       = subsystem_a
+                @subsystem_b       = subsystem_b
+                @relationship_type = relationship_type
+                @strength          = (strength || Constants::DEFAULT_STRENGTH).clamp(
+                  Constants::MIN_STRENGTH, Constants::MAX_STRENGTH
+                )
+                @benefit_ratio     = benefit_ratio || default_benefit_ratio(relationship_type)
+                @activation_count  = 0
+                @created_at        = Time.now.utc
+                @last_activated_at = nil
+              end
+
+              def strength
+                @strength.round(10)
+              end
+
+              def activate!(amount: 0.05)
+                delta = amount.clamp(0.0, 1.0)
+                @strength = (@strength + delta).clamp(Constants::MIN_STRENGTH, Constants::MAX_STRENGTH)
+                @activation_count += 1
+                @last_activated_at = Time.now.utc
+                self
+              end
+
+              def decay!(rate: Constants::BOND_DECAY)
+                @strength = (@strength - rate).clamp(Constants::MIN_STRENGTH, Constants::MAX_STRENGTH)
+                self
+              end
+
+              def dormant?
+                @strength <= Constants::DORMANT_THRESHOLD
+              end
+
+              def strong?
+                @strength >= Constants::STRONG_THRESHOLD
+              end
+
+              def strength_label
+                Constants::INTERACTION_STRENGTHS.each do |range, label|
+                  return label if range.cover?(@strength)
+                end
+                :dormant
+              end
+
+              def involves?(subsystem_id)
+                [@subsystem_a, @subsystem_b].include?(subsystem_id)
+              end
+
+              def partner_of(subsystem_id)
+                return @subsystem_b if @subsystem_a == subsystem_id
+                return @subsystem_a if @subsystem_b == subsystem_id
+
+                nil
+              end
+
+              def to_h
+                {
+                  bond_id:           @bond_id,
+                  subsystem_a:       @subsystem_a,
+                  subsystem_b:       @subsystem_b,
+                  relationship_type: @relationship_type,
+                  strength:          strength,
+                  strength_label:    strength_label,
+                  benefit_ratio:     @benefit_ratio,
+                  activation_count:  @activation_count,
+                  dormant:           dormant?,
+                  strong:            strong?,
+                  created_at:        @created_at.iso8601,
+                  last_activated_at: @last_activated_at&.iso8601
+                }
+              end
+
+              private
+
+              def validate_relationship_type!(type)
+                return if Constants::RELATIONSHIP_TYPES.include?(type)
+
+                raise ArgumentError, "unknown relationship_type: #{type.inspect}. " \
+                                     "Must be one of #{Constants::RELATIONSHIP_TYPES.inspect}"
+              end
+
+              def default_benefit_ratio(type)
+                range = Constants::BENEFIT_RATIO_RANGES.fetch(type)
+                mid = (range.min + range.max) / 2.0
+                mid.round(10)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/social/symbiosis/runners/cognitive_symbiosis.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module Symbiosis
+          module Runners
+            module CognitiveSymbiosis
+              extend self
+
+              include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+              def create_bond(subsystem_a:, subsystem_b:, relationship_type:, strength: nil, benefit_ratio: nil, engine: nil, **)
+                eng = engine || default_engine
+                result = eng.create_bond(
+                  subsystem_a:       subsystem_a,
+                  subsystem_b:       subsystem_b,
+                  relationship_type: relationship_type.to_sym,
+                  strength:          strength,
+                  benefit_ratio:     benefit_ratio
+                )
+                msg = if result[:created]
+                        "[symbiosis] bond created: #{subsystem_a}<->#{subsystem_b} type=#{relationship_type}"
+                      else
+                        "[symbiosis] bond skipped: #{result[:reason]}"
+                      end
+                Legion::Logging.debug msg if defined?(Legion::Logging)
+                { success: result[:created], **result }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def activate(subsystem_a:, subsystem_b:, amount: 0.05, engine: nil, **)
+                eng = engine || default_engine
+                result = eng.activate_interaction(
+                  subsystem_a: subsystem_a,
+                  subsystem_b: subsystem_b,
+                  amount:      amount.clamp(0.0, 1.0)
+                )
+                found = result.fetch(:found, false)
+                Legion::Logging.debug "[symbiosis] activate #{subsystem_a}<->#{subsystem_b} found=#{found}" if defined?(Legion::Logging)
+                { success: found, **result }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def health_status(engine: nil, **)
+                eng = engine || default_engine
+                health = eng.measure_ecosystem_health
+                Legion::Logging.debug "[symbiosis] health score=#{health[:score]} label=#{health[:label]}" if defined?(Legion::Logging)
+                { success: true, **health }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def list_bonds(subsystem_id: nil, relationship_type: nil, engine: nil, **)
+                eng = engine || default_engine
+                bonds = if subsystem_id
+                          eng.ecosystem.symbiotic_web(subsystem_id).map(&:to_h)
+                        else
+                          eng.ecosystem.all_bonds.map(&:to_h)
+                        end
+
+                bonds = bonds.select { |b| b[:relationship_type] == relationship_type.to_sym } if relationship_type
+                Legion::Logging.debug "[symbiosis] list_bonds count=#{bonds.size}" if defined?(Legion::Logging)
+                { success: true, bonds: bonds, count: bonds.size }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def detect_parasites(strength_threshold: 0.0, engine: nil, **)
+                eng = engine || default_engine
+                parasites = eng.detect_parasites(strength_threshold: strength_threshold.clamp(0.0, 1.0))
+                Legion::Logging.debug "[symbiosis] detect_parasites count=#{parasites.size}" if defined?(Legion::Logging)
+                { success: true, parasites: parasites, count: parasites.size }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def ecosystem_report(engine: nil, **)
+                eng = engine || default_engine
+                report = eng.ecosystem_report
+                Legion::Logging.debug "[symbiosis] ecosystem_report health=#{report.dig(:health, :label)}" if defined?(Legion::Logging)
+                { success: true, **report }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              private
+
+              def default_engine
+                @default_engine ||= Helpers::SymbiosisEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+require 'legion/extensions/agentic/social/symbiosis/version'
+require 'legion/extensions/agentic/social/symbiosis/helpers/constants'
+require 'legion/extensions/agentic/social/symbiosis/helpers/symbiotic_bond'
+require 'legion/extensions/agentic/social/symbiosis/helpers/ecosystem'
+require 'legion/extensions/agentic/social/symbiosis/helpers/symbiosis_engine'
+require 'legion/extensions/agentic/social/symbiosis/runners/cognitive_symbiosis'
+require 'legion/extensions/agentic/social/symbiosis/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module Symbiosis
+        end
+      end
+    end
+  end
+end