lex-dissonance 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 93ff7acbd3ccecfcaf1bcdf7ea395eb09507a278423c1a5fb5f0349e7ef59c43
+  data.tar.gz: ca429797ec391379c0eb88c0ecd07c429686b0f4166433e3716ad05e9db25634
+SHA512:
+  metadata.gz: 3619a6c4544ae2ac31410c59ca0e2b6cbec8ea687283718e83ccbf3b1d57bb7c20ccfe115e925f2876d29025d573971e7429ad1c45535777308477b8e699e640
+  data.tar.gz: 3acc77063b498cda63078d5261eba333c6d14affc1c618b4f85f8e5e5aa319031a9b01ea57cd9b89cdf9fa203805ad35d92f992fc5eacdbbab8b687f8b9f3a04

data/Gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rspec', '~> 3.0'
+gem 'rubocop', '~> 1.0', require: false
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/lex-dissonance.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/dissonance/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-dissonance'
+  spec.version       = Legion::Extensions::Dissonance::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Dissonance'
+  spec.description   = 'Cognitive dissonance modeling — contradiction detection, belief tracking, and resolution strategies for brain-modeled agentic AI'
+  spec.homepage      = 'https://github.com/LegionIO/lex-dissonance'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']        = spec.homepage
+  spec.metadata['source_code_uri']     = 'https://github.com/LegionIO/lex-dissonance'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-dissonance'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-dissonance'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-dissonance/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-dissonance.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/dissonance/helpers/constants'
+require 'legion/extensions/dissonance/helpers/belief'
+require 'legion/extensions/dissonance/helpers/dissonance_event'
+require 'legion/extensions/dissonance/helpers/dissonance_model'
+require 'legion/extensions/dissonance/runners/dissonance'
+
+module Legion
+  module Extensions
+    module Dissonance
+      class Client
+        include Runners::Dissonance
+
+        attr_reader :model
+
+        def initialize(model: nil, **)
+          @model            = model || Helpers::DissonanceModel.new
+          @dissonance_model = @model
+        end
+
+        private
+
+        attr_accessor :dissonance_model
+      end
+    end
+  end
+end

data/lib/legion/extensions/dissonance/helpers/belief.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Dissonance
+      module Helpers
+        class Belief
+          attr_reader :id, :domain, :content, :confidence, :importance, :created_at
+
+          def initialize(domain:, content:, confidence: 0.7, importance: :moderate)
+            @id         = SecureRandom.uuid
+            @domain     = domain
+            @content    = content
+            @confidence = confidence.clamp(0.0, 1.0)
+            @importance = importance
+            @created_at = Time.now.utc
+          end
+
+          def contradicts?(other)
+            return false if id == other.id
+            return false unless domain == other.domain
+
+            content.strip.downcase != other.content.strip.downcase
+          end
+
+          def to_h
+            {
+              id:         id,
+              domain:     domain,
+              content:    content,
+              confidence: confidence,
+              importance: importance,
+              created_at: created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Dissonance
+      module Helpers
+        module Constants
+          DISSONANCE_THRESHOLD  = 0.4
+          MAX_BELIEFS           = 200
+          MAX_DISSONANCE_EVENTS = 100
+          DECAY_RATE            = 0.03
+          RESOLUTION_RELIEF     = 0.3
+          RATIONALIZATION_FACTOR = 0.5
+          IMPORTANCE_WEIGHTS    = { core: 1.0, significant: 0.7, moderate: 0.5, peripheral: 0.25 }.freeze
+          RESOLUTION_STRATEGIES = %i[belief_revision rationalization avoidance].freeze
+          STRESS_CEILING        = 1.0
+          STRESS_FLOOR          = 0.0
+          CONTRADICTION_TYPES   = %i[direct inverse conditional temporal].freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/dissonance/helpers/dissonance_event.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Dissonance
+      module Helpers
+        class DissonanceEvent
+          attr_reader :id, :belief_a_id, :belief_b_id, :domain, :magnitude,
+                      :contradiction_type, :resolved, :resolution_strategy, :timestamp
+
+          def initialize(belief_a_id:, belief_b_id:, domain:, magnitude:, contradiction_type: :direct)
+            @id                  = SecureRandom.uuid
+            @belief_a_id         = belief_a_id
+            @belief_b_id         = belief_b_id
+            @domain              = domain
+            @magnitude           = magnitude.clamp(0.0, 1.0)
+            @contradiction_type  = contradiction_type
+            @resolved            = false
+            @resolution_strategy = nil
+            @timestamp           = Time.now.utc
+          end
+
+          def resolve!(strategy)
+            @resolved            = true
+            @resolution_strategy = strategy
+            self
+          end
+
+          def to_h
+            {
+              id:                  id,
+              belief_a_id:         belief_a_id,
+              belief_b_id:         belief_b_id,
+              domain:              domain,
+              magnitude:           magnitude,
+              contradiction_type:  contradiction_type,
+              resolved:            resolved,
+              resolution_strategy: resolution_strategy,
+              timestamp:           timestamp
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/dissonance/helpers/dissonance_model.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Dissonance
+      module Helpers
+        class DissonanceModel
+          include Constants
+
+          attr_reader :beliefs, :events, :stress
+
+          def initialize
+            @beliefs = {}
+            @events  = {}
+            @stress  = STRESS_FLOOR
+          end
+
+          def add_belief(domain:, content:, confidence: 0.7, importance: :moderate)
+            prune_beliefs if @beliefs.size >= MAX_BELIEFS
+
+            belief = Belief.new(domain: domain, content: content,
+                                confidence: confidence, importance: importance)
+            @beliefs[belief.id] = belief
+
+            new_events = detect_contradictions_for(belief)
+            new_events.each { |ev| @events[ev.id] = ev }
+
+            { belief: belief, new_dissonance_events: new_events }
+          end
+
+          def detect_contradictions
+            new_events = []
+            belief_list = @beliefs.values
+
+            belief_list.each_with_index do |bel_a, idx|
+              belief_list[(idx + 1)..].each do |bel_b|
+                next unless bel_a.contradicts?(bel_b)
+                next if contradiction_tracked?(bel_a.id, bel_b.id)
+
+                ev = build_event(bel_a, bel_b)
+                @events[ev.id] = ev
+                new_events << ev
+              end
+            end
+
+            new_events
+          end
+
+          def resolve(event_id, strategy:)
+            event = @events[event_id]
+            return nil unless event
+            return nil if event.resolved
+            return nil unless RESOLUTION_STRATEGIES.include?(strategy)
+
+            event.resolve!(strategy)
+            relief = compute_relief(strategy)
+            @stress = (@stress - relief).clamp(STRESS_FLOOR, STRESS_CEILING)
+            event
+          end
+
+          def stress_level
+            @stress
+          end
+
+          def domain_stress(domain)
+            unresolved = unresolved_events.select { |ev| ev.domain == domain }
+            return STRESS_FLOOR if unresolved.empty?
+
+            raw = unresolved.sum(&:magnitude) / MAX_DISSONANCE_EVENTS.to_f
+            raw.clamp(STRESS_FLOOR, STRESS_CEILING)
+          end
+
+          def unresolved_events
+            @events.values.reject(&:resolved)
+          end
+
+          def decay
+            unresolved = unresolved_events
+            if unresolved.any?
+              increment = DECAY_RATE * unresolved.size
+              @stress   = (@stress + increment).clamp(STRESS_FLOOR, STRESS_CEILING)
+            else
+              @stress = (@stress - DECAY_RATE).clamp(STRESS_FLOOR, STRESS_CEILING)
+            end
+            @stress
+          end
+
+          def to_h
+            {
+              beliefs:          @beliefs.values.map(&:to_h),
+              events:           @events.values.map(&:to_h),
+              stress:           @stress,
+              unresolved_count: unresolved_events.size,
+              total_beliefs:    @beliefs.size,
+              total_events:     @events.size
+            }
+          end
+
+          private
+
+          def detect_contradictions_for(new_belief)
+            new_events = []
+
+            @beliefs.each_value do |existing|
+              next if existing.id == new_belief.id
+              next unless new_belief.contradicts?(existing)
+              next if contradiction_tracked?(new_belief.id, existing.id)
+
+              ev = build_event(new_belief, existing)
+              new_events << ev
+            end
+
+            new_events
+          end
+
+          def build_event(bel_a, bel_b)
+            magnitude = compute_magnitude(bel_a, bel_b)
+            DissonanceEvent.new(
+              belief_a_id:        bel_a.id,
+              belief_b_id:        bel_b.id,
+              domain:             bel_a.domain,
+              magnitude:          magnitude,
+              contradiction_type: :direct
+            )
+          end
+
+          def compute_magnitude(bel_a, bel_b)
+            weight_a       = IMPORTANCE_WEIGHTS.fetch(bel_a.importance, 0.5)
+            weight_b       = IMPORTANCE_WEIGHTS.fetch(bel_b.importance, 0.5)
+            avg_weight     = (weight_a + weight_b) / 2.0
+            avg_confidence = (bel_a.confidence + bel_b.confidence) / 2.0
+            (avg_weight * avg_confidence).clamp(0.0, 1.0)
+          end
+
+          def compute_relief(strategy)
+            base = RESOLUTION_RELIEF
+            strategy == :rationalization ? base * RATIONALIZATION_FACTOR : base
+          end
+
+          def contradiction_tracked?(id_a, id_b)
+            @events.values.any? do |ev|
+              (ev.belief_a_id == id_a && ev.belief_b_id == id_b) ||
+                (ev.belief_a_id == id_b && ev.belief_b_id == id_a)
+            end
+          end
+
+          def prune_beliefs
+            oldest = @beliefs.values.min_by(&:created_at)
+            @beliefs.delete(oldest.id) if oldest
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Dissonance
+      module Runners
+        module Dissonance
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def add_belief(domain:, content:, confidence: 0.7, importance: :moderate, **)
+            unless Helpers::Constants::IMPORTANCE_WEIGHTS.key?(importance)
+              return { success: false, error: :invalid_importance,
+                       valid: Helpers::Constants::IMPORTANCE_WEIGHTS.keys }
+            end
+
+            result  = dissonance_model.add_belief(domain: domain, content: content,
+                                                  confidence: confidence, importance: importance)
+            belief  = result[:belief]
+            new_evs = result[:new_dissonance_events]
+
+            Legion::Logging.debug "[dissonance] add_belief: id=#{belief.id[0..7]} domain=#{domain} importance=#{importance} new_events=#{new_evs.size}"
+
+            {
+              success:               true,
+              belief_id:             belief.id,
+              domain:                domain,
+              new_dissonance_events: new_evs.map(&:to_h),
+              dissonance_triggered:  new_evs.any? { |ev| ev.magnitude >= Helpers::Constants::DISSONANCE_THRESHOLD }
+            }
+          end
+
+          def update_dissonance(**)
+            dissonance_model.detect_contradictions
+            new_stress = dissonance_model.decay
+            unresolved = dissonance_model.unresolved_events
+
+            Legion::Logging.debug "[dissonance] update: stress=#{new_stress.round(3)} unresolved=#{unresolved.size}"
+
+            {
+              success:          true,
+              stress:           new_stress,
+              unresolved_count: unresolved.size,
+              above_threshold:  unresolved.any? { |ev| ev.magnitude >= Helpers::Constants::DISSONANCE_THRESHOLD }
+            }
+          end
+
+          def resolve_dissonance(event_id:, strategy: :belief_revision, **)
+            unless Helpers::Constants::RESOLUTION_STRATEGIES.include?(strategy)
+              return { success: false, error: :invalid_strategy,
+                       valid: Helpers::Constants::RESOLUTION_STRATEGIES }
+            end
+
+            event = dissonance_model.resolve(event_id, strategy: strategy)
+            if event
+              Legion::Logging.debug "[dissonance] resolved: id=#{event_id[0..7]} strategy=#{strategy}"
+              { success: true, resolved: true, strategy: strategy, event: event.to_h }
+            else
+              Legion::Logging.debug "[dissonance] resolve failed: id=#{event_id[0..7]} not_found_or_already_resolved"
+              { success: false, error: :not_found_or_already_resolved }
+            end
+          end
+
+          def dissonance_status(**)
+            model    = dissonance_model
+            snapshot = model.to_h
+
+            Legion::Logging.debug "[dissonance] status: stress=#{snapshot[:stress].round(3)} " \
+                                  "beliefs=#{snapshot[:total_beliefs]} unresolved=#{snapshot[:unresolved_count]}"
+
+            {
+              success:          true,
+              stress:           snapshot[:stress],
+              total_beliefs:    snapshot[:total_beliefs],
+              total_events:     snapshot[:total_events],
+              unresolved_count: snapshot[:unresolved_count]
+            }
+          end
+
+          def domain_dissonance(domain:, **)
+            stress = dissonance_model.domain_stress(domain)
+            unresolved = dissonance_model.unresolved_events.select { |ev| ev.domain == domain }
+
+            Legion::Logging.debug "[dissonance] domain_dissonance: domain=#{domain} stress=#{stress.round(3)} unresolved=#{unresolved.size}"
+
+            {
+              success:          true,
+              domain:           domain,
+              stress:           stress,
+              unresolved_count: unresolved.size,
+              events:           unresolved.map(&:to_h)
+            }
+          end
+
+          def beliefs_for(domain:, **)
+            beliefs = dissonance_model.beliefs.values.select { |b| b.domain == domain }
+
+            Legion::Logging.debug "[dissonance] beliefs_for: domain=#{domain} count=#{beliefs.size}"
+
+            {
+              success: true,
+              domain:  domain,
+              count:   beliefs.size,
+              beliefs: beliefs.map(&:to_h)
+            }
+          end
+
+          def unresolved(**)
+            events = dissonance_model.unresolved_events
+
+            Legion::Logging.debug "[dissonance] unresolved: count=#{events.size}"
+
+            {
+              success: true,
+              count:   events.size,
+              events:  events.map(&:to_h)
+            }
+          end
+
+          def dissonance_stats(**)
+            model    = dissonance_model
+            snapshot = model.to_h
+
+            domains = model.beliefs.values.map(&:domain).uniq
+            domain_stresses = domains.to_h { |d| [d, model.domain_stress(d)] }
+
+            unresolved = model.unresolved_events
+            resolved   = model.events.values.select(&:resolved)
+
+            resolution_breakdown = Helpers::Constants::RESOLUTION_STRATEGIES.to_h do |s|
+              [s, resolved.count { |ev| ev.resolution_strategy == s }]
+            end
+
+            Legion::Logging.debug "[dissonance] stats: beliefs=#{snapshot[:total_beliefs]} " \
+                                  "events=#{snapshot[:total_events]} stress=#{snapshot[:stress].round(3)}"
+
+            {
+              success:              true,
+              stress:               snapshot[:stress],
+              total_beliefs:        snapshot[:total_beliefs],
+              total_events:         snapshot[:total_events],
+              unresolved_count:     unresolved.size,
+              resolved_count:       resolved.size,
+              domain_stresses:      domain_stresses,
+              resolution_breakdown: resolution_breakdown,
+              above_threshold:      unresolved.any? { |ev| ev.magnitude >= Helpers::Constants::DISSONANCE_THRESHOLD }
+            }
+          end
+
+          private
+
+          def dissonance_model
+            @dissonance_model ||= Helpers::DissonanceModel.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/dissonance.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/dissonance/version'
+require 'legion/extensions/dissonance/helpers/constants'
+require 'legion/extensions/dissonance/helpers/belief'
+require 'legion/extensions/dissonance/helpers/dissonance_event'
+require 'legion/extensions/dissonance/helpers/dissonance_model'
+require 'legion/extensions/dissonance/runners/dissonance'
+
+module Legion
+  module Extensions
+    module Dissonance
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

data/spec/legion/extensions/dissonance/client_spec.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/dissonance/client'
+
+RSpec.describe Legion::Extensions::Dissonance::Client do
+  describe '#initialize' do
+    it 'creates a default DissonanceModel when none provided' do
+      client = described_class.new
+      expect(client.model).to be_a(Legion::Extensions::Dissonance::Helpers::DissonanceModel)
+    end
+
+    it 'accepts a custom model' do
+      custom_model = Legion::Extensions::Dissonance::Helpers::DissonanceModel.new
+      client = described_class.new(model: custom_model)
+      expect(client.model).to be(custom_model)
+    end
+  end
+
+  describe 'responds to all runner methods' do
+    let(:client) { described_class.new }
+
+    it { expect(client).to respond_to(:add_belief) }
+    it { expect(client).to respond_to(:update_dissonance) }
+    it { expect(client).to respond_to(:resolve_dissonance) }
+    it { expect(client).to respond_to(:dissonance_status) }
+    it { expect(client).to respond_to(:domain_dissonance) }
+    it { expect(client).to respond_to(:beliefs_for) }
+    it { expect(client).to respond_to(:unresolved) }
+    it { expect(client).to respond_to(:dissonance_stats) }
+  end
+
+  describe 'state isolation between instances' do
+    it 'two clients do not share belief state' do
+      client1 = described_class.new
+      client2 = described_class.new
+      client1.add_belief(domain: 'x', content: 'some belief')
+      result = client2.beliefs_for(domain: 'x')
+      expect(result[:count]).to eq(0)
+    end
+  end
+
+  describe 'custom model integration' do
+    it 'uses the beliefs already in a pre-populated model' do
+      model = Legion::Extensions::Dissonance::Helpers::DissonanceModel.new
+      model.add_belief(domain: 'shared', content: 'a shared belief')
+      client = described_class.new(model: model)
+      result = client.beliefs_for(domain: 'shared')
+      expect(result[:count]).to eq(1)
+    end
+  end
+end

data/spec/legion/extensions/dissonance/helpers/belief_spec.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Dissonance::Helpers::Belief do
+  let(:belief) { described_class.new(domain: 'ethics', content: 'honesty is required', confidence: 0.9, importance: :core) }
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(belief.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'assigns domain' do
+      expect(belief.domain).to eq('ethics')
+    end
+
+    it 'assigns content' do
+      expect(belief.content).to eq('honesty is required')
+    end
+
+    it 'assigns confidence' do
+      expect(belief.confidence).to eq(0.9)
+    end
+
+    it 'assigns importance' do
+      expect(belief.importance).to eq(:core)
+    end
+
+    it 'assigns created_at as UTC Time' do
+      expect(belief.created_at).to be_a(Time)
+    end
+
+    it 'clamps confidence to 0-1 range (above)' do
+      b = described_class.new(domain: 'd', content: 'c', confidence: 1.5)
+      expect(b.confidence).to eq(1.0)
+    end
+
+    it 'clamps confidence to 0-1 range (below)' do
+      b = described_class.new(domain: 'd', content: 'c', confidence: -0.5)
+      expect(b.confidence).to eq(0.0)
+    end
+
+    it 'defaults confidence to 0.7' do
+      b = described_class.new(domain: 'd', content: 'c')
+      expect(b.confidence).to eq(0.7)
+    end
+
+    it 'defaults importance to :moderate' do
+      b = described_class.new(domain: 'd', content: 'c')
+      expect(b.importance).to eq(:moderate)
+    end
+  end
+
+  describe '#contradicts?' do
+    let(:other_same) do
+      described_class.new(domain: 'ethics', content: 'honesty is required', confidence: 0.8, importance: :moderate)
+    end
+
+    let(:other_different) do
+      described_class.new(domain: 'ethics', content: 'deception is acceptable', confidence: 0.6, importance: :moderate)
+    end
+
+    let(:other_domain) do
+      described_class.new(domain: 'safety', content: 'honesty is required', confidence: 0.8, importance: :moderate)
+    end
+
+    it 'returns false for same content' do
+      expect(belief.contradicts?(other_same)).to be false
+    end
+
+    it 'returns true for different content in same domain' do
+      expect(belief.contradicts?(other_different)).to be true
+    end
+
+    it 'returns false for different domain' do
+      expect(belief.contradicts?(other_domain)).to be false
+    end
+
+    it 'returns false when compared to itself' do
+      expect(belief.contradicts?(belief)).to be false
+    end
+
+    it 'is case-insensitive for content comparison' do
+      upper = described_class.new(domain: 'ethics', content: 'HONESTY IS REQUIRED', confidence: 0.8, importance: :moderate)
+      expect(belief.contradicts?(upper)).to be false
+    end
+
+    it 'ignores leading/trailing whitespace in content comparison' do
+      padded = described_class.new(domain: 'ethics', content: '  honesty is required  ', confidence: 0.8, importance: :moderate)
+      expect(belief.contradicts?(padded)).to be false
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with all fields' do
+      h = belief.to_h
+      expect(h[:id]).to eq(belief.id)
+      expect(h[:domain]).to eq('ethics')
+      expect(h[:content]).to eq('honesty is required')
+      expect(h[:confidence]).to eq(0.9)
+      expect(h[:importance]).to eq(:core)
+      expect(h[:created_at]).to be_a(Time)
+    end
+  end
+end