lex-agentic-social 0.1.0

data/lib/legion/extensions/agentic/social/joint_attention/helpers/joint_focus_manager.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module JointAttention
+          module Helpers
+            class JointFocusManager
+              include Constants
+
+              attr_reader :targets, :history
+
+              def initialize
+                @targets     = {}
+                @agent_focus = {}
+                @history     = []
+              end
+
+              def create_target(name:, domain:, priority:, creator:)
+                prune_targets if @targets.size >= MAX_TARGETS
+                target = AttentionTarget.new(
+                  name:             name,
+                  domain:           domain,
+                  priority:         priority,
+                  creator_agent_id: creator
+                )
+                @targets[target.id] = target
+                record_history(event: :target_created, target_id: target.id, agent_id: creator)
+                join_target(target_id: target.id, agent_id: creator)
+                target
+              end
+
+              def join_target(target_id:, agent_id:, gaze: nil)
+                target = @targets[target_id]
+                return :target_not_found unless target
+
+                current = agent_target_ids(agent_id)
+                return :capacity_exceeded if current.size >= MAX_SIMULTANEOUS_TARGETS && !current.include?(target_id)
+
+                result = target.add_attendee(agent_id: agent_id, gaze: gaze)
+                if result == :joined
+                  @agent_focus[agent_id] ||= []
+                  @agent_focus[agent_id] << target_id unless @agent_focus[agent_id].include?(target_id)
+                  record_history(event: :agent_joined, target_id: target_id, agent_id: agent_id)
+                end
+                result
+              end
+
+              def leave_target(target_id:, agent_id:)
+                target = @targets[target_id]
+                return :target_not_found unless target
+
+                result = target.remove_attendee(agent_id: agent_id)
+                if result == :removed
+                  @agent_focus[agent_id]&.delete(target_id)
+                  record_history(event: :agent_left, target_id: target_id, agent_id: agent_id)
+                end
+                result
+              end
+
+              def direct_attention(from_agent:, to_agent:, target_id:)
+                target = @targets[target_id]
+                return :target_not_found unless target
+
+                return :referrer_not_attending unless target.attendees.key?(from_agent)
+
+                join_result = join_target(target_id: target_id, agent_id: to_agent)
+                return join_result if join_result == :capacity_exceeded
+
+                target.boost_focus(agent_id: to_agent, amount: REFERRAL_BOOST) if target.attendees.key?(to_agent)
+                record_history(event: :attention_directed, target_id: target_id, from_agent: from_agent, to_agent: to_agent)
+                :directed
+              end
+
+              def establish_shared(target_id:, agent_a:, agent_b:)
+                target = @targets[target_id]
+                return :target_not_found unless target
+
+                result = target.establish_mutual_awareness(agent_a: agent_a, agent_b: agent_b)
+                record_history(event: :shared_awareness, target_id: target_id, agent_a: agent_a, agent_b: agent_b) if result == :established
+                result
+              end
+
+              def update_gaze(target_id:, agent_id:, gaze:)
+                target = @targets[target_id]
+                return :target_not_found unless target
+
+                target.update_gaze(agent_id: agent_id, gaze: gaze)
+              end
+
+              def targets_for_agent(agent_id:)
+                ids = agent_target_ids(agent_id)
+                ids.filter_map { |tid| @targets[tid] }
+              end
+
+              def attendees_for_target(target_id:)
+                target = @targets[target_id]
+                return [] unless target
+
+                target.attendees.keys
+              end
+
+              def shared_targets(agent_a:, agent_b:)
+                ids_a = agent_target_ids(agent_a)
+                ids_b = agent_target_ids(agent_b)
+                (ids_a & ids_b).filter_map { |tid| @targets[tid] }
+              end
+
+              def decay_all
+                @targets.each_value(&:decay)
+                @targets.each_value(&:prune_faded_attendees)
+                sync_agent_focus
+                @targets.reject! { |_, t| t.faded? }
+              end
+
+              def target_count
+                @targets.size
+              end
+
+              def to_h
+                {
+                  target_count: target_count,
+                  agent_count:  @agent_focus.count { |_, ids| ids.any? },
+                  history_size: @history.size,
+                  targets:      @targets.transform_values(&:to_h)
+                }
+              end
+
+              private
+
+              def agent_target_ids(agent_id)
+                @agent_focus.fetch(agent_id, [])
+              end
+
+              def sync_agent_focus
+                @agent_focus.each_value { |ids| ids.select! { |tid| @targets.key?(tid) } }
+              end
+
+              def record_history(event)
+                @history << event.merge(at: Time.now.utc)
+                @history.shift while @history.size > MAX_HISTORY
+              end
+
+              def prune_targets
+                sorted = @targets.values.sort_by { |t| [t.focus_strength, t.created_at] }
+                to_remove = sorted.first(@targets.size - MAX_TARGETS + 1)
+                to_remove.each { |t| @targets.delete(t.id) }
+                sync_agent_focus
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/social/joint_attention/runners/joint_attention.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module JointAttention
+          module Runners
+            module JointAttention
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def create_attention_target(name:, domain:, creator:, priority: 0.5, **)
+                target = joint_focus_manager.create_target(name: name, domain: domain, priority: priority, creator: creator)
+                Legion::Logging.debug "[joint_attention] create_target: name=#{name} domain=#{domain} priority=#{priority} " \
+                                      "creator=#{creator} id=#{target.id}"
+                { success: true, target: target.to_h }
+              end
+
+              def join_attention(target_id:, agent_id:, gaze: nil, **)
+                result = joint_focus_manager.join_target(target_id: target_id, agent_id: agent_id, gaze: gaze)
+                Legion::Logging.debug "[joint_attention] join: target_id=#{target_id} agent_id=#{agent_id} gaze=#{gaze} result=#{result}"
+                { success: %i[joined already_attending].include?(result), result: result, target_id: target_id, agent_id: agent_id }
+              end
+
+              def leave_attention(target_id:, agent_id:, **)
+                result = joint_focus_manager.leave_target(target_id: target_id, agent_id: agent_id)
+                Legion::Logging.debug "[joint_attention] leave: target_id=#{target_id} agent_id=#{agent_id} result=#{result}"
+                { success: result == :removed, result: result, target_id: target_id, agent_id: agent_id }
+              end
+
+              def direct_attention(from_agent:, to_agent:, target_id:, **)
+                result = joint_focus_manager.direct_attention(from_agent: from_agent, to_agent: to_agent, target_id: target_id)
+                Legion::Logging.debug "[joint_attention] direct: from=#{from_agent} to=#{to_agent} target_id=#{target_id} result=#{result}"
+                { success: %i[directed already_attending].include?(result), result: result, target_id: target_id,
+                  from_agent: from_agent, to_agent: to_agent }
+              end
+
+              def establish_mutual_awareness(target_id:, agent_a:, agent_b:, **)
+                result = joint_focus_manager.establish_shared(target_id: target_id, agent_a: agent_a, agent_b: agent_b)
+                Legion::Logging.debug "[joint_attention] mutual_awareness: target_id=#{target_id} " \
+                                      "agent_a=#{agent_a} agent_b=#{agent_b} result=#{result}"
+                { success: result == :established, result: result, target_id: target_id, agent_a: agent_a, agent_b: agent_b }
+              end
+
+              def update_gaze(target_id:, agent_id:, gaze:, **)
+                result = joint_focus_manager.update_gaze(target_id: target_id, agent_id: agent_id, gaze: gaze)
+                Legion::Logging.debug "[joint_attention] update_gaze: target_id=#{target_id} agent_id=#{agent_id} gaze=#{gaze} result=#{result}"
+                { success: result == :updated, result: result, target_id: target_id, agent_id: agent_id, gaze: gaze }
+              end
+
+              def shared_focus(agent_a:, agent_b:, **)
+                targets = joint_focus_manager.shared_targets(agent_a: agent_a, agent_b: agent_b)
+                Legion::Logging.debug "[joint_attention] shared_focus: agent_a=#{agent_a} agent_b=#{agent_b} count=#{targets.size}"
+                { success: true, agent_a: agent_a, agent_b: agent_b, shared_targets: targets.map(&:to_h), count: targets.size }
+              end
+
+              def attention_targets_for(agent_id:, **)
+                targets = joint_focus_manager.targets_for_agent(agent_id: agent_id)
+                Legion::Logging.debug "[joint_attention] targets_for: agent_id=#{agent_id} count=#{targets.size}"
+                { success: true, agent_id: agent_id, targets: targets.map(&:to_h), count: targets.size }
+              end
+
+              def update_joint_attention(**)
+                joint_focus_manager.decay_all
+                stats = joint_focus_manager.to_h
+                Legion::Logging.debug "[joint_attention] decay_tick: targets=#{stats[:target_count]} agents=#{stats[:agent_count]}"
+                { success: true, targets: stats[:target_count], agents: stats[:agent_count], history: stats[:history_size] }
+              end
+
+              def joint_attention_stats(**)
+                stats = joint_focus_manager.to_h
+                Legion::Logging.debug "[joint_attention] stats: targets=#{stats[:target_count]} agents=#{stats[:agent_count]}"
+                { success: true, stats: stats }
+              end
+
+              private
+
+              def joint_focus_manager
+                @joint_focus_manager ||= Helpers::JointFocusManager.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/social/joint_attention/version.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module JointAttention
+          VERSION = '0.1.0'
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/social/joint_attention.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'legion/extensions/agentic/social/joint_attention/version'
+require 'legion/extensions/agentic/social/joint_attention/helpers/constants'
+require 'legion/extensions/agentic/social/joint_attention/helpers/attention_target'
+require 'legion/extensions/agentic/social/joint_attention/helpers/joint_focus_manager'
+require 'legion/extensions/agentic/social/joint_attention/runners/joint_attention'
+require 'legion/extensions/agentic/social/joint_attention/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module JointAttention
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Social
+        module Mentalizing
+          module Actor
+            class Decay < Legion::Extensions::Actors::Every
+              def runner_class
+                Legion::Extensions::Agentic::Social::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
+  end
+end

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

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

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

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

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

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

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

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

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

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