lex-joint-attention 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 53f2d7e37654d603ad4e24112ae12264f4c2aa62b1d1f5f9afa33f533cfa79ad
+  data.tar.gz: ac7ad7cf0c6b56837d3f104621f41c39b3a7bfe9b83cf0eae8121dbf521e9736
+SHA512:
+  metadata.gz: 7289dcb7ce22c9b3b9c7975d54de54149858b995d36f8d1f498d3867362f0de2cef29baaed01aa2d59eb8b00548280f6a5349ed624e6ea57f5089419d8dc6bab
+  data.tar.gz: 2141148896e3d02e86379e3919e6c701c6c685df2368ff9545526921e5921bb1b7f151941c970f8b086824996a8f2b7c0b3b7518db3a086237b1e557304d961f

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-joint-attention.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/joint_attention/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-joint-attention'
+  spec.version       = Legion::Extensions::JointAttention::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Joint Attention'
+  spec.description   = "Tomasello's joint attention framework for LegionIO — shared focus between agents, " \
+                       'mutual awareness tracking, referential communication, and collaborative attention ' \
+                       'management with focus decay and working-memory constraints.'
+  spec.homepage      = 'https://github.com/LegionIO/lex-joint-attention'
+  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-joint-attention'
+  spec.metadata['documentation_uri']     = 'https://github.com/LegionIO/lex-joint-attention'
+  spec.metadata['changelog_uri']         = 'https://github.com/LegionIO/lex-joint-attention'
+  spec.metadata['bug_tracker_uri']       = 'https://github.com/LegionIO/lex-joint-attention/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-joint-attention.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module JointAttention
+      module Actor
+        class Decay < Legion::Extensions::Actors::Every
+          def runner_class
+            Legion::Extensions::JointAttention::Runners::JointAttention
+          end
+
+          def runner_function
+            'update_joint_attention'
+          end
+
+          def time
+            120
+          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/joint_attention/client.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/joint_attention/helpers/constants'
+require 'legion/extensions/joint_attention/helpers/attention_target'
+require 'legion/extensions/joint_attention/helpers/joint_focus_manager'
+require 'legion/extensions/joint_attention/runners/joint_attention'
+
+module Legion
+  module Extensions
+    module JointAttention
+      class Client
+        include Runners::JointAttention
+
+        def initialize(joint_focus_manager: nil, **)
+          @joint_focus_manager = joint_focus_manager || Helpers::JointFocusManager.new
+        end
+
+        private
+
+        attr_reader :joint_focus_manager
+      end
+    end
+  end
+end

data/lib/legion/extensions/joint_attention/helpers/attention_target.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module JointAttention
+      module Helpers
+        class AttentionTarget
+          include Constants
+
+          attr_reader :id, :name, :domain, :priority, :creator_agent_id, :created_at, :attendees, :focus_strength
+
+          def initialize(name:, domain:, priority:, creator_agent_id:)
+            @id               = SecureRandom.uuid
+            @name             = name
+            @domain           = domain
+            @priority         = priority.clamp(0.0, 1.0)
+            @creator_agent_id = creator_agent_id
+            @created_at       = Time.now.utc
+            @attendees        = {}
+            @focus_strength   = DEFAULT_FOCUS
+          end
+
+          def add_attendee(agent_id:, gaze: nil)
+            return :at_capacity if @attendees.size >= MAX_ATTENDEES_PER_TARGET
+            return :already_attending if @attendees.key?(agent_id)
+
+            @attendees[agent_id] = {
+              focus:            DEFAULT_FOCUS,
+              gaze:             gaze,
+              joined_at:        Time.now.utc,
+              mutual_awareness: false
+            }
+            :joined
+          end
+
+          def remove_attendee(agent_id:)
+            return :not_found unless @attendees.key?(agent_id)
+
+            @attendees.delete(agent_id)
+            :removed
+          end
+
+          def update_gaze(agent_id:, gaze:)
+            return :not_found unless @attendees.key?(agent_id)
+
+            @attendees[agent_id][:gaze] = gaze
+            :updated
+          end
+
+          def boost_focus(agent_id:, amount:)
+            return :not_found unless @attendees.key?(agent_id)
+
+            current = @attendees[agent_id][:focus]
+            @attendees[agent_id][:focus] = [current + amount, 1.0].min
+            :boosted
+          end
+
+          def establish_mutual_awareness(agent_a:, agent_b:)
+            return :not_found unless @attendees.key?(agent_a) && @attendees.key?(agent_b)
+
+            bonus = SHARED_AWARENESS_BONUS
+            @attendees[agent_a][:mutual_awareness] = true
+            @attendees[agent_b][:mutual_awareness] = true
+            @attendees[agent_a][:focus] = [@attendees[agent_a][:focus] + bonus, 1.0].min
+            @attendees[agent_b][:focus] = [@attendees[agent_b][:focus] + bonus, 1.0].min
+            :established
+          end
+
+          def attendee_count
+            @attendees.size
+          end
+
+          def shared_awareness?
+            @attendees.count { |_, v| v[:mutual_awareness] } >= 2
+          end
+
+          def focus_label
+            FOCUS_LABELS.each { |range, lbl| return lbl if range.cover?(@focus_strength) }
+            :fading
+          end
+
+          def decay
+            @attendees.each_value do |info|
+              info[:focus] = [info[:focus] - FOCUS_DECAY, FOCUS_FLOOR].max
+            end
+            @focus_strength = if @attendees.empty?
+                                [@focus_strength - FOCUS_DECAY, FOCUS_FLOOR].max
+                              else
+                                @attendees.values.sum { |v| v[:focus] } / @attendees.size
+                              end
+          end
+
+          def faded?
+            @focus_strength <= FOCUS_FLOOR && @attendees.empty?
+          end
+
+          def prune_faded_attendees
+            @attendees.reject! { |_, v| v[:focus] <= FOCUS_FLOOR }
+          end
+
+          def to_h
+            {
+              id:               @id,
+              name:             @name,
+              domain:           @domain,
+              priority:         @priority,
+              creator_agent_id: @creator_agent_id,
+              created_at:       @created_at,
+              focus_strength:   @focus_strength.round(4),
+              focus_label:      focus_label,
+              attendee_count:   attendee_count,
+              shared_awareness: shared_awareness?,
+              attendees:        @attendees.transform_values { |v| v.merge(focus: v[:focus].round(4)) }
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module JointAttention
+      module Helpers
+        module Constants
+          MAX_TARGETS              = 100
+          MAX_ATTENDEES_PER_TARGET = 20
+          MAX_HISTORY              = 200
+          FOCUS_DECAY              = 0.015
+          FOCUS_FLOOR              = 0.05
+          FOCUS_ALPHA              = 0.12
+          DEFAULT_FOCUS            = 0.5
+          SHARED_AWARENESS_BONUS   = 0.15
+          REFERRAL_BOOST           = 0.2
+          MAX_SIMULTANEOUS_TARGETS = 5
+
+          FOCUS_LABELS = {
+            (0.8..)     => :locked_on,
+            (0.6...0.8) => :focused,
+            (0.4...0.6) => :attending,
+            (0.2...0.4) => :peripheral,
+            (..0.2)     => :fading
+          }.freeze
+        end
+      end
+    end
+  end
+end

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

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

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

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

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

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

data/lib/legion/extensions/joint_attention.rb

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

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::JointAttention::Client do
+  subject(:client) { described_class.new }
+
+  it 'instantiates without arguments' do
+    expect(client).to be_a(described_class)
+  end
+
+  it 'accepts an injected joint_focus_manager' do
+    mgr = Legion::Extensions::JointAttention::Helpers::JointFocusManager.new
+    c = described_class.new(joint_focus_manager: mgr)
+    expect(c).to be_a(described_class)
+  end
+
+  it 'includes runner methods' do
+    expect(client).to respond_to(:create_attention_target)
+    expect(client).to respond_to(:join_attention)
+    expect(client).to respond_to(:leave_attention)
+    expect(client).to respond_to(:direct_attention)
+    expect(client).to respond_to(:establish_mutual_awareness)
+    expect(client).to respond_to(:update_gaze)
+    expect(client).to respond_to(:shared_focus)
+    expect(client).to respond_to(:attention_targets_for)
+    expect(client).to respond_to(:update_joint_attention)
+    expect(client).to respond_to(:joint_attention_stats)
+  end
+
+  it 'two clients maintain independent state' do
+    c1 = described_class.new
+    c2 = described_class.new
+    c1.create_attention_target(name: 'only-in-c1', domain: :test, creator: 'agent-1')
+    expect(c1.joint_attention_stats[:stats][:target_count]).to eq(1)
+    expect(c2.joint_attention_stats[:stats][:target_count]).to eq(0)
+  end
+end