lex-agentic-social 0.1.0

data/lib/legion/extensions/agentic/social/perspective_shifting/helpers/perspective.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module PerspectiveShifting
+          module Helpers
+            class Perspective
+              attr_reader :id, :name, :perspective_type, :priorities,
+                          :expertise_domains, :empathy_level, :bias_toward, :created_at
+
+              def initialize(name:, perspective_type:, priorities: [], expertise_domains: [],
+                             empathy_level: Constants::DEFAULT_EMPATHY, bias_toward: nil)
+                @id               = SecureRandom.uuid
+                @name             = name
+                @perspective_type = perspective_type
+                @priorities       = Array(priorities)
+                @expertise_domains = Array(expertise_domains)
+                @empathy_level    = empathy_level.clamp(0.0, 1.0)
+                @bias_toward      = bias_toward
+                @created_at       = Time.now.utc
+              end
+
+              def to_h
+                {
+                  id:                @id,
+                  name:              @name,
+                  perspective_type:  @perspective_type,
+                  priorities:        @priorities,
+                  expertise_domains: @expertise_domains,
+                  empathy_level:     @empathy_level.round(10),
+                  bias_toward:       @bias_toward,
+                  created_at:        @created_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/social/perspective_shifting/helpers/perspective_view.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module PerspectiveShifting
+          module Helpers
+            class PerspectiveView
+              attr_reader :id, :situation_id, :perspective_id, :valence,
+                          :concerns, :opportunities, :confidence, :created_at
+
+              def initialize(situation_id:, perspective_id:, valence: 0.0,
+                             concerns: [], opportunities: [], confidence: 0.5)
+                @id             = SecureRandom.uuid
+                @situation_id   = situation_id
+                @perspective_id = perspective_id
+                @valence        = valence.clamp(-1.0, 1.0).round(10)
+                @concerns       = Array(concerns)
+                @opportunities  = Array(opportunities)
+                @confidence     = confidence.clamp(0.0, 1.0).round(10)
+                @created_at     = Time.now.utc
+              end
+
+              def positive?
+                @valence > 0.1
+              end
+
+              def negative?
+                @valence < -0.1
+              end
+
+              def neutral?
+                !positive? && !negative?
+              end
+
+              def to_h
+                {
+                  id:             @id,
+                  situation_id:   @situation_id,
+                  perspective_id: @perspective_id,
+                  valence:        @valence,
+                  concerns:       @concerns,
+                  opportunities:  @opportunities,
+                  confidence:     @confidence,
+                  created_at:     @created_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/social/perspective_shifting/helpers/shifting_engine.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module PerspectiveShifting
+          module Helpers
+            class ShiftingEngine
+              attr_reader :perspectives, :situations
+
+              def initialize
+                @perspectives = {}
+                @situations   = {}
+              end
+
+              def add_perspective(name:, type: :stakeholder, priorities: [], empathy: Constants::DEFAULT_EMPATHY,
+                                  bias: nil, expertise_domains: [])
+                return { error: :too_many_perspectives } if @perspectives.size >= Constants::MAX_PERSPECTIVES
+                return { error: :invalid_type } unless Constants::PERSPECTIVE_TYPES.include?(type)
+
+                p = Perspective.new(
+                  name:              name,
+                  perspective_type:  type,
+                  priorities:        priorities,
+                  expertise_domains: expertise_domains,
+                  empathy_level:     empathy,
+                  bias_toward:       bias
+                )
+                @perspectives[p.id] = p
+                p
+              end
+
+              def add_situation(content:)
+                return { error: :too_many_situations } if @situations.size >= Constants::MAX_SITUATIONS
+
+                id = SecureRandom.uuid
+                @situations[id] = { id: id, content: content, views: [], created_at: Time.now.utc }
+                @situations[id]
+              end
+
+              def generate_view(situation_id:, perspective_id:, valence: 0.0,
+                                concerns: [], opportunities: [], confidence: 0.5)
+                situation = @situations[situation_id]
+                perspective = @perspectives[perspective_id]
+
+                return { error: :situation_not_found } unless situation
+                return { error: :perspective_not_found } unless perspective
+                return { error: :too_many_views } if situation[:views].size >= Constants::MAX_VIEWS_PER_SITUATION
+
+                view = PerspectiveView.new(
+                  situation_id:   situation_id,
+                  perspective_id: perspective_id,
+                  valence:        valence,
+                  concerns:       concerns,
+                  opportunities:  opportunities,
+                  confidence:     confidence
+                )
+                situation[:views] << view
+                view
+              end
+
+              def views_for_situation(situation_id:)
+                situation = @situations[situation_id]
+                return [] unless situation
+
+                situation[:views]
+              end
+
+              def perspective_agreement(situation_id:)
+                views = views_for_situation(situation_id: situation_id)
+                return 0.0 if views.size < Constants::MIN_PERSPECTIVES_FOR_SYNTHESIS
+
+                valences = views.map(&:valence)
+                mean     = valences.sum / valences.size.to_f
+                variance = valences.sum { |v| (v - mean)**2 } / valences.size.to_f
+                std_dev  = Math.sqrt(variance)
+
+                # Agreement is inverse of normalized std_dev (max std_dev is 1.0 for symmetric ±1 distribution)
+                (1.0 - std_dev).clamp(0.0, 1.0).round(10)
+              end
+
+              def blind_spots(situation_id:)
+                views = views_for_situation(situation_id: situation_id)
+                applied_ids = views.map(&:perspective_id).uniq
+                applied_types = applied_ids.filter_map { |pid| @perspectives[pid]&.perspective_type }.uniq
+                Constants::PERSPECTIVE_TYPES - applied_types
+              end
+
+              def coverage_score(situation_id:)
+                views = views_for_situation(situation_id: situation_id)
+                return 0.0 if @perspectives.empty?
+
+                applied_count = views.map(&:perspective_id).uniq.size
+                (applied_count.to_f / @perspectives.size).clamp(0.0, 1.0).round(10)
+              end
+
+              def dominant_view(situation_id:)
+                views = views_for_situation(situation_id: situation_id)
+                return nil if views.empty?
+
+                views.max_by(&:confidence)
+              end
+
+              def synthesize(situation_id:)
+                views = views_for_situation(situation_id: situation_id)
+                return { error: :insufficient_views } if views.size < Constants::MIN_PERSPECTIVES_FOR_SYNTHESIS
+
+                total_confidence = views.sum(&:confidence)
+                return { error: :zero_confidence } if total_confidence.zero?
+
+                weighted_valence = views.sum { |v| v.valence * v.confidence } / total_confidence
+                all_concerns     = views.flat_map(&:concerns).uniq
+                all_opportunities = views.flat_map(&:opportunities).uniq
+                agreement = perspective_agreement(situation_id: situation_id)
+
+                {
+                  situation_id:     situation_id,
+                  weighted_valence: weighted_valence.round(10),
+                  concerns:         all_concerns,
+                  opportunities:    all_opportunities,
+                  agreement:        agreement.round(10),
+                  agreement_label:  Constants.agreement_label(agreement),
+                  view_count:       views.size,
+                  coverage_score:   coverage_score(situation_id: situation_id),
+                  coverage_label:   Constants.coverage_label(coverage_score(situation_id: situation_id))
+                }
+              end
+
+              def most_divergent_pair(situation_id:)
+                views = views_for_situation(situation_id: situation_id)
+                return nil if views.size < 2
+
+                max_diff = -1.0
+                pair     = nil
+
+                views.combination(2) do |a, b|
+                  diff = (a.valence - b.valence).abs
+                  if diff > max_diff
+                    max_diff = diff
+                    pair     = [a, b]
+                  end
+                end
+
+                pair
+              end
+
+              def to_h
+                {
+                  perspective_count: @perspectives.size,
+                  situation_count:   @situations.size,
+                  perspectives:      @perspectives.values.map(&:to_h),
+                  situations:        @situations.values.map do |s|
+                    s.merge(views: s[:views].map(&:to_h))
+                  end
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module PerspectiveShifting
+          module Runners
+            module PerspectiveShifting
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              # --- Perspective management ---
+
+              def add_perspective(name:, type: :stakeholder, priorities: [], empathy: Helpers::Constants::DEFAULT_EMPATHY,
+                                  bias: nil, expertise_domains: [], engine: nil, **)
+                eng    = engine || shifting_engine
+                result = eng.add_perspective(name: name, type: type, priorities: priorities,
+                                             empathy: empathy, bias: bias, expertise_domains: expertise_domains)
+                return { success: false, error: result[:error] } if result.is_a?(Hash) && result[:error]
+
+                Legion::Logging.debug "[perspective_shifting] added perspective name=#{name} type=#{type} id=#{result.id[0..7]}"
+                { success: true, perspective: result.to_h }
+              end
+
+              def list_perspectives(engine: nil, **)
+                eng   = engine || shifting_engine
+                persp = eng.perspectives.values.map(&:to_h)
+                Legion::Logging.debug "[perspective_shifting] list_perspectives count=#{persp.size}"
+                { success: true, perspectives: persp, count: persp.size }
+              end
+
+              def get_perspective(perspective_id:, engine: nil, **)
+                eng   = engine || shifting_engine
+                persp = eng.perspectives[perspective_id]
+                if persp
+                  { success: true, found: true, perspective: persp.to_h }
+                else
+                  Legion::Logging.debug "[perspective_shifting] perspective not found id=#{perspective_id[0..7]}"
+                  { success: false, found: false }
+                end
+              end
+
+              # --- Situation management ---
+
+              def add_situation(content:, engine: nil, **)
+                eng    = engine || shifting_engine
+                result = eng.add_situation(content: content)
+                return { success: false, error: result[:error] } if result.is_a?(Hash) && result[:error]
+
+                Legion::Logging.debug "[perspective_shifting] added situation id=#{result[:id][0..7]}"
+                { success: true, situation_id: result[:id], content: result[:content] }
+              end
+
+              def list_situations(engine: nil, **)
+                eng  = engine || shifting_engine
+                sits = eng.situations.values.map { |s| s.merge(views: s[:views].map(&:to_h)) }
+                Legion::Logging.debug "[perspective_shifting] list_situations count=#{sits.size}"
+                { success: true, situations: sits, count: sits.size }
+              end
+
+              # --- View generation and retrieval ---
+
+              def generate_view(situation_id:, perspective_id:, valence: 0.0,
+                                concerns: [], opportunities: [], confidence: 0.5, engine: nil, **)
+                eng    = engine || shifting_engine
+                result = eng.generate_view(
+                  situation_id:   situation_id,
+                  perspective_id: perspective_id,
+                  valence:        valence,
+                  concerns:       concerns,
+                  opportunities:  opportunities,
+                  confidence:     confidence
+                )
+                return { success: false, error: result[:error] } if result.is_a?(Hash) && result[:error]
+
+                Legion::Logging.debug "[perspective_shifting] generated view id=#{result.id[0..7]} " \
+                                      "valence=#{result.valence.round(2)}"
+                { success: true, view: result.to_h }
+              end
+
+              def views_for_situation(situation_id:, engine: nil, **)
+                eng   = engine || shifting_engine
+                views = eng.views_for_situation(situation_id: situation_id)
+                Legion::Logging.debug "[perspective_shifting] views_for_situation id=#{situation_id[0..7]} count=#{views.size}"
+                { success: true, views: views.map(&:to_h), count: views.size }
+              end
+
+              # --- Analysis ---
+
+              def perspective_agreement(situation_id:, engine: nil, **)
+                eng       = engine || shifting_engine
+                score     = eng.perspective_agreement(situation_id: situation_id)
+                label     = Helpers::Constants.agreement_label(score)
+                Legion::Logging.debug "[perspective_shifting] agreement situation=#{situation_id[0..7]} score=#{score.round(2)} label=#{label}"
+                { success: true, situation_id: situation_id, agreement: score, label: label }
+              end
+
+              def blind_spots(situation_id:, engine: nil, **)
+                eng   = engine || shifting_engine
+                spots = eng.blind_spots(situation_id: situation_id)
+                Legion::Logging.debug "[perspective_shifting] blind_spots situation=#{situation_id[0..7]} count=#{spots.size}"
+                { success: true, situation_id: situation_id, blind_spots: spots, count: spots.size }
+              end
+
+              def coverage_score(situation_id:, engine: nil, **)
+                eng   = engine || shifting_engine
+                score = eng.coverage_score(situation_id: situation_id)
+                label = Helpers::Constants.coverage_label(score)
+                Legion::Logging.debug "[perspective_shifting] coverage situation=#{situation_id[0..7]} score=#{score.round(2)} label=#{label}"
+                { success: true, situation_id: situation_id, coverage: score, label: label }
+              end
+
+              def dominant_view(situation_id:, engine: nil, **)
+                eng  = engine || shifting_engine
+                view = eng.dominant_view(situation_id: situation_id)
+                if view
+                  Legion::Logging.debug "[perspective_shifting] dominant_view situation=#{situation_id[0..7]} confidence=#{view.confidence.round(2)}"
+                  { success: true, found: true, view: view.to_h }
+                else
+                  { success: true, found: false }
+                end
+              end
+
+              def synthesize(situation_id:, engine: nil, **)
+                eng    = engine || shifting_engine
+                result = eng.synthesize(situation_id: situation_id)
+                return { success: false, error: result[:error] } if result[:error]
+
+                Legion::Logging.info "[perspective_shifting] synthesized situation=#{situation_id[0..7]} " \
+                                     "valence=#{result[:weighted_valence].round(2)} views=#{result[:view_count]}"
+                result.merge(success: true)
+              end
+
+              def most_divergent_pair(situation_id:, engine: nil, **)
+                eng  = engine || shifting_engine
+                pair = eng.most_divergent_pair(situation_id: situation_id)
+                unless pair
+                  Legion::Logging.debug '[perspective_shifting] most_divergent_pair: not enough views'
+                  return { success: true, found: false }
+                end
+
+                divergence = (pair[0].valence - pair[1].valence).abs.round(10)
+                Legion::Logging.debug "[perspective_shifting] most_divergent_pair divergence=#{divergence.round(2)}"
+                { success: true, found: true, views: pair.map(&:to_h), divergence: divergence }
+              end
+
+              def engine_status(engine: nil, **)
+                eng = engine || shifting_engine
+                Legion::Logging.debug '[perspective_shifting] engine_status'
+                { success: true }.merge(eng.to_h)
+              end
+
+              private
+
+              def shifting_engine
+                @shifting_engine ||= Helpers::ShiftingEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/social/perspective_shifting/version'
+require 'legion/extensions/agentic/social/perspective_shifting/helpers/constants'
+require 'legion/extensions/agentic/social/perspective_shifting/helpers/perspective'
+require 'legion/extensions/agentic/social/perspective_shifting/helpers/perspective_view'
+require 'legion/extensions/agentic/social/perspective_shifting/helpers/shifting_engine'
+require 'legion/extensions/agentic/social/perspective_shifting/runners/perspective_shifting'
+require 'legion/extensions/agentic/social/perspective_shifting/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module PerspectiveShifting
+        end
+      end
+    end
+  end
+end

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

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

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

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