lex-agentic-social 0.1.0

data/spec/legion/extensions/agentic/social/joint_attention/runners/joint_attention_spec.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Social::JointAttention::Runners::JointAttention do
+  let(:client) { Legion::Extensions::Agentic::Social::JointAttention::Client.new }
+
+  let!(:target_result) do
+    client.create_attention_target(name: 'shared-task', domain: :work, priority: 0.7, creator: 'agent-1')
+  end
+  let(:target_id) { target_result[:target][:id] }
+
+  describe '#create_attention_target' do
+    it 'returns success: true' do
+      expect(target_result[:success]).to be true
+    end
+
+    it 'returns target with all fields' do
+      t = target_result[:target]
+      expect(t).to include(:id, :name, :domain, :priority, :creator_agent_id, :created_at, :attendee_count)
+    end
+
+    it 'sets the name correctly' do
+      expect(target_result[:target][:name]).to eq('shared-task')
+    end
+
+    it 'uses default priority when not specified' do
+      result = client.create_attention_target(name: 'default-prio', domain: :x, creator: 'a')
+      const = Legion::Extensions::Agentic::Social::JointAttention::Helpers::Constants::DEFAULT_FOCUS
+      expect(result[:target][:priority]).to be_within(0.01).of(const)
+    end
+
+    it 'auto-joins the creator' do
+      expect(target_result[:target][:attendee_count]).to eq(1)
+    end
+  end
+
+  describe '#join_attention' do
+    it 'joins a second agent and returns success' do
+      result = client.join_attention(target_id: target_id, agent_id: 'agent-2')
+      expect(result[:success]).to be true
+      expect(result[:result]).to eq(:joined)
+    end
+
+    it 'returns success for already_attending' do
+      client.join_attention(target_id: target_id, agent_id: 'agent-2')
+      result = client.join_attention(target_id: target_id, agent_id: 'agent-2')
+      expect(result[:success]).to be true
+      expect(result[:result]).to eq(:already_attending)
+    end
+
+    it 'returns success: false for unknown target' do
+      result = client.join_attention(target_id: 'bogus', agent_id: 'agent-2')
+      expect(result[:success]).to be false
+      expect(result[:result]).to eq(:target_not_found)
+    end
+
+    it 'includes target_id and agent_id in response' do
+      result = client.join_attention(target_id: target_id, agent_id: 'agent-2')
+      expect(result[:target_id]).to eq(target_id)
+      expect(result[:agent_id]).to eq('agent-2')
+    end
+
+    it 'accepts a gaze keyword' do
+      result = client.join_attention(target_id: target_id, agent_id: 'agent-2', gaze: :deadline)
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#leave_attention' do
+    before { client.join_attention(target_id: target_id, agent_id: 'agent-2') }
+
+    it 'removes the agent and returns success' do
+      result = client.leave_attention(target_id: target_id, agent_id: 'agent-2')
+      expect(result[:success]).to be true
+      expect(result[:result]).to eq(:removed)
+    end
+
+    it 'returns success: false for not_found' do
+      result = client.leave_attention(target_id: target_id, agent_id: 'never-joined')
+      expect(result[:success]).to be false
+    end
+
+    it 'returns success: false for unknown target' do
+      result = client.leave_attention(target_id: 'bogus', agent_id: 'agent-2')
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#direct_attention' do
+    it 'directs to_agent to target and returns success' do
+      result = client.direct_attention(from_agent: 'agent-1', to_agent: 'agent-2', target_id: target_id)
+      expect(result[:success]).to be true
+      expect(result[:result]).to eq(:directed)
+    end
+
+    it 'returns success: false for unknown target' do
+      result = client.direct_attention(from_agent: 'agent-1', to_agent: 'agent-2', target_id: 'bogus')
+      expect(result[:success]).to be false
+    end
+
+    it 'returns success: false when referrer is not attending' do
+      result = client.direct_attention(from_agent: 'nobody', to_agent: 'agent-2', target_id: target_id)
+      expect(result[:success]).to be false
+      expect(result[:result]).to eq(:referrer_not_attending)
+    end
+
+    it 'includes from_agent and to_agent in response' do
+      result = client.direct_attention(from_agent: 'agent-1', to_agent: 'agent-2', target_id: target_id)
+      expect(result[:from_agent]).to eq('agent-1')
+      expect(result[:to_agent]).to eq('agent-2')
+    end
+  end
+
+  describe '#establish_mutual_awareness' do
+    before { client.join_attention(target_id: target_id, agent_id: 'agent-2') }
+
+    it 'establishes shared awareness and returns success' do
+      result = client.establish_mutual_awareness(target_id: target_id, agent_a: 'agent-1', agent_b: 'agent-2')
+      expect(result[:success]).to be true
+      expect(result[:result]).to eq(:established)
+    end
+
+    it 'returns success: false for unknown target' do
+      result = client.establish_mutual_awareness(target_id: 'bogus', agent_a: 'agent-1', agent_b: 'agent-2')
+      expect(result[:success]).to be false
+    end
+
+    it 'returns success: false when one agent is not attending' do
+      result = client.establish_mutual_awareness(target_id: target_id, agent_a: 'agent-1', agent_b: 'stranger')
+      expect(result[:success]).to be false
+    end
+
+    it 'includes agent_a and agent_b in response' do
+      result = client.establish_mutual_awareness(target_id: target_id, agent_a: 'agent-1', agent_b: 'agent-2')
+      expect(result[:agent_a]).to eq('agent-1')
+      expect(result[:agent_b]).to eq('agent-2')
+    end
+  end
+
+  describe '#update_gaze' do
+    it 'updates gaze direction and returns success' do
+      result = client.update_gaze(target_id: target_id, agent_id: 'agent-1', gaze: :risk)
+      expect(result[:success]).to be true
+      expect(result[:result]).to eq(:updated)
+      expect(result[:gaze]).to eq(:risk)
+    end
+
+    it 'returns success: false for unknown target' do
+      result = client.update_gaze(target_id: 'bogus', agent_id: 'agent-1', gaze: :risk)
+      expect(result[:success]).to be false
+    end
+
+    it 'returns success: false for unknown agent' do
+      result = client.update_gaze(target_id: target_id, agent_id: 'nobody', gaze: :risk)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#shared_focus' do
+    it 'returns shared targets between two agents' do
+      client.join_attention(target_id: target_id, agent_id: 'agent-2')
+      result = client.shared_focus(agent_a: 'agent-1', agent_b: 'agent-2')
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(1)
+      expect(result[:shared_targets].first[:id]).to eq(target_id)
+    end
+
+    it 'returns empty when no shared targets' do
+      result = client.shared_focus(agent_a: 'agent-1', agent_b: 'loner')
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(0)
+      expect(result[:shared_targets]).to be_empty
+    end
+
+    it 'includes agent_a and agent_b in response' do
+      result = client.shared_focus(agent_a: 'agent-1', agent_b: 'agent-2')
+      expect(result[:agent_a]).to eq('agent-1')
+      expect(result[:agent_b]).to eq('agent-2')
+    end
+  end
+
+  describe '#attention_targets_for' do
+    it 'returns targets for an agent' do
+      result = client.attention_targets_for(agent_id: 'agent-1')
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(1)
+      expect(result[:targets].first[:id]).to eq(target_id)
+    end
+
+    it 'returns empty for unknown agent' do
+      result = client.attention_targets_for(agent_id: 'nobody')
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(0)
+    end
+
+    it 'includes agent_id in response' do
+      result = client.attention_targets_for(agent_id: 'agent-1')
+      expect(result[:agent_id]).to eq('agent-1')
+    end
+  end
+
+  describe '#update_joint_attention' do
+    it 'returns success with stats' do
+      result = client.update_joint_attention
+      expect(result[:success]).to be true
+      expect(result).to have_key(:targets)
+      expect(result).to have_key(:agents)
+      expect(result).to have_key(:history)
+    end
+
+    it 'reflects current target count' do
+      result = client.update_joint_attention
+      expect(result[:targets]).to be >= 1
+    end
+  end
+
+  describe '#joint_attention_stats' do
+    it 'returns success with full stats hash' do
+      result = client.joint_attention_stats
+      expect(result[:success]).to be true
+      expect(result[:stats]).to include(:target_count, :agent_count, :history_size, :targets)
+    end
+
+    it 'stats reflect created targets' do
+      stats = client.joint_attention_stats
+      expect(stats[:stats][:target_count]).to eq(1)
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/social/mentalizing/client'
+
+RSpec.describe Legion::Extensions::Agentic::Social::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/agentic/social/mentalizing/helpers/belief_attribution_spec.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Social::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::Agentic::Social::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::Agentic::Social::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::Agentic::Social::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/agentic/social/mentalizing/helpers/mental_model_spec.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Social::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::Agentic::Social::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::Agentic::Social::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::Agentic::Social::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::Agentic::Social::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