lex-conscience 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8f0fe95528d279f5002b8b2f6e0c5c92f7066677c2e6b63b44518a8a538b3018
+  data.tar.gz: f05fc53a2a90c1cf1adc883de909ea0e9719d08c0437eda80f54ec381777d0e1
+SHA512:
+  metadata.gz: da828802ee102cb9bab71d2334c93ce73fa7ddae5f38c1138e57c7f8387337cef7d698c57d5aa956104bb4a201a4559c65c652161d27a6c5adcf480477014fd9
+  data.tar.gz: a21dd9ab957be320e6fee7cd8f85290eff17f060935be89a94bc99907de0384e497df3475f4938bd7770e8f6a9efc597aec7903f1dfbe28822113652241cf5c1

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/conscience/helpers/constants'
+require 'legion/extensions/conscience/helpers/moral_evaluator'
+require 'legion/extensions/conscience/helpers/moral_store'
+require 'legion/extensions/conscience/runners/conscience'
+
+module Legion
+  module Extensions
+    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

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

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

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

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

data/lib/legion/extensions/conscience/helpers/moral_store.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Conscience
+      module Helpers
+        class MoralStore
+          attr_reader :evaluator, :history, :dilemmas, :sensitivity_snapshots
+
+          def initialize(evaluator: nil)
+            @evaluator            = evaluator || MoralEvaluator.new
+            @history              = []
+            @dilemmas             = []
+            @sensitivity_snapshots = []
+            @followed_count       = 0
+            @overridden_count     = 0
+          end
+
+          # Store a completed moral evaluation result
+          def record_evaluation(result)
+            @history << result
+            @history.shift while @history.size > Constants::MAX_MORAL_HISTORY
+
+            @dilemmas << result[:dilemma] if result[:dilemma]
+
+            snapshot_sensitivities(result[:verdict])
+
+            result
+          end
+
+          # Record whether the agent followed its moral verdict or overrode it.
+          # outcome: :followed | :overridden
+          def record_follow_through(verdict, outcome)
+            if outcome == :followed
+              @followed_count += 1
+            else
+              @overridden_count += 1
+            end
+
+            # Feed back into evaluator sensitivities
+            foundation_feedback(verdict, outcome)
+          end
+
+          # Ratio of evaluations where the agent followed its moral verdict
+          def consistency_score
+            total = @followed_count + @overridden_count
+            return 1.0 if total.zero?
+
+            (@followed_count.to_f / total).round(4)
+          end
+
+          # Current foundation sensitivities from the evaluator
+          def foundation_sensitivities
+            @evaluator.sensitivities.transform_values { |s| s.round(4) }
+          end
+
+          # Recent evaluations, newest last
+          def recent_evaluations(limit = 20)
+            @history.last(limit)
+          end
+
+          # Open dilemmas (not yet resolved)
+          def open_dilemmas
+            @dilemmas.last(20)
+          end
+
+          # Aggregate stats across all evaluations
+          def aggregate_stats
+            verdict_counts = Hash.new(0)
+            @history.each { |e| verdict_counts[e[:verdict]] += 1 }
+
+            {
+              total_evaluations:        @history.size,
+              verdict_counts:           verdict_counts,
+              dilemma_count:            @dilemmas.size,
+              consistency_score:        consistency_score,
+              followed_count:           @followed_count,
+              overridden_count:         @overridden_count,
+              foundation_sensitivities: foundation_sensitivities
+            }
+          end
+
+          private
+
+          def snapshot_sensitivities(verdict)
+            @sensitivity_snapshots << {
+              verdict:       verdict,
+              sensitivities: @evaluator.sensitivities.dup,
+              at:            Time.now.utc
+            }
+            @sensitivity_snapshots.shift while @sensitivity_snapshots.size > Constants::MAX_MORAL_HISTORY
+          end
+
+          def foundation_feedback(verdict, outcome)
+            # When an agent overrides a prohibited verdict, desensitize authority/sanctity
+            # When an agent follows a cautioned verdict, sensitize care/fairness
+            case [verdict, outcome]
+            when %i[prohibited overridden]
+              @evaluator.update_sensitivity(:care, -0.5)
+              @evaluator.update_sensitivity(:sanctity, -0.3)
+            when %i[cautioned followed]
+              @evaluator.update_sensitivity(:care, 0.8)
+              @evaluator.update_sensitivity(:fairness, 0.6)
+            when %i[permitted followed]
+              @evaluator.update_sensitivity(:liberty, 0.7)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Conscience
+      module Runners
+        module Conscience
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          # Full moral assessment of a proposed action.
+          # action: string or symbol describing what is about to happen
+          # context: hash of moral context signals (harm_to_others, consent_present, etc.)
+          def moral_evaluate(action:, context: {}, **)
+            result = moral_store.evaluator.evaluate(action: action, context: context)
+            moral_store.record_evaluation(result)
+
+            Legion::Logging.debug "[conscience] action=#{action} verdict=#{result[:verdict]} " \
+                                  "score=#{result[:weighted_score]} dilemma=#{result[:dilemma]&.dig(:type)}"
+
+            result
+          end
+
+          # Current moral sensitivities and consistency score
+          def moral_status(**)
+            stats = moral_store.aggregate_stats
+            sensitivities = moral_store.foundation_sensitivities
+
+            Legion::Logging.debug "[conscience] consistency=#{stats[:consistency_score]} " \
+                                  "evaluations=#{stats[:total_evaluations]}"
+
+            {
+              sensitivities: sensitivities,
+              consistency:   stats[:consistency_score],
+              stats:         stats
+            }
+          end
+
+          # Recent moral evaluation history
+          def moral_history(limit: 20, **)
+            recent = moral_store.recent_evaluations(limit)
+            Legion::Logging.debug "[conscience] history: #{recent.size} entries"
+
+            {
+              history: recent,
+              total:   moral_store.history.size,
+              limit:   limit
+            }
+          end
+
+          # Record whether the agent actually followed or overrode its moral verdict.
+          # outcome: :followed | :overridden
+          def update_moral_outcome(action:, outcome:, verdict: nil, **)
+            effective_verdict = verdict || infer_last_verdict(action)
+
+            moral_store.record_follow_through(effective_verdict, outcome)
+
+            Legion::Logging.debug "[conscience] follow_through action=#{action} " \
+                                  "verdict=#{effective_verdict} outcome=#{outcome} " \
+                                  "consistency=#{moral_store.consistency_score}"
+
+            {
+              action:      action,
+              verdict:     effective_verdict,
+              outcome:     outcome,
+              consistency: moral_store.consistency_score
+            }
+          end
+
+          # List unresolved moral dilemmas (cases where foundations strongly disagreed)
+          def moral_dilemmas(**)
+            open = moral_store.open_dilemmas
+            Legion::Logging.debug "[conscience] dilemmas: #{open.size} open"
+
+            {
+              dilemmas: open,
+              count:    open.size
+            }
+          end
+
+          # Aggregate moral reasoning stats
+          def conscience_stats(**)
+            stats = moral_store.aggregate_stats
+            Legion::Logging.debug '[conscience] stats'
+
+            stats.merge(
+              verdict_distribution: verdict_distribution(stats[:verdict_counts]),
+              foundation_weights:   Helpers::Constants::MORAL_FOUNDATIONS.transform_values { |v| v[:weight] }
+            )
+          end
+
+          private
+
+          def moral_store
+            @moral_store ||= Helpers::MoralStore.new
+          end
+
+          def infer_last_verdict(action)
+            last = moral_store.history.reverse.find { |e| e[:action] == action }
+            last ? last[:verdict] : :permitted
+          end
+
+          def verdict_distribution(verdict_counts)
+            total = verdict_counts.values.sum.to_f
+            return {} if total.zero?
+
+            verdict_counts.transform_values { |count| (count / total).round(4) }
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/conscience.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/conscience/version'
+require 'legion/extensions/conscience/helpers/constants'
+require 'legion/extensions/conscience/helpers/moral_evaluator'
+require 'legion/extensions/conscience/helpers/moral_store'
+require 'legion/extensions/conscience/runners/conscience'
+require 'legion/extensions/conscience/client'
+
+module Legion
+  module Extensions
+    module Conscience
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined?(:Core)
+    end
+  end
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: lex-conscience
+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: Applies Moral Foundations Theory to evaluate proposed actions, track
+  moral consistency, and surface ethical dilemmas before execution
+email:
+- matt@legionIO.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/legion/extensions/conscience.rb
+- lib/legion/extensions/conscience/client.rb
+- lib/legion/extensions/conscience/helpers/constants.rb
+- lib/legion/extensions/conscience/helpers/moral_evaluator.rb
+- lib/legion/extensions/conscience/helpers/moral_store.rb
+- lib/legion/extensions/conscience/runners/conscience.rb
+- lib/legion/extensions/conscience/version.rb
+homepage: https://github.com/LegionIO/lex-conscience
+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: Moral reasoning engine for LegionIO cognitive agents
+test_files: []