lex-agentic-social 0.1.0

data/lib/legion/extensions/agentic/social/conflict/helpers/conflict_log.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module Conflict
+          module Helpers
+            class ConflictLog
+              attr_reader :conflicts
+
+              def initialize
+                @conflicts = {}
+              end
+
+              def record(parties:, severity:, description:, posture: nil)
+                id = SecureRandom.uuid
+                @conflicts[id] = {
+                  conflict_id: id,
+                  parties:     parties,
+                  severity:    severity,
+                  posture:     posture || Severity.recommended_posture(severity),
+                  description: description,
+                  status:      :active,
+                  outcome:     nil,
+                  created_at:  Time.now.utc,
+                  resolved_at: nil,
+                  exchanges:   []
+                }
+                id
+              end
+
+              def add_exchange(conflict_id, speaker:, message:)
+                conflict = @conflicts[conflict_id]
+                return nil unless conflict
+
+                conflict[:exchanges] << { speaker: speaker, message: message, at: Time.now.utc }
+              end
+
+              def resolve(conflict_id, outcome:, resolution_notes: nil)
+                conflict = @conflicts[conflict_id]
+                return nil unless conflict
+
+                conflict[:status] = :resolved
+                conflict[:outcome] = outcome
+                conflict[:resolution_notes] = resolution_notes
+                conflict[:resolved_at] = Time.now.utc
+                conflict
+              end
+
+              def active_conflicts
+                @conflicts.values.select { |c| c[:status] == :active }
+              end
+
+              def get(conflict_id)
+                @conflicts[conflict_id]
+              end
+
+              def count
+                @conflicts.size
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/social/conflict/helpers/llm_enhancer.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module Conflict
+          module Helpers
+            module LlmEnhancer
+              SYSTEM_PROMPT = <<~PROMPT
+                You are the conflict mediation processor for an autonomous AI agent built on LegionIO.
+                You analyze disagreements between the agent and human partners, then suggest resolution approaches.
+                Be neutral, constructive, and specific. Focus on finding common ground and actionable next steps.
+                Do not take sides. Identify the underlying needs behind each position.
+              PROMPT
+
+              module_function
+
+              def available?
+                defined?(Legion::LLM) && Legion::LLM.respond_to?(:started?) && Legion::LLM.started?
+              rescue StandardError
+                false
+              end
+
+              def suggest_resolution(description:, severity:, exchanges:)
+                prompt = build_suggest_resolution_prompt(description: description, severity: severity, exchanges: exchanges)
+                response = llm_ask(prompt)
+                parse_suggest_resolution_response(response)
+              rescue StandardError => e
+                Legion::Logging.warn "[conflict:llm] suggest_resolution failed: #{e.message}"
+                nil
+              end
+
+              def analyze_stale_conflict(description:, severity:, age_hours:, exchange_count:)
+                prompt = build_analyze_stale_conflict_prompt(
+                  description:    description,
+                  severity:       severity,
+                  age_hours:      age_hours,
+                  exchange_count: exchange_count
+                )
+                response = llm_ask(prompt)
+                parse_analyze_stale_conflict_response(response)
+              rescue StandardError => e
+                Legion::Logging.warn "[conflict:llm] analyze_stale_conflict failed: #{e.message}"
+                nil
+              end
+
+              # --- Private helpers ---
+
+              def llm_ask(prompt)
+                chat = Legion::LLM.chat
+                chat.with_instructions(SYSTEM_PROMPT)
+                chat.ask(prompt)
+              end
+              private_class_method :llm_ask
+
+              def build_suggest_resolution_prompt(description:, severity:, exchanges:)
+                exchange_lines = exchanges.map { |e| "[#{e[:speaker]}]: #{e[:message]}" }.join("\n")
+
+                <<~PROMPT
+                  Analyze this conflict and suggest a resolution.
+
+                  DESCRIPTION: #{description}
+                  SEVERITY: #{severity}
+                  EXCHANGE HISTORY (#{exchanges.size} exchanges):
+                  #{exchange_lines}
+
+                  Suggest a constructive resolution approach.
+
+                  Format EXACTLY as:
+                  OUTCOME: resolved | deferred | escalated
+                  NOTES: <2-3 sentences describing the resolution approach and next steps>
+                PROMPT
+              end
+              private_class_method :build_suggest_resolution_prompt
+
+              def parse_suggest_resolution_response(response)
+                return nil unless response&.content
+
+                text = response.content
+                outcome_match = text.match(/OUTCOME:\s*(resolved|deferred|escalated)/i)
+                notes_match   = text.match(/NOTES:\s*(.+)/im)
+
+                return nil unless outcome_match && notes_match
+
+                outcome = outcome_match.captures.first.strip.downcase.to_sym
+                notes   = notes_match.captures.first.strip
+
+                { resolution_notes: notes, suggested_outcome: outcome }
+              end
+              private_class_method :parse_suggest_resolution_response
+
+              def build_analyze_stale_conflict_prompt(description:, severity:, age_hours:, exchange_count:)
+                <<~PROMPT
+                  A conflict has been unresolved for #{age_hours.round(1)} hours with #{exchange_count} exchanges.
+
+                  DESCRIPTION: #{description}
+                  SEVERITY: #{severity}
+
+                  Recommend how to proceed with this stale conflict.
+
+                  Format EXACTLY as:
+                  RECOMMENDATION: escalate | retry | close
+                  ANALYSIS: <2-3 sentences explaining the recommendation>
+                PROMPT
+              end
+              private_class_method :build_analyze_stale_conflict_prompt
+
+              def parse_analyze_stale_conflict_response(response)
+                return nil unless response&.content
+
+                text = response.content
+                rec_match      = text.match(/RECOMMENDATION:\s*(escalate|retry|close)/i)
+                analysis_match = text.match(/ANALYSIS:\s*(.+)/im)
+
+                return nil unless rec_match && analysis_match
+
+                recommendation = rec_match.captures.first.strip.downcase.to_sym
+                analysis       = analysis_match.captures.first.strip
+
+                { analysis: analysis, recommendation: recommendation }
+              end
+              private_class_method :parse_analyze_stale_conflict_response
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/social/conflict/helpers/severity.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module Conflict
+          module Helpers
+            module Severity
+              LEVELS = %i[low medium high critical].freeze
+              POSTURES = %i[speak_once persistent_engagement stubborn_presence].freeze
+
+              # Posture selection thresholds
+              PERSISTENT_THRESHOLD = :high
+              STUBBORN_THRESHOLD   = :critical
+
+              LEVEL_ORDER             = { low: 0, medium: 1, high: 2, critical: 3 }.freeze
+              STALE_CONFLICT_TIMEOUT  = 86_400 # 24 hours
+
+              module_function
+
+              def valid_level?(level)
+                LEVELS.include?(level)
+              end
+
+              def valid_posture?(posture)
+                POSTURES.include?(posture)
+              end
+
+              def recommended_posture(severity)
+                case severity
+                when :critical then :stubborn_presence
+                when :high     then :persistent_engagement
+                else :speak_once
+                end
+              end
+
+              def severity_gte?(left, right)
+                LEVEL_ORDER.fetch(left, 0) >= LEVEL_ORDER.fetch(right, 0)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module Conflict
+          module Runners
+            module Conflict
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def register_conflict(parties:, severity:, description:, **)
+                return { error: :invalid_severity, valid: Helpers::Severity::LEVELS } unless Helpers::Severity.valid_level?(severity)
+
+                id = conflict_log.record(parties: parties, severity: severity, description: description)
+                conflict = conflict_log.get(id)
+                Legion::Logging.info "[conflict] registered: id=#{id[0..7]} severity=#{severity} posture=#{conflict[:posture]} parties=#{parties.join(',')}"
+                { conflict_id: id, severity: severity, posture: conflict[:posture] }
+              end
+
+              def add_exchange(conflict_id:, speaker:, message:, **)
+                result = conflict_log.add_exchange(conflict_id, speaker: speaker, message: message)
+                if result
+                  Legion::Logging.debug "[conflict] exchange: id=#{conflict_id[0..7]} speaker=#{speaker}"
+                  { recorded: true }
+                else
+                  Legion::Logging.debug "[conflict] exchange failed: id=#{conflict_id[0..7]} not found"
+                  { error: :not_found }
+                end
+              end
+
+              def resolve_conflict(conflict_id:, outcome:, resolution_notes: nil, **)
+                conflict = conflict_log.get(conflict_id)
+                unless conflict
+                  Legion::Logging.debug "[conflict] resolve failed: id=#{conflict_id[0..7]} not found"
+                  return { error: :not_found }
+                end
+
+                if resolution_notes.nil? && Helpers::LlmEnhancer.available?
+                  llm_result = Helpers::LlmEnhancer.suggest_resolution(
+                    description: conflict[:description],
+                    severity:    conflict[:severity],
+                    exchanges:   conflict[:exchanges]
+                  )
+                  resolution_notes = llm_result[:resolution_notes] if llm_result
+                end
+
+                result = conflict_log.resolve(conflict_id, outcome: outcome, resolution_notes: resolution_notes)
+                if result
+                  Legion::Logging.info "[conflict] resolved: id=#{conflict_id[0..7]} outcome=#{outcome}"
+                  { resolved: true, outcome: outcome }
+                else
+                  Legion::Logging.debug "[conflict] resolve failed: id=#{conflict_id[0..7]} not found"
+                  { error: :not_found }
+                end
+              end
+
+              def get_conflict(conflict_id:, **)
+                conflict = conflict_log.get(conflict_id)
+                Legion::Logging.debug "[conflict] get: id=#{conflict_id[0..7]} found=#{!conflict.nil?}"
+                conflict ? { found: true, conflict: conflict } : { found: false }
+              end
+
+              def active_conflicts(**)
+                conflicts = conflict_log.active_conflicts
+                Legion::Logging.debug "[conflict] active: count=#{conflicts.size}"
+                { conflicts: conflicts, count: conflicts.size }
+              end
+
+              def check_stale_conflicts(**)
+                active = conflict_log.active_conflicts
+                stale  = active.select { |c| Time.now.utc - c[:created_at] > Helpers::Severity::STALE_CONFLICT_TIMEOUT }
+                stale.each do |c|
+                  message = 'conflict marked stale — no resolution after 24h'
+
+                  if Helpers::LlmEnhancer.available?
+                    age_hours = (Time.now.utc - c[:created_at]) / 3600.0
+                    analysis  = Helpers::LlmEnhancer.analyze_stale_conflict(
+                      description:    c[:description],
+                      severity:       c[:severity],
+                      age_hours:      age_hours,
+                      exchange_count: c[:exchanges].size
+                    )
+                    message = "conflict marked stale — #{analysis[:analysis]} (recommendation: #{analysis[:recommendation]})" if analysis
+                  end
+
+                  conflict_log.add_exchange(c[:conflict_id], speaker: :system, message: message)
+                end
+                stale_ids = stale.map { |c| c[:conflict_id] }
+                Legion::Logging.debug "[conflict] stale check: active=#{active.size} stale=#{stale.size}"
+                { checked: active.size, stale_count: stale.size, stale_ids: stale_ids }
+              end
+
+              def recommended_posture(severity:, **)
+                posture = Helpers::Severity.recommended_posture(severity)
+                Legion::Logging.debug "[conflict] posture: severity=#{severity} posture=#{posture}"
+                { severity: severity, posture: posture }
+              end
+
+              private
+
+              def conflict_log
+                @conflict_log ||= Helpers::ConflictLog.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/social/conflict/version'
+require 'legion/extensions/agentic/social/conflict/helpers/severity'
+require 'legion/extensions/agentic/social/conflict/helpers/conflict_log'
+require 'legion/extensions/agentic/social/conflict/helpers/llm_enhancer'
+require 'legion/extensions/agentic/social/conflict/runners/conflict'
+require 'legion/extensions/agentic/social/conflict/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module Conflict
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/social/conscience/helpers/constants'
+require 'legion/extensions/agentic/social/conscience/helpers/moral_evaluator'
+require 'legion/extensions/agentic/social/conscience/helpers/moral_store'
+require 'legion/extensions/agentic/social/conscience/runners/conscience'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module Conscience
+          class Client
+            include Runners::Conscience
+
+            attr_reader :moral_store
+
+            def initialize(moral_store: nil, **)
+              @moral_store = moral_store || Helpers::MoralStore.new
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module Conscience
+          module Helpers
+            module Constants
+              # Moral Foundations Theory — 6 foundations with weights summing to 1.0
+              # Based on Haidt & Graham (2007): Care, Fairness, Loyalty, Authority, Sanctity, Liberty
+              MORAL_FOUNDATIONS = {
+                care:      { weight: 0.25, description: 'Compassion and prevention of suffering' },
+                fairness:  { weight: 0.20, description: 'Justice, reciprocity, and proportionality' },
+                loyalty:   { weight: 0.15, description: 'Group allegiance and trustworthiness' },
+                authority: { weight: 0.15, description: 'Respect for hierarchy and legitimate authority' },
+                sanctity:  { weight: 0.15, description: 'Purity and integrity of systems' },
+                liberty:   { weight: 0.10, description: 'Autonomy and freedom from domination' }
+              }.freeze
+
+              # Possible verdict outcomes from moral evaluation
+              MORAL_VERDICTS = %i[permitted cautioned conflicted prohibited].freeze
+
+              # EMA alpha for moral sensitivity — changes very slowly
+              FOUNDATION_ALPHA = 0.05
+
+              # Foundations must disagree by more than this to trigger a dilemma
+              CONFLICT_THRESHOLD = 0.3
+
+              # Weighted moral score below this means prohibited
+              PROHIBITION_THRESHOLD = -0.5
+
+              # Weighted moral score below this means cautioned
+              CAUTION_THRESHOLD = -0.1
+
+              # Maximum moral evaluation history entries to retain
+              MAX_MORAL_HISTORY = 100
+
+              # Types of ethical dilemmas that can arise when foundations conflict
+              DILEMMA_TYPES = %i[utilitarian deontological virtue_ethics].freeze
+
+              # Initial sensitivity value for each foundation — starts fully sensitive, decays through experience
+              INITIAL_SENSITIVITY = 1.0
+
+              # Moral score range (per-foundation and weighted)
+              MORAL_SCORE_RANGE = { min: -1.0, max: 1.0 }.freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/social/conscience/helpers/moral_evaluator.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module Conscience
+          module Helpers
+            class MoralEvaluator
+              attr_reader :sensitivities
+
+              def initialize
+                @sensitivities = Constants::MORAL_FOUNDATIONS.keys.to_h do |foundation|
+                  [foundation, Constants::INITIAL_SENSITIVITY]
+                end
+              end
+
+              # Evaluate a proposed action against all 6 moral foundations.
+              # Returns a hash with per-foundation scores, weighted_score, verdict, and dilemma info.
+              def evaluate(action:, context:)
+                scores = per_foundation_scores(action, context)
+                w_score = weighted_score(scores)
+                v = verdict(w_score)
+                dilemma = detect_dilemma(scores)
+
+                {
+                  action:         action,
+                  scores:         scores,
+                  weighted_score: w_score.round(4),
+                  verdict:        v,
+                  dilemma:        dilemma,
+                  sensitivities:  @sensitivities.transform_values { |s| s.round(4) },
+                  evaluated_at:   Time.now.utc
+                }
+              end
+
+              # Weighted sum of per-foundation scores * weights * sensitivity
+              def weighted_score(scores)
+                total = 0.0
+                Constants::MORAL_FOUNDATIONS.each do |foundation, config|
+                  score = scores[foundation] || 0.0
+                  sensitivity = @sensitivities[foundation]
+                  total += score * config[:weight] * sensitivity
+                end
+                total.clamp(Constants::MORAL_SCORE_RANGE[:min], Constants::MORAL_SCORE_RANGE[:max])
+              end
+
+              # Determine overall moral verdict from a weighted score
+              def verdict(score)
+                if score <= Constants::PROHIBITION_THRESHOLD
+                  :prohibited
+                elsif score < Constants::CAUTION_THRESHOLD
+                  :cautioned
+                else
+                  :permitted
+                end
+              end
+
+              # Detect a dilemma when foundations strongly disagree with each other.
+              # Returns nil when no dilemma, or a hash describing the conflict type and disagreeing foundations.
+              def detect_dilemma(scores)
+                pos_foundations = scores.select { |_, v| v > Constants::CONFLICT_THRESHOLD }
+                neg_foundations = scores.select { |_, v| v < -Constants::CONFLICT_THRESHOLD }
+
+                return nil if pos_foundations.empty? || neg_foundations.empty?
+
+                dilemma_type = classify_dilemma(pos_foundations.keys, neg_foundations.keys)
+
+                {
+                  type:            dilemma_type,
+                  approving:       pos_foundations.keys,
+                  opposing:        neg_foundations.keys,
+                  tension:         (pos_foundations.values.sum / pos_foundations.size.to_f).round(4),
+                  counter_tension: (neg_foundations.values.sum / neg_foundations.size.to_f).abs.round(4),
+                  detected_at:     Time.now.utc
+                }
+              end
+
+              # Feedback loop: update sensitivity for a foundation based on observed outcome.
+              # outcome is a float in [-1.0, 1.0] where positive = action was morally good in retrospect.
+              def update_sensitivity(foundation, outcome)
+                return unless @sensitivities.key?(foundation)
+
+                current = @sensitivities[foundation]
+                @sensitivities[foundation] = ema(current, outcome.abs.clamp(0.0, 1.0), Constants::FOUNDATION_ALPHA)
+              end
+
+              private
+
+              def per_foundation_scores(action, context)
+                {
+                  care:      evaluate_care(action, context),
+                  fairness:  evaluate_fairness(action, context),
+                  loyalty:   evaluate_loyalty(action, context),
+                  authority: evaluate_authority(action, context),
+                  sanctity:  evaluate_sanctity(action, context),
+                  liberty:   evaluate_liberty(action, context)
+                }
+              end
+
+              # Care/Harm — compassion axis
+              # harm_to_others: negative, benefit_to_others: positive
+              def evaluate_care(_action, context)
+                harm  = context.fetch(:harm_to_others, 0.0).to_f.clamp(-1.0, 1.0)
+                benef = context.fetch(:benefit_to_others, 0.0).to_f.clamp(-1.0, 1.0)
+                vuln  = context.fetch(:vulnerable_affected, false) ? -0.2 : 0.0
+
+                score = (benef - harm.abs) + vuln
+                score.clamp(-1.0, 1.0)
+              end
+
+              # Fairness/Cheating — justice axis
+              # distributional_justice, reciprocity, proportionality
+              def evaluate_fairness(_action, context)
+                justice        = context.fetch(:distributional_justice, 0.0).to_f.clamp(-1.0, 1.0)
+                reciprocity    = context.fetch(:reciprocity, 0.0).to_f.clamp(-1.0, 1.0)
+                proportional   = context.fetch(:proportionality, 0.0).to_f.clamp(-1.0, 1.0)
+
+                ((justice + reciprocity + proportional) / 3.0).clamp(-1.0, 1.0)
+              end
+
+              # Loyalty/Betrayal — group allegiance axis
+              def evaluate_loyalty(_action, context)
+                alignment  = context.fetch(:alignment_with_group_norms, 0.0).to_f.clamp(-1.0, 1.0)
+                trust_pres = context.fetch(:trust_preservation, 0.0).to_f.clamp(-1.0, 1.0)
+
+                ((alignment + trust_pres) / 2.0).clamp(-1.0, 1.0)
+              end
+
+              # Authority/Subversion — hierarchy respect axis
+              def evaluate_authority(_action, context)
+                compliance = context.fetch(:legitimate_authority_compliance, 0.0).to_f.clamp(-1.0, 1.0)
+                hierarchy  = context.fetch(:hierarchy_respect, 0.0).to_f.clamp(-1.0, 1.0)
+
+                ((compliance + hierarchy) / 2.0).clamp(-1.0, 1.0)
+              end
+
+              # Sanctity/Degradation — system integrity axis
+              def evaluate_sanctity(_action, context)
+                integrity = context.fetch(:system_integrity, 0.0).to_f.clamp(-1.0, 1.0)
+                degrad    = context.fetch(:degradation_prevention, 0.0).to_f.clamp(-1.0, 1.0)
+
+                ((integrity + degrad) / 2.0).clamp(-1.0, 1.0)
+              end
+
+              # Liberty/Oppression — autonomy axis
+              def evaluate_liberty(_action, context)
+                autonomy = context.fetch(:autonomy_preservation, 0.0).to_f.clamp(-1.0, 1.0)
+                consent  = context.fetch(:consent_present, false) ? 0.3 : -0.2
+
+                (autonomy + consent).clamp(-1.0, 1.0)
+              end
+
+              # Classify the dilemma type from which foundations are in conflict
+              def classify_dilemma(approving, opposing)
+                care_side    = approving.include?(:care) || opposing.include?(:care)
+                fair_side    = approving.include?(:fairness) || opposing.include?(:fairness)
+                auth_side    = approving.include?(:authority) || opposing.include?(:authority)
+
+                if care_side && fair_side
+                  :utilitarian
+                elsif auth_side
+                  :deontological
+                else
+                  :virtue_ethics
+                end
+              end
+
+              def ema(current, observed, alpha)
+                (current * (1.0 - alpha)) + (observed * alpha)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end