lex-empathy 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 40db9aaaa8d96a3ba285d18ccad9acc7fafd91182c50c924b2bfa2c245e861bb
+  data.tar.gz: d70d356a8d62939a8ed5614956535991670ab0cde5b958c48e9db575135fcb34
+SHA512:
+  metadata.gz: 34685cb1524b649c3dde6115662ba3df9ee778772a648925b91463a7c4961139d5e2d0cea6f8663b6153a2603400d49ecbb9ab45974c356229a6430e129d9777
+  data.tar.gz: e45412bab0f4003356c941253953f874f77b41eb247248b87d1cb1b4dd17f217ba2e1277f05c31cee0d34f4756ae7ce77329b19e5152b0c674d3f1786f9ada93

data/Gemfile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :dev, :test do
+  gem 'rspec', '~> 3.12'
+  gem 'rubocop', '~> 1.75'
+  gem 'rubocop-rspec', '~> 3.0'
+end
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Iverson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,62 @@
+# lex-empathy
+
+Theory of Mind engine for the LegionIO brain-modeled cognitive architecture.
+
+## What It Does
+
+Models other agents' mental states — their beliefs, emotions, intentions, and cooperation stance. Enables prediction of how other agents will react to proposed actions, perspective-taking via narrative generation, and social climate assessment across the mesh. Updates mental models from observed behavior using exponential moving averages, so the model continuously improves as more observations arrive.
+
+## Usage
+
+```ruby
+client = Legion::Extensions::Empathy::Client.new
+
+# Observe another agent's behavior to build a mental model
+client.observe_agent(
+  agent_id: 'agent-b',
+  observation: {
+    goal: 'code_review',
+    emotion: :focused,
+    cooperation: :cooperative,
+    evidence_strength: 0.8
+  }
+)
+
+# Predict how they'll react to a proposed action
+client.predict_reaction(
+  agent_id: 'agent-b',
+  scenario: { emotional_impact: :positive, impact_on_agent: :beneficial }
+)
+# => { likely_response: :likely_agree, confidence: 0.65, reasoning: '...' }
+
+# Generate a perspective-taking narrative
+client.perspective_take(agent_id: 'agent-b')
+# => { narrative: "Agent agent-b appears to be pursuing code_review and seems focused...",
+#      model_confidence: 0.72 }
+
+# Survey cooperation across all tracked agents
+client.social_landscape
+# => { tracked_agents: 5, cooperative_count: 3, overall_climate: :harmonious, climate_label: :harmonious }
+
+# Track prediction accuracy over time
+client.update_prediction_accuracy(
+  agent_id: 'agent-b',
+  predicted: :likely_agree,
+  actual: :likely_agree
+)
+
+# Periodic maintenance: decay stale models
+client.update_empathy
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-empathy.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/empathy/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-empathy'
+  spec.version       = Legion::Extensions::Empathy::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Empathy'
+  spec.description   = 'Theory of mind engine — models other agents beliefs, emotions, intentions, and cooperation stance'
+  spec.homepage      = 'https://github.com/LegionIO/lex-empathy'
+  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-empathy'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-empathy'
+  spec.metadata['changelog_uri'] = 'https://github.com/LegionIO/lex-empathy'
+  spec.metadata['bug_tracker_uri'] = 'https://github.com/LegionIO/lex-empathy/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-empathy.gemspec Gemfile LICENSE README.md]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Empathy
+      class Client
+        include Runners::Empathy
+
+        attr_reader :model_store
+
+        def initialize(model_store: nil, **)
+          @model_store = model_store || Helpers::ModelStore.new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Empathy
+      module Helpers
+        module Constants
+          # Mental state dimensions tracked per agent
+          MENTAL_STATE_DIMENSIONS = %i[
+            believed_goal
+            emotional_state
+            attention_focus
+            confidence_level
+            cooperation_stance
+          ].freeze
+
+          # How quickly mental models update (EMA alpha)
+          MODEL_UPDATE_ALPHA = 0.2
+
+          # How long before a mental model is considered stale (seconds)
+          MODEL_STALENESS_THRESHOLD = 300
+
+          # Maximum number of tracked agents
+          MAX_TRACKED_AGENTS = 100
+
+          # Maximum interaction history per agent
+          MAX_INTERACTION_HISTORY = 50
+
+          # Prediction confidence thresholds
+          PREDICTION_CONFIDENT   = 0.7
+          PREDICTION_UNCERTAIN   = 0.4
+
+          # Cooperation stance values
+          COOPERATION_STANCES = %i[cooperative neutral competitive unknown].freeze
+
+          # Emotional state labels for other agents
+          INFERRED_EMOTIONS = %i[
+            calm focused stressed frustrated curious cautious enthusiastic unknown
+          ].freeze
+
+          # Perspective-taking accuracy tracking window
+          ACCURACY_WINDOW = 20
+
+          # Mental model decay rate (per decay cycle)
+          MODEL_DECAY_RATE = 0.01
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Empathy
+      module Helpers
+        class MentalModel
+          attr_reader :agent_id, :believed_goal, :emotional_state, :attention_focus,
+                      :confidence_level, :cooperation_stance, :interaction_history,
+                      :predictions, :created_at, :updated_at
+
+          def initialize(agent_id:)
+            @agent_id = agent_id
+            @believed_goal = nil
+            @emotional_state = :unknown
+            @attention_focus = nil
+            @confidence_level = 0.5
+            @cooperation_stance = :unknown
+            @interaction_history = []
+            @predictions = []
+            @prediction_outcomes = []
+            @created_at = Time.now.utc
+            @updated_at = @created_at
+          end
+
+          def update_from_observation(observation)
+            @updated_at = Time.now.utc
+
+            update_believed_goal(observation[:goal]) if observation[:goal]
+            update_emotional_state(observation[:emotion]) if observation[:emotion]
+            update_attention(observation[:attention]) if observation[:attention]
+            update_cooperation(observation[:cooperation]) if observation[:cooperation]
+            update_confidence(observation)
+
+            record_interaction(observation)
+          end
+
+          def predict_reaction(scenario)
+            prediction = {
+              prediction_id:     SecureRandom.uuid,
+              scenario:          scenario,
+              predicted_at:      Time.now.utc,
+              likely_response:   infer_response(scenario),
+              emotional_shift:   infer_emotional_shift(scenario),
+              cooperation_shift: infer_cooperation_shift(scenario),
+              confidence:        prediction_confidence
+            }
+
+            @predictions << prediction
+            @predictions = @predictions.last(Constants::MAX_INTERACTION_HISTORY)
+            prediction
+          end
+
+          def record_prediction_outcome(prediction_id:, actual_response:, accurate:)
+            pred = @predictions.find { |p| p[:prediction_id] == prediction_id }
+            return nil unless pred
+
+            pred[:actual_response] = actual_response
+            pred[:accurate] = accurate
+
+            @prediction_outcomes << { prediction_id: prediction_id, accurate: accurate, at: Time.now.utc }
+            @prediction_outcomes = @prediction_outcomes.last(Constants::ACCURACY_WINDOW)
+            accurate
+          end
+
+          def prediction_accuracy
+            return nil if @prediction_outcomes.empty?
+
+            correct = @prediction_outcomes.count { |o| o[:accurate] }
+            correct.to_f / @prediction_outcomes.size
+          end
+
+          def stale?
+            (Time.now.utc - @updated_at) > Constants::MODEL_STALENESS_THRESHOLD
+          end
+
+          def decay
+            @confidence_level = [(@confidence_level - Constants::MODEL_DECAY_RATE), 0.1].max
+          end
+
+          def to_h
+            {
+              agent_id:            @agent_id,
+              believed_goal:       @believed_goal,
+              emotional_state:     @emotional_state,
+              attention_focus:     @attention_focus,
+              confidence_level:    @confidence_level,
+              cooperation_stance:  @cooperation_stance,
+              interactions:        @interaction_history.size,
+              predictions_made:    @predictions.size,
+              prediction_accuracy: prediction_accuracy,
+              stale:               stale?,
+              created_at:          @created_at,
+              updated_at:          @updated_at
+            }
+          end
+
+          private
+
+          def update_believed_goal(goal)
+            @believed_goal = goal
+          end
+
+          def update_emotional_state(emotion)
+            sym = emotion.to_sym
+            @emotional_state = Constants::INFERRED_EMOTIONS.include?(sym) ? sym : :unknown
+          end
+
+          def update_attention(attention)
+            @attention_focus = attention
+          end
+
+          def update_cooperation(cooperation)
+            sym = cooperation.to_sym
+            @cooperation_stance = Constants::COOPERATION_STANCES.include?(sym) ? sym : :unknown
+          end
+
+          def update_confidence(observation)
+            evidence_strength = observation[:evidence_strength] || 0.5
+            alpha = Constants::MODEL_UPDATE_ALPHA
+            @confidence_level = (@confidence_level * (1 - alpha)) + (evidence_strength * alpha)
+            @confidence_level = @confidence_level.clamp(0.0, 1.0)
+          end
+
+          def record_interaction(observation)
+            @interaction_history << {
+              type:    observation[:interaction_type] || :observation,
+              summary: observation[:summary],
+              at:      Time.now.utc
+            }
+            @interaction_history = @interaction_history.last(Constants::MAX_INTERACTION_HISTORY)
+          end
+
+          def infer_response(scenario)
+            case @cooperation_stance
+            when :cooperative
+              scenario[:cooperative_option] || :likely_agree
+            when :competitive
+              scenario[:competitive_option] || :likely_resist
+            when :neutral
+              @confidence_level > 0.5 ? :likely_consider : :unpredictable
+            else
+              :unpredictable
+            end
+          end
+
+          def infer_emotional_shift(scenario)
+            impact = scenario[:emotional_impact] || :neutral
+            case impact
+            when :positive
+              :likely_positive
+            when :negative
+              stressed_states = %i[stressed frustrated cautious]
+              stressed_states.include?(@emotional_state) ? :likely_escalate : :likely_negative
+            else
+              :likely_stable
+            end
+          end
+
+          def infer_cooperation_shift(scenario)
+            return :stable if scenario[:impact_on_agent].nil?
+
+            case scenario[:impact_on_agent]
+            when :beneficial then :likely_more_cooperative
+            when :harmful then :likely_less_cooperative
+            else :stable
+            end
+          end
+
+          def prediction_confidence
+            base = @confidence_level
+            staleness_penalty = stale? ? 0.2 : 0.0
+            history_bonus = [@interaction_history.size / 20.0, 0.2].min
+
+            (base - staleness_penalty + history_bonus).clamp(0.1, 0.9)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/empathy/helpers/model_store.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Empathy
+      module Helpers
+        class ModelStore
+          attr_reader :models
+
+          def initialize
+            @models = {}
+          end
+
+          def get(agent_id)
+            @models[agent_id.to_s]
+          end
+
+          def get_or_create(agent_id)
+            key = agent_id.to_s
+            @models[key] ||= MentalModel.new(agent_id: key)
+          end
+
+          def update(agent_id, observation)
+            model = get_or_create(agent_id)
+            model.update_from_observation(observation)
+            evict_if_needed
+            model
+          end
+
+          def predict(agent_id, scenario)
+            model = get(agent_id)
+            return nil unless model
+
+            model.predict_reaction(scenario)
+          end
+
+          def decay_all
+            count = 0
+            @models.each_value do |model|
+              model.decay
+              count += 1
+            end
+            count
+          end
+
+          def remove_stale
+            stale_keys = @models.select { |_, m| m.stale? && m.interaction_history.empty? }.keys
+            stale_keys.each { |k| @models.delete(k) }
+            stale_keys.size
+          end
+
+          def all_models
+            @models.values
+          end
+
+          def by_cooperation(stance)
+            @models.values.select { |m| m.cooperation_stance == stance }
+          end
+
+          def by_emotion(emotion)
+            @models.values.select { |m| m.emotional_state == emotion }
+          end
+
+          def size
+            @models.size
+          end
+
+          def clear
+            @models.clear
+          end
+
+          private
+
+          def evict_if_needed
+            return unless @models.size > Constants::MAX_TRACKED_AGENTS
+
+            oldest = @models.min_by { |_, m| m.updated_at }
+            @models.delete(oldest[0]) if oldest
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Empathy
+      module Runners
+        module Empathy
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def observe_agent(agent_id:, observation: {}, **)
+            model = model_store.update(agent_id, observation)
+            Legion::Logging.debug "[empathy] observed: agent=#{agent_id} emotion=#{model.emotional_state} " \
+                                  "cooperation=#{model.cooperation_stance}"
+
+            {
+              agent_id:           agent_id,
+              emotional_state:    model.emotional_state,
+              cooperation_stance: model.cooperation_stance,
+              believed_goal:      model.believed_goal,
+              confidence:         model.confidence_level
+            }
+          end
+
+          def predict_reaction(agent_id:, scenario: {}, **)
+            prediction = model_store.predict(agent_id, scenario)
+
+            if prediction
+              Legion::Logging.debug "[empathy] prediction: agent=#{agent_id} response=#{prediction[:likely_response]} " \
+                                    "confidence=#{prediction[:confidence].round(2)}"
+              prediction
+            else
+              Legion::Logging.debug "[empathy] no model for agent=#{agent_id}"
+              { error: :no_model, agent_id: agent_id }
+            end
+          end
+
+          def record_outcome(agent_id:, prediction_id:, actual_response:, accurate:, **)
+            model = model_store.get(agent_id)
+            return { error: :no_model } unless model
+
+            result = model.record_prediction_outcome(
+              prediction_id:   prediction_id,
+              actual_response: actual_response,
+              accurate:        accurate
+            )
+
+            if result.nil?
+              { error: :prediction_not_found }
+            else
+              Legion::Logging.info "[empathy] outcome recorded: agent=#{agent_id} accurate=#{accurate} " \
+                                   "accuracy=#{model.prediction_accuracy&.round(2)}"
+              { agent_id: agent_id, accurate: accurate, current_accuracy: model.prediction_accuracy }
+            end
+          end
+
+          def perspective_take(agent_id:, **)
+            model = model_store.get(agent_id)
+            return { error: :no_model, agent_id: agent_id } unless model
+
+            narrative = build_perspective_narrative(model)
+            Legion::Logging.debug "[empathy] perspective: agent=#{agent_id}"
+
+            {
+              agent_id:  agent_id,
+              narrative: narrative,
+              model:     model.to_h
+            }
+          end
+
+          def social_landscape(**)
+            models = model_store.all_models
+            cooperative = model_store.by_cooperation(:cooperative).size
+            competitive = model_store.by_cooperation(:competitive).size
+            stressed = model_store.by_emotion(:stressed).size + model_store.by_emotion(:frustrated).size
+
+            Legion::Logging.debug "[empathy] landscape: agents=#{models.size} cooperative=#{cooperative} " \
+                                  "competitive=#{competitive} stressed=#{stressed}"
+
+            {
+              tracked_agents:    models.size,
+              cooperative_count: cooperative,
+              competitive_count: competitive,
+              stressed_count:    stressed,
+              stances:           stance_distribution(models),
+              emotions:          emotion_distribution(models),
+              overall_climate:   assess_climate(cooperative, competitive, stressed, models.size)
+            }
+          end
+
+          def decay_models(**)
+            decayed = model_store.decay_all
+            removed = model_store.remove_stale
+            Legion::Logging.debug "[empathy] decay: updated=#{decayed} stale_removed=#{removed}"
+            { decayed: decayed, stale_removed: removed }
+          end
+
+          def empathy_stats(**)
+            models = model_store.all_models
+            accuracies = models.filter_map(&:prediction_accuracy)
+
+            {
+              tracked_agents:      model_store.size,
+              total_predictions:   models.sum { |m| m.predictions.size },
+              avg_accuracy:        accuracies.empty? ? nil : (accuracies.sum / accuracies.size).round(3),
+              stale_models:        models.count(&:stale?),
+              cooperation_stances: stance_distribution(models)
+            }
+          end
+
+          private
+
+          def model_store
+            @model_store ||= Helpers::ModelStore.new
+          end
+
+          def build_perspective_narrative(model)
+            parts = []
+            parts << "Agent #{model.agent_id}"
+
+            parts << if model.believed_goal
+                       "appears to be pursuing #{model.believed_goal}"
+                     else
+                       'has no clearly observed goal'
+                     end
+
+            parts << "and seems #{model.emotional_state}" unless model.emotional_state == :unknown
+            parts << "with a #{model.cooperation_stance} stance" unless model.cooperation_stance == :unknown
+
+            parts << "(model is stale — last updated #{((Time.now.utc - model.updated_at) / 60).round(1)} minutes ago)" if model.stale?
+
+            parts << "— prediction accuracy: #{(model.prediction_accuracy * 100).round(1)}%" if model.prediction_accuracy
+
+            parts.join(' ')
+          end
+
+          def stance_distribution(models)
+            dist = Hash.new(0)
+            models.each { |m| dist[m.cooperation_stance] += 1 }
+            dist
+          end
+
+          def emotion_distribution(models)
+            dist = Hash.new(0)
+            models.each { |m| dist[m.emotional_state] += 1 }
+            dist
+          end
+
+          def assess_climate(cooperative, competitive, stressed, total)
+            return :empty if total.zero?
+
+            coop_ratio = cooperative.to_f / total
+            stress_ratio = stressed.to_f / total
+
+            if coop_ratio > 0.6
+              :harmonious
+            elsif stress_ratio > 0.4
+              :tense
+            elsif competitive > cooperative
+              :adversarial
+            else
+              :neutral
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/empathy.rb

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

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Empathy::Client do
+  it 'creates default model store' do
+    client = described_class.new
+    expect(client.model_store).to be_a(Legion::Extensions::Empathy::Helpers::ModelStore)
+  end
+
+  it 'accepts injected model store' do
+    store = Legion::Extensions::Empathy::Helpers::ModelStore.new
+    client = described_class.new(model_store: store)
+    expect(client.model_store).to equal(store)
+  end
+
+  it 'includes Empathy runner methods' do
+    client = described_class.new
+    expect(client).to respond_to(:observe_agent, :predict_reaction, :perspective_take,
+                                 :social_landscape, :empathy_stats)
+  end
+end

data/spec/legion/extensions/empathy/helpers/constants_spec.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Empathy::Helpers::Constants do
+  it 'defines 5 mental state dimensions' do
+    expect(described_class::MENTAL_STATE_DIMENSIONS.size).to eq(5)
+  end
+
+  it 'defines cooperation stances' do
+    expect(described_class::COOPERATION_STANCES).to include(:cooperative, :competitive, :neutral, :unknown)
+  end
+
+  it 'defines inferred emotions' do
+    expect(described_class::INFERRED_EMOTIONS).to include(:calm, :stressed, :curious, :unknown)
+  end
+
+  it 'defines prediction thresholds in order' do
+    expect(described_class::PREDICTION_UNCERTAIN).to be < described_class::PREDICTION_CONFIDENT
+  end
+
+  it 'sets MAX_TRACKED_AGENTS to 100' do
+    expect(described_class::MAX_TRACKED_AGENTS).to eq(100)
+  end
+end

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

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Empathy::Helpers::MentalModel do
+  subject(:model) { described_class.new(agent_id: 'agent-42') }
+
+  describe '#initialize' do
+    it 'sets agent_id' do
+      expect(model.agent_id).to eq('agent-42')
+    end
+
+    it 'starts with unknown emotional state' do
+      expect(model.emotional_state).to eq(:unknown)
+    end
+
+    it 'starts with unknown cooperation stance' do
+      expect(model.cooperation_stance).to eq(:unknown)
+    end
+
+    it 'starts with 0.5 confidence' do
+      expect(model.confidence_level).to eq(0.5)
+    end
+  end
+
+  describe '#update_from_observation' do
+    it 'updates believed goal' do
+      model.update_from_observation(goal: 'code_review')
+      expect(model.believed_goal).to eq('code_review')
+    end
+
+    it 'updates emotional state' do
+      model.update_from_observation(emotion: :focused)
+      expect(model.emotional_state).to eq(:focused)
+    end
+
+    it 'updates cooperation stance' do
+      model.update_from_observation(cooperation: :cooperative)
+      expect(model.cooperation_stance).to eq(:cooperative)
+    end
+
+    it 'records interaction history' do
+      model.update_from_observation(summary: 'sent a message')
+      expect(model.interaction_history.size).to eq(1)
+    end
+
+    it 'rejects unknown emotions as :unknown' do
+      model.update_from_observation(emotion: :nonexistent)
+      expect(model.emotional_state).to eq(:unknown)
+    end
+
+    it 'updates confidence via EMA' do
+      model.update_from_observation(evidence_strength: 0.9)
+      expect(model.confidence_level).to be > 0.5
+    end
+  end
+
+  describe '#predict_reaction' do
+    before do
+      model.update_from_observation(cooperation: :cooperative, emotion: :calm)
+    end
+
+    it 'returns a prediction hash' do
+      prediction = model.predict_reaction(emotional_impact: :positive)
+      expect(prediction).to have_key(:prediction_id)
+      expect(prediction).to have_key(:likely_response)
+      expect(prediction).to have_key(:confidence)
+    end
+
+    it 'predicts cooperative agents will likely agree' do
+      prediction = model.predict_reaction(cooperative_option: :accept)
+      expect(prediction[:likely_response]).to eq(:accept)
+    end
+
+    it 'stores predictions' do
+      model.predict_reaction({})
+      expect(model.predictions.size).to eq(1)
+    end
+  end
+
+  describe '#record_prediction_outcome' do
+    it 'records accurate prediction' do
+      prediction = model.predict_reaction({})
+      result = model.record_prediction_outcome(
+        prediction_id:   prediction[:prediction_id],
+        actual_response: :agreed,
+        accurate:        true
+      )
+      expect(result).to be true
+    end
+
+    it 'returns nil for unknown prediction' do
+      result = model.record_prediction_outcome(
+        prediction_id:   'nonexistent',
+        actual_response: :agreed,
+        accurate:        true
+      )
+      expect(result).to be_nil
+    end
+  end
+
+  describe '#prediction_accuracy' do
+    it 'returns nil with no outcomes' do
+      expect(model.prediction_accuracy).to be_nil
+    end
+
+    it 'computes accuracy from outcomes' do
+      3.times do
+        pred = model.predict_reaction({})
+        model.record_prediction_outcome(prediction_id: pred[:prediction_id],
+                                        actual_response: :ok, accurate: true)
+      end
+      pred = model.predict_reaction({})
+      model.record_prediction_outcome(prediction_id: pred[:prediction_id],
+                                      actual_response: :nope, accurate: false)
+
+      expect(model.prediction_accuracy).to eq(0.75)
+    end
+  end
+
+  describe '#stale?' do
+    it 'returns false when fresh' do
+      expect(model.stale?).to be false
+    end
+
+    it 'returns true when old' do
+      model.instance_variable_set(:@updated_at, Time.now.utc - 400)
+      expect(model.stale?).to be true
+    end
+  end
+
+  describe '#decay' do
+    it 'reduces confidence' do
+      original = model.confidence_level
+      model.decay
+      expect(model.confidence_level).to be < original
+    end
+
+    it 'floors confidence at 0.1' do
+      50.times { model.decay }
+      expect(model.confidence_level).to be >= 0.1
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a complete state hash' do
+      h = model.to_h
+      expect(h).to include(:agent_id, :believed_goal, :emotional_state,
+                           :cooperation_stance, :confidence_level, :stale)
+    end
+  end
+end

data/spec/legion/extensions/empathy/helpers/model_store_spec.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Empathy::Helpers::ModelStore do
+  subject(:store) { described_class.new }
+
+  describe '#get_or_create' do
+    it 'creates a new model for unknown agent' do
+      model = store.get_or_create('agent-1')
+      expect(model.agent_id).to eq('agent-1')
+    end
+
+    it 'returns existing model' do
+      m1 = store.get_or_create('agent-1')
+      m2 = store.get_or_create('agent-1')
+      expect(m1).to equal(m2)
+    end
+  end
+
+  describe '#update' do
+    it 'updates model with observation' do
+      model = store.update('agent-1', emotion: :focused, cooperation: :cooperative)
+      expect(model.emotional_state).to eq(:focused)
+    end
+
+    it 'increments store size' do
+      store.update('agent-1', {})
+      store.update('agent-2', {})
+      expect(store.size).to eq(2)
+    end
+  end
+
+  describe '#predict' do
+    it 'returns nil for unknown agent' do
+      expect(store.predict('nobody', {})).to be_nil
+    end
+
+    it 'returns prediction for known agent' do
+      store.update('agent-1', cooperation: :cooperative)
+      prediction = store.predict('agent-1', {})
+      expect(prediction).to have_key(:likely_response)
+    end
+  end
+
+  describe '#decay_all' do
+    it 'decays all models' do
+      store.update('agent-1', {})
+      store.update('agent-2', {})
+      count = store.decay_all
+      expect(count).to eq(2)
+    end
+  end
+
+  describe '#remove_stale' do
+    it 'removes stale models with no interactions' do
+      store.get_or_create('agent-old')
+      store.models['agent-old'].instance_variable_set(:@updated_at, Time.now.utc - 400)
+      removed = store.remove_stale
+      expect(removed).to eq(1)
+      expect(store.size).to eq(0)
+    end
+
+    it 'keeps stale models that have interactions' do
+      store.update('agent-old', summary: 'did something')
+      store.models['agent-old'].instance_variable_set(:@updated_at, Time.now.utc - 400)
+      removed = store.remove_stale
+      expect(removed).to eq(0)
+    end
+  end
+
+  describe '#by_cooperation' do
+    it 'filters by cooperation stance' do
+      store.update('a', cooperation: :cooperative)
+      store.update('b', cooperation: :competitive)
+      store.update('c', cooperation: :cooperative)
+      expect(store.by_cooperation(:cooperative).size).to eq(2)
+    end
+  end
+
+  describe '#by_emotion' do
+    it 'filters by emotional state' do
+      store.update('a', emotion: :stressed)
+      store.update('b', emotion: :calm)
+      expect(store.by_emotion(:stressed).size).to eq(1)
+    end
+  end
+
+  describe '#clear' do
+    it 'removes all models' do
+      store.update('a', {})
+      store.clear
+      expect(store.size).to eq(0)
+    end
+  end
+end

data/spec/legion/extensions/empathy/runners/empathy_spec.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Empathy::Runners::Empathy do
+  let(:client) { Legion::Extensions::Empathy::Client.new }
+
+  describe '#observe_agent' do
+    it 'creates a mental model from observation' do
+      result = client.observe_agent(agent_id: 'agent-b', observation: {
+                                      goal: 'testing', emotion: :focused, cooperation: :cooperative, evidence_strength: 0.8
+                                    })
+      expect(result[:emotional_state]).to eq(:focused)
+      expect(result[:cooperation_stance]).to eq(:cooperative)
+      expect(result[:believed_goal]).to eq('testing')
+    end
+
+    it 'updates existing models' do
+      client.observe_agent(agent_id: 'agent-b', observation: { emotion: :calm })
+      result = client.observe_agent(agent_id: 'agent-b', observation: { emotion: :stressed })
+      expect(result[:emotional_state]).to eq(:stressed)
+    end
+  end
+
+  describe '#predict_reaction' do
+    before do
+      client.observe_agent(agent_id: 'agent-b', observation: {
+                             cooperation: :cooperative, emotion: :calm
+                           })
+    end
+
+    it 'returns prediction for known agent' do
+      result = client.predict_reaction(agent_id: 'agent-b', scenario: {
+                                         emotional_impact: :positive, impact_on_agent: :beneficial
+                                       })
+      expect(result).to have_key(:likely_response)
+      expect(result).to have_key(:confidence)
+    end
+
+    it 'returns error for unknown agent' do
+      result = client.predict_reaction(agent_id: 'nobody', scenario: {})
+      expect(result[:error]).to eq(:no_model)
+    end
+  end
+
+  describe '#record_outcome' do
+    it 'records prediction outcome' do
+      client.observe_agent(agent_id: 'agent-b', observation: { cooperation: :cooperative })
+      prediction = client.predict_reaction(agent_id: 'agent-b', scenario: {})
+      result = client.record_outcome(
+        agent_id:        'agent-b',
+        prediction_id:   prediction[:prediction_id],
+        actual_response: :agreed,
+        accurate:        true
+      )
+      expect(result[:accurate]).to be true
+      expect(result[:current_accuracy]).to eq(1.0)
+    end
+
+    it 'returns error for unknown agent' do
+      result = client.record_outcome(agent_id: 'nobody', prediction_id: 'x',
+                                     actual_response: :ok, accurate: true)
+      expect(result[:error]).to eq(:no_model)
+    end
+
+    it 'returns error for unknown prediction' do
+      client.observe_agent(agent_id: 'agent-b', observation: {})
+      result = client.record_outcome(agent_id: 'agent-b', prediction_id: 'nonexistent',
+                                     actual_response: :ok, accurate: true)
+      expect(result[:error]).to eq(:prediction_not_found)
+    end
+  end
+
+  describe '#perspective_take' do
+    it 'generates narrative for known agent' do
+      client.observe_agent(agent_id: 'agent-b', observation: {
+                             goal: 'code_review', emotion: :focused, cooperation: :cooperative
+                           })
+      result = client.perspective_take(agent_id: 'agent-b')
+      expect(result[:narrative]).to include('agent-b')
+      expect(result[:narrative]).to include('code_review')
+    end
+
+    it 'returns error for unknown agent' do
+      result = client.perspective_take(agent_id: 'nobody')
+      expect(result[:error]).to eq(:no_model)
+    end
+  end
+
+  describe '#social_landscape' do
+    before do
+      client.observe_agent(agent_id: 'a', observation: { cooperation: :cooperative, emotion: :calm })
+      client.observe_agent(agent_id: 'b', observation: { cooperation: :cooperative, emotion: :focused })
+      client.observe_agent(agent_id: 'c', observation: { cooperation: :competitive, emotion: :stressed })
+    end
+
+    it 'returns social climate assessment' do
+      result = client.social_landscape
+      expect(result[:tracked_agents]).to eq(3)
+      expect(result[:cooperative_count]).to eq(2)
+      expect(result[:competitive_count]).to eq(1)
+      expect(result).to have_key(:overall_climate)
+    end
+
+    it 'assesses harmonious climate when mostly cooperative' do
+      client.observe_agent(agent_id: 'd', observation: { cooperation: :cooperative })
+      result = client.social_landscape
+      expect(result[:overall_climate]).to eq(:harmonious)
+    end
+  end
+
+  describe '#decay_models' do
+    it 'decays all models' do
+      client.observe_agent(agent_id: 'a', observation: {})
+      result = client.decay_models
+      expect(result[:decayed]).to eq(1)
+    end
+  end
+
+  describe '#empathy_stats' do
+    it 'returns summary statistics' do
+      client.observe_agent(agent_id: 'a', observation: { cooperation: :cooperative })
+      client.predict_reaction(agent_id: 'a', scenario: {})
+      result = client.empathy_stats
+      expect(result[:tracked_agents]).to eq(1)
+      expect(result[:total_predictions]).to eq(1)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Legion
+  module Logging
+    module_function
+
+    def debug(*); end
+
+    def info(*); end
+
+    def warn(*); end
+
+    def error(*); end
+  end
+
+  module Extensions
+    module Helpers; end
+  end
+end
+
+require 'legion/extensions/empathy'
+
+RSpec.configure do |config|
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+  config.order = :random
+  Kernel.srand config.seed
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: lex-empathy
+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: Theory of mind engine — models other agents beliefs, emotions, intentions,
+  and cooperation stance
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE
+- README.md
+- lex-empathy.gemspec
+- lib/legion/extensions/empathy.rb
+- lib/legion/extensions/empathy/client.rb
+- lib/legion/extensions/empathy/helpers/constants.rb
+- lib/legion/extensions/empathy/helpers/mental_model.rb
+- lib/legion/extensions/empathy/helpers/model_store.rb
+- lib/legion/extensions/empathy/runners/empathy.rb
+- lib/legion/extensions/empathy/version.rb
+- spec/legion/extensions/empathy/client_spec.rb
+- spec/legion/extensions/empathy/helpers/constants_spec.rb
+- spec/legion/extensions/empathy/helpers/mental_model_spec.rb
+- spec/legion/extensions/empathy/helpers/model_store_spec.rb
+- spec/legion/extensions/empathy/runners/empathy_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-empathy
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-empathy
+  source_code_uri: https://github.com/LegionIO/lex-empathy
+  documentation_uri: https://github.com/LegionIO/lex-empathy
+  changelog_uri: https://github.com/LegionIO/lex-empathy
+  bug_tracker_uri: https://github.com/LegionIO/lex-empathy/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 Empathy
+test_files: []