lex-social 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4fd404736b85974600feaa1f44e7aaf419034288b9f8d243758d8700d492ac81
+  data.tar.gz: 5807d2f6fcb4ba8ec32add6876e44293dea24da7423868a4fecacc2d0803fc7a
+SHA512:
+  metadata.gz: d6f1779cd6f358569921d73597b3764e9809115b68bc6096d5b320ac4f8b642f00292ba29fe1d8d225b7fdfb30a1b3754ccd492ef0e96144f6a5cd8bf2d65c8a
+  data.tar.gz: a358618950db736b213eb48173bbb898720df1c88857098a65f7adf2149d07ba420adadc4a57c2ebe43dcea02a62ea025cd9a7f0ab82393d34342cb250990704

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/social/helpers/constants'
+require 'legion/extensions/social/helpers/social_graph'
+require 'legion/extensions/social/runners/social'
+
+module Legion
+  module Extensions
+    module Social
+      class Client
+        include Runners::Social
+
+        attr_reader :social_graph
+
+        def initialize(social_graph: nil, **)
+          @social_graph = social_graph || Helpers::SocialGraph.new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Social
+      module Helpers
+        module Constants
+          # Social roles an agent can hold in a group
+          ROLES = %i[
+            leader
+            contributor
+            specialist
+            observer
+            mentor
+            newcomer
+          ].freeze
+
+          # Group relationship types
+          RELATIONSHIP_TYPES = %i[
+            ally
+            collaborator
+            neutral
+            competitor
+            adversary
+          ].freeze
+
+          # Reputation dimensions
+          REPUTATION_DIMENSIONS = {
+            reliability: { weight: 0.25, description: 'Follows through on commitments' },
+            competence:  { weight: 0.25, description: 'Quality of work output' },
+            benevolence: { weight: 0.20, description: 'Acts in others interests' },
+            integrity:   { weight: 0.15, description: 'Consistency between words and actions' },
+            influence:   { weight: 0.15, description: 'Ability to shape group direction' }
+          }.freeze
+
+          # EMA alpha for reputation updates
+          REPUTATION_ALPHA = 0.1
+
+          # Social standing thresholds
+          STANDING_LEVELS = {
+            exemplary:  0.8,
+            respected:  0.6,
+            neutral:    0.4,
+            marginal:   0.2,
+            ostracized: 0.0
+          }.freeze
+
+          # Group cohesion thresholds
+          COHESION_LEVELS = {
+            tight:     0.7,
+            moderate:  0.5,
+            loose:     0.3,
+            fractured: 0.0
+          }.freeze
+
+          # Maximum tracked groups
+          MAX_GROUPS = 20
+
+          # Maximum members per group
+          MAX_GROUP_MEMBERS = 50
+
+          # Social norms violation types
+          NORM_VIOLATIONS = %i[
+            free_riding
+            defection
+            deception
+            dominance_abuse
+            exclusion
+          ].freeze
+
+          # Reciprocity tracking window
+          RECIPROCITY_WINDOW = 50
+
+          # Social influence decay rate
+          INFLUENCE_DECAY = 0.02
+        end
+      end
+    end
+  end
+end

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

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

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

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

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

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

data/lib/legion/extensions/social.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/social/version'
+require 'legion/extensions/social/helpers/constants'
+require 'legion/extensions/social/helpers/social_graph'
+require 'legion/extensions/social/runners/social'
+require 'legion/extensions/social/client'
+
+module Legion
+  module Extensions
+    module Social
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined?(:Core)
+    end
+  end
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: lex-social
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Matthew Iverson
+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: Models social roles, group membership, reputation, and collective behavior
+  in multi-agent systems
+email:
+- matt@legionIO.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/legion/extensions/social.rb
+- lib/legion/extensions/social/client.rb
+- lib/legion/extensions/social/helpers/constants.rb
+- lib/legion/extensions/social/helpers/social_graph.rb
+- lib/legion/extensions/social/runners/social.rb
+- lib/legion/extensions/social/version.rb
+homepage: https://github.com/LegionIO/lex-social
+licenses:
+- MIT
+metadata:
+  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: Social identity and group dynamics for LegionIO cognitive agents
+test_files: []