lex-agentic-social 0.1.0

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

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module Social
+          module Helpers
+            class SocialGraph
+              attr_reader :groups, :reputation_scores, :reciprocity_ledger
+
+              def initialize
+                @groups = {}
+                @reputation_scores = {}
+                @reciprocity_ledger = []
+              end
+
+              def join_group(group_id:, role: :contributor, members: [])
+                @groups[group_id] ||= {
+                  role:       role,
+                  members:    members.dup,
+                  joined_at:  Time.now.utc,
+                  norms:      [],
+                  cohesion:   0.5,
+                  violations: []
+                }
+                trim_groups
+                @groups[group_id]
+              end
+
+              def leave_group(group_id)
+                @groups.delete(group_id)
+              end
+
+              def update_role(group_id:, role:)
+                return nil unless @groups.key?(group_id)
+                return nil unless Constants::ROLES.include?(role)
+
+                @groups[group_id][:role] = role
+              end
+
+              def update_reputation(agent_id:, dimension:, signal:)
+                return nil unless Constants::REPUTATION_DIMENSIONS.key?(dimension)
+
+                @reputation_scores[agent_id] ||= Constants::REPUTATION_DIMENSIONS.keys.to_h { |d| [d, 0.5] }
+                current = @reputation_scores[agent_id][dimension]
+                @reputation_scores[agent_id][dimension] = ema(current, signal.clamp(0.0, 1.0), Constants::REPUTATION_ALPHA)
+              end
+
+              def reputation_for(agent_id)
+                scores = @reputation_scores[agent_id]
+                return nil unless scores
+
+                composite = 0.0
+                Constants::REPUTATION_DIMENSIONS.each do |dim, config|
+                  composite += scores[dim] * config[:weight]
+                end
+
+                {
+                  agent_id:  agent_id,
+                  scores:    scores.transform_values { |v| v.round(4) },
+                  composite: composite.round(4),
+                  standing:  classify_standing(composite)
+                }
+              end
+
+              def social_standing
+                return :neutral if @reputation_scores.empty?
+
+                all_composites = @reputation_scores.map { |id, _| reputation_for(id)[:composite] }
+                avg = all_composites.sum / all_composites.size.to_f
+                classify_standing(avg)
+              end
+
+              def record_reciprocity(agent_id:, action:, direction:)
+                @reciprocity_ledger << {
+                  agent_id:  agent_id,
+                  action:    action,
+                  direction: direction,
+                  at:        Time.now.utc
+                }
+                @reciprocity_ledger.shift while @reciprocity_ledger.size > Constants::RECIPROCITY_WINDOW
+              end
+
+              def reciprocity_balance(agent_id)
+                entries = @reciprocity_ledger.select { |e| e[:agent_id] == agent_id }
+                given = entries.count { |e| e[:direction] == :given }
+                received = entries.count { |e| e[:direction] == :received }
+
+                { given: given, received: received, balance: given - received }
+              end
+
+              def record_violation(group_id:, type:, agent_id:)
+                return nil unless @groups.key?(group_id)
+                return nil unless Constants::NORM_VIOLATIONS.include?(type)
+
+                violation = { type: type, agent_id: agent_id, at: Time.now.utc }
+                @groups[group_id][:violations] << violation
+                reduce_cohesion(group_id, 0.1)
+                violation
+              end
+
+              def group_cohesion(group_id)
+                return nil unless @groups.key?(group_id)
+
+                @groups[group_id][:cohesion]
+              end
+
+              def update_cohesion(group_id:, signal:)
+                return nil unless @groups.key?(group_id)
+
+                current = @groups[group_id][:cohesion]
+                @groups[group_id][:cohesion] = ema(current, signal.clamp(0.0, 1.0), Constants::REPUTATION_ALPHA)
+              end
+
+              def classify_cohesion(group_id)
+                cohesion = group_cohesion(group_id)
+                return nil unless cohesion
+
+                Constants::COHESION_LEVELS.each do |level, threshold|
+                  return level if cohesion >= threshold
+                end
+                :fractured
+              end
+
+              def group_count
+                @groups.size
+              end
+
+              def agents_tracked
+                @reputation_scores.keys.size
+              end
+
+              def to_h
+                {
+                  groups:          @groups.keys,
+                  group_count:     @groups.size,
+                  agents_tracked:  agents_tracked,
+                  social_standing: social_standing,
+                  ledger_size:     @reciprocity_ledger.size
+                }
+              end
+
+              private
+
+              def ema(current, observed, alpha)
+                (current * (1.0 - alpha)) + (observed * alpha)
+              end
+
+              def classify_standing(composite)
+                Constants::STANDING_LEVELS.each do |level, threshold|
+                  return level if composite >= threshold
+                end
+                :ostracized
+              end
+
+              def reduce_cohesion(group_id, amount)
+                current = @groups[group_id][:cohesion]
+                @groups[group_id][:cohesion] = [current - amount, 0.0].max
+              end
+
+              def trim_groups
+                oldest = @groups.keys.sort_by { |k| @groups[k][:joined_at] }
+                oldest.first([@groups.size - Constants::MAX_GROUPS, 0].max).each { |k| @groups.delete(k) }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module Social
+          module Runners
+            module Social
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def update_social(tick_results: {}, **)
+                extract_social_signals(tick_results)
+
+                Legion::Logging.debug "[social] groups=#{social_graph.group_count} " \
+                                      "agents=#{social_graph.agents_tracked} standing=#{social_graph.social_standing}"
+
+                {
+                  groups:         social_graph.group_count,
+                  agents_tracked: social_graph.agents_tracked,
+                  standing:       social_graph.social_standing,
+                  ledger_size:    social_graph.reciprocity_ledger.size
+                }
+              end
+
+              def join_group(group_id:, role: :contributor, members: [], **)
+                group = social_graph.join_group(group_id: group_id, role: role, members: members)
+                Legion::Logging.info "[social] joined group=#{group_id} role=#{role}"
+                { success: true, group_id: group_id, role: role, group: group }
+              end
+
+              def leave_group(group_id:, **)
+                social_graph.leave_group(group_id)
+                Legion::Logging.info "[social] left group=#{group_id}"
+                { success: true, group_id: group_id }
+              end
+
+              def update_reputation(agent_id:, dimension:, signal:, **)
+                result = social_graph.update_reputation(agent_id: agent_id, dimension: dimension.to_sym, signal: signal)
+                return { success: false, error: 'invalid dimension' } unless result
+
+                rep = social_graph.reputation_for(agent_id)
+                Legion::Logging.debug "[social] reputation updated agent=#{agent_id} dim=#{dimension}"
+                { success: true, reputation: rep }
+              end
+
+              def agent_reputation(agent_id:, **)
+                rep = social_graph.reputation_for(agent_id)
+                return { error: 'unknown agent' } unless rep
+
+                Legion::Logging.debug "[social] reputation for #{agent_id}: #{rep[:composite]}"
+                rep
+              end
+
+              def reciprocity_status(agent_id:, **)
+                balance = social_graph.reciprocity_balance(agent_id)
+                Legion::Logging.debug "[social] reciprocity #{agent_id}: #{balance}"
+                balance
+              end
+
+              def record_exchange(agent_id:, action:, direction:, **)
+                social_graph.record_reciprocity(agent_id: agent_id, action: action, direction: direction.to_sym)
+                Legion::Logging.debug "[social] exchange agent=#{agent_id} dir=#{direction}"
+                { success: true }
+              end
+
+              def report_violation(group_id:, type:, agent_id:, **)
+                violation = social_graph.record_violation(group_id: group_id, type: type.to_sym, agent_id: agent_id)
+                return { success: false, error: 'invalid group or violation type' } unless violation
+
+                Legion::Logging.warn "[social] violation: #{type} by #{agent_id} in #{group_id}"
+                { success: true, violation: violation, cohesion: social_graph.group_cohesion(group_id)&.round(4) }
+              end
+
+              def group_status(group_id:, **)
+                return { error: 'unknown group' } unless social_graph.groups.key?(group_id)
+
+                group = social_graph.groups[group_id]
+                {
+                  group_id:       group_id,
+                  role:           group[:role],
+                  members:        group[:members].size,
+                  cohesion:       group[:cohesion].round(4),
+                  cohesion_level: social_graph.classify_cohesion(group_id),
+                  violations:     group[:violations].size
+                }
+              end
+
+              def social_status(**)
+                state = social_graph.to_h
+                Legion::Logging.debug "[social] status: #{state[:social_standing]}"
+                state
+              end
+
+              def social_stats(**)
+                Legion::Logging.debug '[social] stats'
+
+                {
+                  groups:         social_graph.group_count,
+                  agents_tracked: social_graph.agents_tracked,
+                  standing:       social_graph.social_standing,
+                  ledger_size:    social_graph.reciprocity_ledger.size,
+                  group_roles:    social_graph.groups.transform_values { |g| g[:role] }
+                }
+              end
+
+              private
+
+              def social_graph
+                @social_graph ||= Helpers::SocialGraph.new
+              end
+
+              def extract_social_signals(tick_results)
+                extract_trust_signals(tick_results)
+                extract_mesh_signals(tick_results)
+              end
+
+              def extract_trust_signals(tick_results)
+                trust_updates = tick_results.dig(:trust, :updates)
+                return unless trust_updates.is_a?(Array)
+
+                trust_updates.each do |update|
+                  social_graph.update_reputation(
+                    agent_id:  update[:agent_id],
+                    dimension: :reliability,
+                    signal:    update[:score] || 0.5
+                  )
+                end
+              end
+
+              def extract_mesh_signals(tick_results)
+                peer_count = tick_results.dig(:mesh_interface, :peer_count) || 0
+                return if peer_count.zero?
+
+                social_graph.groups.each_key do |group_id|
+                  social_graph.update_cohesion(group_id: group_id, signal: [peer_count * 0.1, 1.0].min)
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/social/social/version'
+require 'legion/extensions/agentic/social/social/helpers/constants'
+require 'legion/extensions/agentic/social/social/helpers/social_graph'
+require 'legion/extensions/agentic/social/social/runners/social'
+require 'legion/extensions/agentic/social/social/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module Social
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+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'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module SocialLearning
+          class Client
+            include Runners::SocialLearning
+
+            def initialize(engine: nil)
+              @engine = engine || Helpers::SocialLearningEngine.new
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

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

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

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

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

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