lex-mentalizing 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 15a3ade481ea7a8a8d77fc7ce5e21f3182e8fa37ad5895a61c8922988224eff2
+  data.tar.gz: 7aad6db5216975d38f4dae1b087cc8750412e8cac7a79fe0d36d23e7aaff8c6b
+SHA512:
+  metadata.gz: 7a8d22b17f0fb84925452f67f7055e7e8a81ba8c53d822b59dadbd0f9934871ea5e4ccdcf45008555fda5a8cf32a7dd34039e350de7e7e821825f1dcd96a4c4f
+  data.tar.gz: 9bfd174741ef5e1f2195c7a6e761e7abca42665d059de3e309b8830f9f7622ef5246dd95e696bb4d9500d205edaba36078c06adaa768a684aede601dc48f6f34

data/Gemfile

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

data/lex-mentalizing.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/mentalizing/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-mentalizing'
+  spec.version       = Legion::Extensions::Mentalizing::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Mentalizing'
+  spec.description   = 'Second-order Theory of Mind for brain-modeled agentic AI. ' \
+                       'Recursive belief attribution, false-belief detection, and social alignment modeling.'
+  spec.homepage      = 'https://github.com/LegionIO/lex-mentalizing'
+  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-mentalizing'
+  spec.metadata['documentation_uri']     = 'https://github.com/LegionIO/lex-mentalizing'
+  spec.metadata['changelog_uri']         = 'https://github.com/LegionIO/lex-mentalizing'
+  spec.metadata['bug_tracker_uri']       = 'https://github.com/LegionIO/lex-mentalizing/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-mentalizing.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

data/lib/legion/extensions/mentalizing/actors/decay.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module Mentalizing
+      module Actor
+        class Decay < Legion::Extensions::Actors::Every
+          def runner_class
+            Legion::Extensions::Mentalizing::Runners::Mentalizing
+          end
+
+          def runner_function
+            'update_mentalizing'
+          end
+
+          def time
+            300
+          end
+
+          def run_now?
+            false
+          end
+
+          def use_runner?
+            false
+          end
+
+          def check_subtask?
+            false
+          end
+
+          def generate_task?
+            false
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/mentalizing/helpers/constants'
+require 'legion/extensions/mentalizing/helpers/belief_attribution'
+require 'legion/extensions/mentalizing/helpers/mental_model'
+require 'legion/extensions/mentalizing/runners/mentalizing'
+
+module Legion
+  module Extensions
+    module Mentalizing
+      class Client
+        include Runners::Mentalizing
+
+        def initialize(**)
+          @mental_model = Helpers::MentalModel.new
+        end
+
+        private
+
+        attr_reader :mental_model
+      end
+    end
+  end
+end

data/lib/legion/extensions/mentalizing/helpers/belief_attribution.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Mentalizing
+      module Helpers
+        class BeliefAttribution
+          attr_reader :id, :agent_id, :subject, :content, :depth, :about_agent_id, :created_at
+          attr_accessor :confidence
+
+          def initialize(agent_id:, subject:, content:, confidence:, depth: 0, about_agent_id: nil)
+            @id             = SecureRandom.uuid
+            @agent_id       = agent_id
+            @subject        = subject
+            @content        = content
+            @confidence     = confidence.clamp(0.0, 1.0)
+            @depth          = depth
+            @about_agent_id = about_agent_id
+            @created_at     = Time.now.utc
+          end
+
+          def decay
+            @confidence = [@confidence - Constants::BELIEF_DECAY, Constants::BELIEF_FLOOR].max
+          end
+
+          def reinforce(amount: Constants::CONFIDENCE_ALPHA)
+            @confidence = [@confidence + amount, 1.0].min
+          end
+
+          def label
+            Constants::CONFIDENCE_LABELS.each do |range, lbl|
+              return lbl if range.cover?(@confidence)
+            end
+            :unknown
+          end
+
+          def to_h
+            {
+              id:             @id,
+              agent_id:       @agent_id,
+              subject:        @subject,
+              content:        @content,
+              confidence:     @confidence,
+              depth:          @depth,
+              about_agent_id: @about_agent_id,
+              label:          label,
+              created_at:     @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Mentalizing
+      module Helpers
+        module Constants
+          MAX_AGENTS            = 50
+          MAX_BELIEFS_PER_AGENT = 30
+          MAX_RECURSION_DEPTH   = 4
+          BELIEF_DECAY          = 0.02
+          BELIEF_FLOOR          = 0.05
+          CONFIDENCE_ALPHA      = 0.12
+          DEFAULT_CONFIDENCE    = 0.3
+          MAX_HISTORY           = 200
+          PROJECTION_DISCOUNT   = 0.7
+
+          CONFIDENCE_LABELS = {
+            (0.8..)     => :certain,
+            (0.6...0.8) => :confident,
+            (0.4...0.6) => :uncertain,
+            (0.2...0.4) => :speculative,
+            (..0.2)     => :unknown
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/mentalizing/helpers/mental_model.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Mentalizing
+      module Helpers
+        class MentalModel
+          def initialize
+            @models = {}
+          end
+
+          def attribute_belief(agent_id:, subject:, content:, confidence:, depth: 0, about_agent_id: nil)
+            ensure_agent_capacity(agent_id)
+            capped_depth = [depth.to_i, Constants::MAX_RECURSION_DEPTH].min
+            belief = BeliefAttribution.new(
+              agent_id:       agent_id,
+              subject:        subject,
+              content:        content,
+              confidence:     confidence,
+              depth:          capped_depth,
+              about_agent_id: about_agent_id
+            )
+            @models[agent_id] ||= []
+            @models[agent_id] << belief
+            prune_agent_beliefs(agent_id)
+            belief
+          end
+
+          def beliefs_for(agent_id:)
+            @models[agent_id] || []
+          end
+
+          def beliefs_about(about_agent_id:)
+            @models.values.flatten.select { |b| b.about_agent_id == about_agent_id }
+          end
+
+          def recursive_belief(agent_id:, about_agent_id:, subject:)
+            beliefs = beliefs_for(agent_id: agent_id)
+            beliefs.select { |b| b.about_agent_id == about_agent_id && b.subject == subject }
+                   .max_by(&:confidence)
+          end
+
+          def project_self(subject:, own_belief:, other_agent_id:)
+            discounted = (own_belief * Constants::PROJECTION_DISCOUNT).clamp(0.0, 1.0)
+            attribute_belief(
+              agent_id:       :self,
+              subject:        subject,
+              content:        "projected: #{other_agent_id} thinks I believe this",
+              confidence:     discounted,
+              depth:          1,
+              about_agent_id: other_agent_id
+            )
+          end
+
+          def alignment(agent_a:, agent_b:, subject:)
+            beliefs_a = beliefs_on_subject(agent_a, subject)
+            beliefs_b = beliefs_on_subject(agent_b, subject)
+            return 0.0 if beliefs_a.empty? || beliefs_b.empty?
+
+            conf_a = beliefs_a.map(&:confidence).sum / beliefs_a.size
+            conf_b = beliefs_b.map(&:confidence).sum / beliefs_b.size
+            1.0 - (conf_a - conf_b).abs
+          end
+
+          def detect_false_belief(agent_id:, subject:, reality:)
+            relevant = beliefs_for(agent_id: agent_id).select { |b| b.subject == subject }
+            return { false_belief: false, reason: :no_beliefs } if relevant.empty?
+
+            strongest = relevant.max_by(&:confidence)
+            false_belief = strongest.content != reality
+            {
+              false_belief: false_belief,
+              agent_id:     agent_id,
+              subject:      subject,
+              held_belief:  strongest.content,
+              reality:      reality,
+              confidence:   strongest.confidence
+            }
+          end
+
+          def decay_all
+            @models.each_value { |beliefs| beliefs.each(&:decay) }
+            prune_expired
+          end
+
+          def remove_agent(agent_id:)
+            @models.delete(agent_id)
+          end
+
+          def agent_count
+            @models.size
+          end
+
+          def belief_count
+            @models.values.sum(&:size)
+          end
+
+          def to_h
+            @models.transform_values { |beliefs| beliefs.map(&:to_h) }
+          end
+
+          private
+
+          def beliefs_on_subject(agent_id, subject)
+            beliefs_for(agent_id: agent_id).select { |b| b.subject == subject }
+          end
+
+          def ensure_agent_capacity(agent_id)
+            return if @models.size < Constants::MAX_AGENTS
+            return if @models.key?(agent_id)
+
+            oldest_key = @models.keys.first
+            @models.delete(oldest_key)
+          end
+
+          def prune_agent_beliefs(agent_id)
+            list = @models[agent_id]
+            return unless list && list.size > Constants::MAX_BELIEFS_PER_AGENT
+
+            @models[agent_id] = list.sort_by(&:confidence).last(Constants::MAX_BELIEFS_PER_AGENT)
+          end
+
+          def prune_expired
+            @models.each_value do |beliefs|
+              beliefs.reject! { |b| b.confidence <= Constants::BELIEF_FLOOR }
+            end
+            @models.reject! { |_, v| v.empty? }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Mentalizing
+      module Runners
+        module Mentalizing
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def attribute_belief(agent_id:, subject:, content:, confidence: nil, depth: 0, about_agent_id: nil, **)
+            depth = [depth.to_i, Helpers::Constants::MAX_RECURSION_DEPTH].min
+            conf  = confidence || Helpers::Constants::DEFAULT_CONFIDENCE
+            belief = mental_model.attribute_belief(
+              agent_id:       agent_id,
+              subject:        subject,
+              content:        content,
+              confidence:     conf.to_f,
+              depth:          depth,
+              about_agent_id: about_agent_id
+            )
+            Legion::Logging.debug "[mentalizing] attribute agent=#{agent_id} subject=#{subject} depth=#{depth} conf=#{belief.confidence.round(2)}"
+            { attributed: true, belief: belief.to_h }
+          end
+
+          def project_belief(subject:, own_belief:, other_agent_id:, **)
+            belief = mental_model.project_self(subject: subject, own_belief: own_belief.to_f, other_agent_id: other_agent_id)
+            Legion::Logging.debug "[mentalizing] project subject=#{subject} other=#{other_agent_id} discounted_conf=#{belief.confidence.round(2)}"
+            { projected: true, belief: belief.to_h }
+          end
+
+          def check_alignment(agent_a:, agent_b:, subject:, **)
+            score = mental_model.alignment(agent_a: agent_a, agent_b: agent_b, subject: subject)
+            Legion::Logging.debug "[mentalizing] alignment agent_a=#{agent_a} agent_b=#{agent_b} subject=#{subject} score=#{score.round(2)}"
+            { agent_a: agent_a, agent_b: agent_b, subject: subject, alignment: score.round(4) }
+          end
+
+          def detect_false_belief(agent_id:, subject:, reality:, **)
+            result = mental_model.detect_false_belief(agent_id: agent_id, subject: subject, reality: reality)
+            Legion::Logging.info "[mentalizing] false_belief_check agent=#{agent_id} subject=#{subject} false=#{result[:false_belief]}"
+            result
+          end
+
+          def beliefs_for_agent(agent_id:, **)
+            beliefs = mental_model.beliefs_for(agent_id: agent_id)
+            Legion::Logging.debug "[mentalizing] beliefs_for agent=#{agent_id} count=#{beliefs.size}"
+            { agent_id: agent_id, beliefs: beliefs.map(&:to_h), count: beliefs.size }
+          end
+
+          def beliefs_about_agent(about_agent_id:, **)
+            beliefs = mental_model.beliefs_about(about_agent_id: about_agent_id)
+            Legion::Logging.debug "[mentalizing] beliefs_about about=#{about_agent_id} count=#{beliefs.size}"
+            { about_agent_id: about_agent_id, beliefs: beliefs.map(&:to_h), count: beliefs.size }
+          end
+
+          def recursive_belief_lookup(agent_id:, about_agent_id:, subject:, **)
+            belief = mental_model.recursive_belief(agent_id: agent_id, about_agent_id: about_agent_id, subject: subject)
+            if belief
+              Legion::Logging.debug "[mentalizing] recursive agent=#{agent_id} about=#{about_agent_id} subject=#{subject} found=true"
+              { found: true, belief: belief.to_h }
+            else
+              Legion::Logging.debug "[mentalizing] recursive agent=#{agent_id} about=#{about_agent_id} subject=#{subject} found=false"
+              { found: false, agent_id: agent_id, about_agent_id: about_agent_id, subject: subject }
+            end
+          end
+
+          def update_mentalizing(**)
+            mental_model.decay_all
+            Legion::Logging.debug "[mentalizing] decay cycle agents=#{mental_model.agent_count} beliefs=#{mental_model.belief_count}"
+            { decayed: true, agents: mental_model.agent_count, beliefs: mental_model.belief_count }
+          end
+
+          def mentalizing_stats(**)
+            {
+              agents:  mental_model.agent_count,
+              beliefs: mental_model.belief_count
+            }
+          end
+
+          private
+
+          def mental_model
+            @mental_model ||= Helpers::MentalModel.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/mentalizing.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'legion/extensions/mentalizing/version'
+require 'legion/extensions/mentalizing/helpers/constants'
+require 'legion/extensions/mentalizing/helpers/belief_attribution'
+require 'legion/extensions/mentalizing/helpers/mental_model'
+require 'legion/extensions/mentalizing/runners/mentalizing'
+require 'legion/extensions/mentalizing/client'
+
+module Legion
+  module Extensions
+    module Mentalizing
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/mentalizing/client'
+
+RSpec.describe Legion::Extensions::Mentalizing::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to all runner methods' do
+    expect(client).to respond_to(:attribute_belief)
+    expect(client).to respond_to(:project_belief)
+    expect(client).to respond_to(:check_alignment)
+    expect(client).to respond_to(:detect_false_belief)
+    expect(client).to respond_to(:beliefs_for_agent)
+    expect(client).to respond_to(:beliefs_about_agent)
+    expect(client).to respond_to(:recursive_belief_lookup)
+    expect(client).to respond_to(:update_mentalizing)
+    expect(client).to respond_to(:mentalizing_stats)
+  end
+end

data/spec/legion/extensions/mentalizing/helpers/belief_attribution_spec.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Mentalizing::Helpers::BeliefAttribution do
+  subject(:belief) do
+    described_class.new(
+      agent_id:   'alice',
+      subject:    'weather',
+      content:    'it will rain',
+      confidence: 0.7,
+      depth:      1
+    )
+  end
+
+  describe '#initialize' do
+    it 'assigns fields correctly' do
+      expect(belief.agent_id).to eq('alice')
+      expect(belief.subject).to eq('weather')
+      expect(belief.content).to eq('it will rain')
+      expect(belief.depth).to eq(1)
+      expect(belief.about_agent_id).to be_nil
+    end
+
+    it 'clamps confidence to 0.0..1.0' do
+      over  = described_class.new(agent_id: 'a', subject: 's', content: 'c', confidence: 1.5)
+      under = described_class.new(agent_id: 'a', subject: 's', content: 'c', confidence: -0.5)
+      expect(over.confidence).to eq(1.0)
+      expect(under.confidence).to eq(0.0)
+    end
+
+    it 'assigns a uuid id' do
+      expect(belief.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'records created_at' do
+      expect(belief.created_at).to be_a(Time)
+    end
+  end
+
+  describe '#decay' do
+    it 'reduces confidence by BELIEF_DECAY' do
+      before = belief.confidence
+      belief.decay
+      expect(belief.confidence).to be_within(0.001).of(before - Legion::Extensions::Mentalizing::Helpers::Constants::BELIEF_DECAY)
+    end
+
+    it 'does not drop below BELIEF_FLOOR' do
+      20.times { belief.decay }
+      expect(belief.confidence).to be >= Legion::Extensions::Mentalizing::Helpers::Constants::BELIEF_FLOOR
+    end
+  end
+
+  describe '#reinforce' do
+    it 'increases confidence by CONFIDENCE_ALPHA by default' do
+      belief_low = described_class.new(agent_id: 'a', subject: 's', content: 'c', confidence: 0.3)
+      before = belief_low.confidence
+      belief_low.reinforce
+      expect(belief_low.confidence).to be_within(0.001).of(before + Legion::Extensions::Mentalizing::Helpers::Constants::CONFIDENCE_ALPHA)
+    end
+
+    it 'does not exceed 1.0' do
+      high = described_class.new(agent_id: 'a', subject: 's', content: 'c', confidence: 0.95)
+      high.reinforce(amount: 0.5)
+      expect(high.confidence).to eq(1.0)
+    end
+
+    it 'accepts custom amount' do
+      low = described_class.new(agent_id: 'a', subject: 's', content: 'c', confidence: 0.2)
+      low.reinforce(amount: 0.3)
+      expect(low.confidence).to be_within(0.001).of(0.5)
+    end
+  end
+
+  describe '#label' do
+    it 'returns :certain for high confidence' do
+      high = described_class.new(agent_id: 'a', subject: 's', content: 'c', confidence: 0.9)
+      expect(high.label).to eq(:certain)
+    end
+
+    it 'returns :confident for 0.6..0.8 range' do
+      mid = described_class.new(agent_id: 'a', subject: 's', content: 'c', confidence: 0.7)
+      expect(mid.label).to eq(:confident)
+    end
+
+    it 'returns :uncertain for 0.4..0.6 range' do
+      unc = described_class.new(agent_id: 'a', subject: 's', content: 'c', confidence: 0.5)
+      expect(unc.label).to eq(:uncertain)
+    end
+
+    it 'returns :speculative for 0.2..0.4 range' do
+      spec_b = described_class.new(agent_id: 'a', subject: 's', content: 'c', confidence: 0.3)
+      expect(spec_b.label).to eq(:speculative)
+    end
+
+    it 'returns :unknown for very low confidence' do
+      low = described_class.new(agent_id: 'a', subject: 's', content: 'c', confidence: 0.1)
+      expect(low.label).to eq(:unknown)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with all fields' do
+      h = belief.to_h
+      expect(h).to include(:id, :agent_id, :subject, :content, :confidence, :depth, :about_agent_id, :label, :created_at)
+      expect(h[:agent_id]).to eq('alice')
+      expect(h[:depth]).to eq(1)
+    end
+  end
+end

data/spec/legion/extensions/mentalizing/helpers/mental_model_spec.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Mentalizing::Helpers::MentalModel do
+  subject(:model) { described_class.new }
+
+  describe '#attribute_belief' do
+    it 'stores a belief and returns a BeliefAttribution' do
+      belief = model.attribute_belief(agent_id: 'alice', subject: 'rain', content: 'yes', confidence: 0.8)
+      expect(belief).to be_a(Legion::Extensions::Mentalizing::Helpers::BeliefAttribution)
+      expect(belief.agent_id).to eq('alice')
+    end
+
+    it 'stores separate beliefs per agent' do
+      model.attribute_belief(agent_id: 'alice', subject: 'rain', content: 'yes', confidence: 0.8)
+      model.attribute_belief(agent_id: 'bob',   subject: 'rain', content: 'no',  confidence: 0.6)
+      expect(model.beliefs_for(agent_id: 'alice').size).to eq(1)
+      expect(model.beliefs_for(agent_id: 'bob').size).to eq(1)
+    end
+
+    it 'caps depth at MAX_RECURSION_DEPTH' do
+      belief = model.attribute_belief(agent_id: 'alice', subject: 's', content: 'c', confidence: 0.5, depth: 99)
+      expect(belief.depth).to eq(Legion::Extensions::Mentalizing::Helpers::Constants::MAX_RECURSION_DEPTH)
+    end
+
+    it 'stores about_agent_id when provided' do
+      belief = model.attribute_belief(agent_id: 'alice', subject: 'trust', content: 'bob trusts me', confidence: 0.7, about_agent_id: 'bob')
+      expect(belief.about_agent_id).to eq('bob')
+    end
+  end
+
+  describe '#beliefs_for' do
+    it 'returns empty array for unknown agent' do
+      expect(model.beliefs_for(agent_id: 'nobody')).to eq([])
+    end
+
+    it 'returns all beliefs for known agent' do
+      model.attribute_belief(agent_id: 'alice', subject: 'rain', content: 'yes', confidence: 0.8)
+      model.attribute_belief(agent_id: 'alice', subject: 'snow', content: 'no',  confidence: 0.4)
+      expect(model.beliefs_for(agent_id: 'alice').size).to eq(2)
+    end
+  end
+
+  describe '#beliefs_about' do
+    it 'returns beliefs where about_agent_id matches' do
+      model.attribute_belief(agent_id: 'alice', subject: 'my_trust', content: 'low', confidence: 0.4, about_agent_id: 'me')
+      model.attribute_belief(agent_id: 'bob',   subject: 'my_trust', content: 'high', confidence: 0.9, about_agent_id: 'me')
+      model.attribute_belief(agent_id: 'carol', subject: 'other',    content: 'n/a',  confidence: 0.5, about_agent_id: 'other')
+      result = model.beliefs_about(about_agent_id: 'me')
+      expect(result.size).to eq(2)
+      expect(result.map(&:agent_id)).to contain_exactly('alice', 'bob')
+    end
+
+    it 'returns empty array when no beliefs about agent' do
+      expect(model.beliefs_about(about_agent_id: 'nobody')).to eq([])
+    end
+  end
+
+  describe '#recursive_belief' do
+    it 'returns nil when no matching recursive belief exists' do
+      result = model.recursive_belief(agent_id: 'alice', about_agent_id: 'bob', subject: 'rain')
+      expect(result).to be_nil
+    end
+
+    it 'returns the highest-confidence matching belief' do
+      model.attribute_belief(agent_id: 'alice', subject: 'rain', content: 'low',  confidence: 0.4, about_agent_id: 'bob')
+      model.attribute_belief(agent_id: 'alice', subject: 'rain', content: 'high', confidence: 0.9, about_agent_id: 'bob')
+      result = model.recursive_belief(agent_id: 'alice', about_agent_id: 'bob', subject: 'rain')
+      expect(result.content).to eq('high')
+    end
+  end
+
+  describe '#project_self' do
+    it 'creates a depth-1 belief attributed to :self' do
+      belief = model.project_self(subject: 'plan', own_belief: 0.8, other_agent_id: 'bob')
+      expect(belief.agent_id).to eq(:self)
+      expect(belief.depth).to eq(1)
+      expect(belief.about_agent_id).to eq('bob')
+    end
+
+    it 'discounts confidence by PROJECTION_DISCOUNT' do
+      discount = Legion::Extensions::Mentalizing::Helpers::Constants::PROJECTION_DISCOUNT
+      belief = model.project_self(subject: 'plan', own_belief: 1.0, other_agent_id: 'bob')
+      expect(belief.confidence).to be_within(0.001).of(discount)
+    end
+
+    it 'clamps discounted confidence to 1.0' do
+      belief = model.project_self(subject: 'plan', own_belief: 0.1, other_agent_id: 'bob')
+      expect(belief.confidence).to be >= 0.0
+      expect(belief.confidence).to be <= 1.0
+    end
+  end
+
+  describe '#alignment' do
+    it 'returns 0.0 when either agent has no beliefs on subject' do
+      model.attribute_belief(agent_id: 'alice', subject: 'rain', content: 'yes', confidence: 0.8)
+      expect(model.alignment(agent_a: 'alice', agent_b: 'bob', subject: 'rain')).to eq(0.0)
+    end
+
+    it 'returns 1.0 when both agents have identical confidence' do
+      model.attribute_belief(agent_id: 'alice', subject: 'rain', content: 'yes', confidence: 0.7)
+      model.attribute_belief(agent_id: 'bob',   subject: 'rain', content: 'yes', confidence: 0.7)
+      expect(model.alignment(agent_a: 'alice', agent_b: 'bob', subject: 'rain')).to be_within(0.001).of(1.0)
+    end
+
+    it 'returns lower score for divergent beliefs' do
+      model.attribute_belief(agent_id: 'alice', subject: 'rain', content: 'high', confidence: 0.9)
+      model.attribute_belief(agent_id: 'bob',   subject: 'rain', content: 'low',  confidence: 0.1)
+      score = model.alignment(agent_a: 'alice', agent_b: 'bob', subject: 'rain')
+      expect(score).to be < 0.5
+    end
+  end
+
+  describe '#detect_false_belief' do
+    it 'returns false_belief: false when belief matches reality' do
+      model.attribute_belief(agent_id: 'alice', subject: 'weather', content: 'sunny', confidence: 0.8)
+      result = model.detect_false_belief(agent_id: 'alice', subject: 'weather', reality: 'sunny')
+      expect(result[:false_belief]).to be false
+    end
+
+    it 'returns false_belief: true when belief contradicts reality' do
+      model.attribute_belief(agent_id: 'alice', subject: 'weather', content: 'sunny', confidence: 0.8)
+      result = model.detect_false_belief(agent_id: 'alice', subject: 'weather', reality: 'raining')
+      expect(result[:false_belief]).to be true
+      expect(result[:held_belief]).to eq('sunny')
+      expect(result[:reality]).to eq('raining')
+    end
+
+    it 'returns no_beliefs reason when agent has no beliefs on subject' do
+      result = model.detect_false_belief(agent_id: 'nobody', subject: 'weather', reality: 'sunny')
+      expect(result[:false_belief]).to be false
+      expect(result[:reason]).to eq(:no_beliefs)
+    end
+  end
+
+  describe '#decay_all' do
+    it 'reduces confidence on all beliefs' do
+      model.attribute_belief(agent_id: 'alice', subject: 'rain', content: 'yes', confidence: 0.8)
+      before = model.beliefs_for(agent_id: 'alice').first.confidence
+      model.decay_all
+      after = model.beliefs_for(agent_id: 'alice').first&.confidence
+      expect(after).to be_nil.or be < before
+    end
+
+    it 'prunes beliefs at or below BELIEF_FLOOR' do
+      model.attribute_belief(agent_id: 'alice', subject: 'rain', content: 'yes',
+                             confidence: Legion::Extensions::Mentalizing::Helpers::Constants::BELIEF_FLOOR)
+      model.decay_all
+      expect(model.beliefs_for(agent_id: 'alice')).to be_empty
+    end
+  end
+
+  describe '#remove_agent' do
+    it 'removes all beliefs for the agent' do
+      model.attribute_belief(agent_id: 'alice', subject: 'rain', content: 'yes', confidence: 0.8)
+      model.remove_agent(agent_id: 'alice')
+      expect(model.beliefs_for(agent_id: 'alice')).to eq([])
+    end
+  end
+
+  describe '#agent_count and #belief_count' do
+    it 'tracks counts correctly' do
+      expect(model.agent_count).to eq(0)
+      expect(model.belief_count).to eq(0)
+      model.attribute_belief(agent_id: 'alice', subject: 'rain', content: 'yes', confidence: 0.8)
+      model.attribute_belief(agent_id: 'bob',   subject: 'snow', content: 'no',  confidence: 0.5)
+      expect(model.agent_count).to eq(2)
+      expect(model.belief_count).to eq(2)
+    end
+  end
+
+  describe '#to_h' do
+    it 'serializes all beliefs as hashes' do
+      model.attribute_belief(agent_id: 'alice', subject: 'rain', content: 'yes', confidence: 0.8)
+      h = model.to_h
+      expect(h).to have_key('alice')
+      expect(h['alice'].first).to include(:agent_id, :subject, :confidence)
+    end
+  end
+end

data/spec/legion/extensions/mentalizing/runners/mentalizing_spec.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/mentalizing/client'
+
+RSpec.describe Legion::Extensions::Mentalizing::Runners::Mentalizing do
+  let(:client) { Legion::Extensions::Mentalizing::Client.new }
+
+  describe '#attribute_belief' do
+    it 'returns attributed: true with belief hash' do
+      result = client.attribute_belief(agent_id: 'alice', subject: 'rain', content: 'yes', confidence: 0.8)
+      expect(result[:attributed]).to be true
+      expect(result[:belief]).to include(:id, :agent_id, :subject, :content, :confidence, :depth)
+    end
+
+    it 'defaults confidence to DEFAULT_CONFIDENCE when not provided' do
+      result = client.attribute_belief(agent_id: 'alice', subject: 'snow', content: 'maybe')
+      expect(result[:belief][:confidence]).to eq(Legion::Extensions::Mentalizing::Helpers::Constants::DEFAULT_CONFIDENCE)
+    end
+
+    it 'caps depth at MAX_RECURSION_DEPTH' do
+      result = client.attribute_belief(agent_id: 'alice', subject: 's', content: 'c', depth: 100)
+      expect(result[:belief][:depth]).to eq(Legion::Extensions::Mentalizing::Helpers::Constants::MAX_RECURSION_DEPTH)
+    end
+
+    it 'accepts depth 0 (first-order)' do
+      result = client.attribute_belief(agent_id: 'alice', subject: 'trust', content: 'high', confidence: 0.9, depth: 0)
+      expect(result[:belief][:depth]).to eq(0)
+    end
+
+    it 'stores about_agent_id for second-order beliefs' do
+      result = client.attribute_belief(agent_id: 'alice', subject: 'plan', content: 'I will act', confidence: 0.7,
+                                       depth: 1, about_agent_id: 'bob')
+      expect(result[:belief][:about_agent_id]).to eq('bob')
+    end
+  end
+
+  describe '#project_belief' do
+    it 'returns projected: true with discounted confidence' do
+      result = client.project_belief(subject: 'plan', own_belief: 0.8, other_agent_id: 'bob')
+      expect(result[:projected]).to be true
+      discount = Legion::Extensions::Mentalizing::Helpers::Constants::PROJECTION_DISCOUNT
+      expect(result[:belief][:confidence]).to be_within(0.001).of(0.8 * discount)
+    end
+
+    it 'creates depth-1 belief about the other agent' do
+      result = client.project_belief(subject: 'plan', own_belief: 1.0, other_agent_id: 'carol')
+      expect(result[:belief][:depth]).to eq(1)
+      expect(result[:belief][:about_agent_id]).to eq('carol')
+    end
+  end
+
+  describe '#check_alignment' do
+    it 'returns alignment score of 0.0 when no shared beliefs' do
+      result = client.check_alignment(agent_a: 'alice', agent_b: 'bob', subject: 'rain')
+      expect(result[:alignment]).to eq(0.0)
+    end
+
+    it 'returns alignment near 1.0 for identical confidences' do
+      client.attribute_belief(agent_id: 'alice', subject: 'rain', content: 'yes', confidence: 0.7)
+      client.attribute_belief(agent_id: 'bob',   subject: 'rain', content: 'yes', confidence: 0.7)
+      result = client.check_alignment(agent_a: 'alice', agent_b: 'bob', subject: 'rain')
+      expect(result[:alignment]).to be_within(0.001).of(1.0)
+    end
+
+    it 'returns subject in result' do
+      result = client.check_alignment(agent_a: 'alice', agent_b: 'bob', subject: 'rain')
+      expect(result[:subject]).to eq('rain')
+    end
+  end
+
+  describe '#detect_false_belief' do
+    it 'detects false belief when agent belief contradicts reality' do
+      client.attribute_belief(agent_id: 'alice', subject: 'weather', content: 'sunny', confidence: 0.9)
+      result = client.detect_false_belief(agent_id: 'alice', subject: 'weather', reality: 'raining')
+      expect(result[:false_belief]).to be true
+      expect(result[:held_belief]).to eq('sunny')
+    end
+
+    it 'returns false_belief: false when belief matches reality' do
+      client.attribute_belief(agent_id: 'alice', subject: 'weather', content: 'sunny', confidence: 0.9)
+      result = client.detect_false_belief(agent_id: 'alice', subject: 'weather', reality: 'sunny')
+      expect(result[:false_belief]).to be false
+    end
+
+    it 'returns no_beliefs reason when agent unknown' do
+      result = client.detect_false_belief(agent_id: 'nobody', subject: 'weather', reality: 'sunny')
+      expect(result[:reason]).to eq(:no_beliefs)
+    end
+  end
+
+  describe '#beliefs_for_agent' do
+    it 'returns empty beliefs for unknown agent' do
+      result = client.beliefs_for_agent(agent_id: 'nobody')
+      expect(result[:beliefs]).to eq([])
+      expect(result[:count]).to eq(0)
+    end
+
+    it 'returns beliefs for known agent' do
+      client.attribute_belief(agent_id: 'alice', subject: 'rain', content: 'yes', confidence: 0.8)
+      result = client.beliefs_for_agent(agent_id: 'alice')
+      expect(result[:count]).to eq(1)
+      expect(result[:beliefs].first[:agent_id]).to eq('alice')
+    end
+  end
+
+  describe '#beliefs_about_agent' do
+    it 'returns beliefs where about_agent_id matches' do
+      client.attribute_belief(agent_id: 'alice', subject: 'my_reliability', content: 'high', confidence: 0.8, about_agent_id: 'me')
+      client.attribute_belief(agent_id: 'bob',   subject: 'my_reliability', content: 'low',  confidence: 0.3, about_agent_id: 'me')
+      result = client.beliefs_about_agent(about_agent_id: 'me')
+      expect(result[:count]).to eq(2)
+    end
+
+    it 'returns empty when no beliefs about agent' do
+      result = client.beliefs_about_agent(about_agent_id: 'nobody')
+      expect(result[:count]).to eq(0)
+    end
+  end
+
+  describe '#recursive_belief_lookup' do
+    it 'returns found: false when no match' do
+      result = client.recursive_belief_lookup(agent_id: 'alice', about_agent_id: 'bob', subject: 'rain')
+      expect(result[:found]).to be false
+    end
+
+    it 'returns found: true with belief when match exists' do
+      client.attribute_belief(agent_id: 'alice', subject: 'rain', content: 'bob thinks rain', confidence: 0.75, about_agent_id: 'bob')
+      result = client.recursive_belief_lookup(agent_id: 'alice', about_agent_id: 'bob', subject: 'rain')
+      expect(result[:found]).to be true
+      expect(result[:belief][:content]).to eq('bob thinks rain')
+    end
+  end
+
+  describe '#update_mentalizing' do
+    it 'returns decayed: true' do
+      result = client.update_mentalizing
+      expect(result[:decayed]).to be true
+    end
+
+    it 'returns agent and belief counts' do
+      client.attribute_belief(agent_id: 'alice', subject: 'rain', content: 'yes', confidence: 0.8)
+      result = client.update_mentalizing
+      expect(result).to have_key(:agents)
+      expect(result).to have_key(:beliefs)
+    end
+  end
+
+  describe '#mentalizing_stats' do
+    it 'returns agents and beliefs counts' do
+      result = client.mentalizing_stats
+      expect(result).to include(:agents, :beliefs)
+    end
+
+    it 'reflects current state' do
+      client.attribute_belief(agent_id: 'alice', subject: 'rain', content: 'yes', confidence: 0.8)
+      client.attribute_belief(agent_id: 'bob',   subject: 'snow', content: 'no',  confidence: 0.5)
+      result = client.mentalizing_stats
+      expect(result[:agents]).to eq(2)
+      expect(result[:beliefs]).to eq(2)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+module Legion
+  module Logging
+    def self.debug(_msg); end
+    def self.info(_msg); end
+    def self.warn(_msg); end
+    def self.error(_msg); end
+  end
+end
+
+require 'legion/extensions/mentalizing'
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = '.rspec_status'
+  config.disable_monkey_patching!
+  config.expect_with(:rspec) { |c| c.syntax = :expect }
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: lex-mentalizing
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Esity
+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: Second-order Theory of Mind for brain-modeled agentic AI. Recursive belief
+  attribution, false-belief detection, and social alignment modeling.
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-mentalizing.gemspec
+- lib/legion/extensions/mentalizing.rb
+- lib/legion/extensions/mentalizing/actors/decay.rb
+- lib/legion/extensions/mentalizing/client.rb
+- lib/legion/extensions/mentalizing/helpers/belief_attribution.rb
+- lib/legion/extensions/mentalizing/helpers/constants.rb
+- lib/legion/extensions/mentalizing/helpers/mental_model.rb
+- lib/legion/extensions/mentalizing/runners/mentalizing.rb
+- lib/legion/extensions/mentalizing/version.rb
+- spec/legion/extensions/mentalizing/client_spec.rb
+- spec/legion/extensions/mentalizing/helpers/belief_attribution_spec.rb
+- spec/legion/extensions/mentalizing/helpers/mental_model_spec.rb
+- spec/legion/extensions/mentalizing/runners/mentalizing_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-mentalizing
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-mentalizing
+  source_code_uri: https://github.com/LegionIO/lex-mentalizing
+  documentation_uri: https://github.com/LegionIO/lex-mentalizing
+  changelog_uri: https://github.com/LegionIO/lex-mentalizing
+  bug_tracker_uri: https://github.com/LegionIO/lex-mentalizing/issues
+  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: LEX Mentalizing
+test_files: []