lex-agentic-attention 0.1.0

data/lib/legion/extensions/agentic/attention/feature_binding/helpers/binding_field.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module FeatureBinding
+          module Helpers
+            class BindingField
+              include Constants
+
+              attr_reader :features, :objects, :binding_history
+
+              def initialize
+                @features        = {}
+                @objects         = {}
+                @binding_history = []
+                @object_counter  = 0
+              end
+
+              def register_feature(id:, dimension:, value:, source: :perception, salience: 0.5)
+                return @features[id] if @features.key?(id)
+                return nil if @features.size >= MAX_FEATURES
+
+                @features[id] = Feature.new(id: id, dimension: dimension, value: value, source: source, salience: salience)
+              end
+
+              def bind(feature_ids:, attention: false)
+                ids = Array(feature_ids).select { |fid| @features.key?(fid) }
+                return nil if ids.size < 2
+                return nil if @objects.size >= MAX_OBJECTS
+
+                @object_counter += 1
+                obj_id = :"object_#{@object_counter}"
+                strength = attention ? DEFAULT_BINDING_STRENGTH + ATTENTION_BOOST : DEFAULT_BINDING_STRENGTH
+
+                obj = BoundObject.new(id: obj_id, feature_ids: ids, binding_strength: strength)
+                obj.confirm if attention
+                @objects[obj_id] = obj
+
+                record_binding(obj_id, ids, attention)
+                obj
+              end
+
+              def attend(object_id:)
+                obj = @objects[object_id]
+                return nil unless obj
+
+                obj.strengthen
+                obj.confirm unless obj.confirmed?
+                obj
+              end
+
+              def unbind(object_id:)
+                obj = @objects.delete(object_id)
+                !obj.nil?
+              end
+
+              def features_of(object_id:)
+                obj = @objects[object_id]
+                return [] unless obj
+
+                obj.feature_ids.filter_map { |fid| @features[fid]&.to_h }
+              end
+
+              def objects_with_feature(feature_id:)
+                @objects.values.select { |o| o.includes_feature?(feature_id) }.map(&:to_h)
+              end
+
+              def illusory_conjunctions
+                @objects.values.select { |o| o.state == :illusory }.map(&:to_h)
+              end
+
+              def unbound_features
+                bound_ids = @objects.values.flat_map(&:feature_ids).uniq
+                @features.values.reject { |f| bound_ids.include?(f.id) }.map(&:to_h)
+              end
+
+              def search_by_dimension(dimension:, value: nil)
+                matches = @features.values.select { |f| f.dimension == dimension }
+                matches = matches.select { |f| f.value == value } if value
+                matches.map(&:to_h)
+              end
+
+              def decay_all
+                @features.each_value(&:decay)
+                @features.reject! { |_, f| f.faded? }
+
+                @objects.each_value(&:decay)
+                @objects.reject! { |_, o| o.dissolved? }
+              end
+
+              def feature_count
+                @features.size
+              end
+
+              def object_count
+                @objects.size
+              end
+
+              def to_h
+                {
+                  features:          @features.size,
+                  objects:           @objects.size,
+                  confirmed_objects: @objects.values.count(&:confirmed?),
+                  illusory_count:    @objects.values.count { |o| o.state == :illusory },
+                  unbound_features:  unbound_features.size,
+                  history_size:      @binding_history.size
+                }
+              end
+
+              private
+
+              def record_binding(obj_id, feature_ids, attended)
+                @binding_history << { object_id: obj_id, features: feature_ids, attended: attended, at: Time.now.utc }
+                @binding_history.shift while @binding_history.size > MAX_BINDING_HISTORY
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/feature_binding/helpers/bound_object.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module FeatureBinding
+          module Helpers
+            class BoundObject
+              include Constants
+
+              attr_reader :id, :feature_ids, :bound_at, :confirmed_at
+              attr_accessor :binding_strength
+
+              def initialize(id:, feature_ids:, binding_strength: DEFAULT_BINDING_STRENGTH)
+                @id               = id
+                @feature_ids      = Array(feature_ids).uniq
+                @binding_strength = binding_strength.to_f.clamp(0.0, 1.0)
+                @bound_at         = Time.now.utc
+                @confirmed_at     = nil
+              end
+
+              def confirm
+                @confirmed_at = Time.now.utc
+                @binding_strength = [@binding_strength + ATTENTION_BOOST, 1.0].min
+              end
+
+              def confirmed?
+                !@confirmed_at.nil?
+              end
+
+              def strengthen(amount = ATTENTION_BOOST)
+                @binding_strength = [@binding_strength + amount, 1.0].min
+              end
+
+              def decay
+                @binding_strength = [@binding_strength - BINDING_DECAY, 0.0].max
+              end
+
+              def dissolved?
+                @binding_strength <= BINDING_STRENGTH_FLOOR
+              end
+
+              def state
+                if @binding_strength >= BINDING_CONFIRMATION_THRESHOLD && confirmed?
+                  :bound
+                elsif @binding_strength >= ILLUSORY_CONJUNCTION_THRESHOLD
+                  :tentative
+                elsif @binding_strength > BINDING_STRENGTH_FLOOR
+                  :illusory
+                else
+                  :unbound
+                end
+              end
+
+              def feature_count
+                @feature_ids.size
+              end
+
+              def includes_feature?(feature_id)
+                @feature_ids.include?(feature_id)
+              end
+
+              def strength_label
+                STRENGTH_LABELS.each { |range, lbl| return lbl if range.cover?(@binding_strength) }
+                :dissolving
+              end
+
+              def to_h
+                {
+                  id:               @id,
+                  features:         @feature_ids.dup,
+                  feature_count:    feature_count,
+                  binding_strength: @binding_strength.round(4),
+                  strength_label:   strength_label,
+                  state:            state,
+                  state_label:      BINDING_STATE_LABELS[state],
+                  confirmed:        confirmed?,
+                  bound_at:         @bound_at,
+                  confirmed_at:     @confirmed_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/feature_binding/helpers/constants.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module FeatureBinding
+          module Helpers
+            module Constants
+              MAX_FEATURES = 200
+              MAX_BINDINGS = 100
+              MAX_OBJECTS = 50
+              MAX_BINDING_HISTORY = 200
+
+              BINDING_STRENGTH_FLOOR = 0.05
+              BINDING_DECAY = 0.01
+              BINDING_ALPHA = 0.15
+              ATTENTION_BOOST = 0.3
+              DEFAULT_BINDING_STRENGTH = 0.3
+
+              ILLUSORY_CONJUNCTION_THRESHOLD = 0.3
+              BINDING_CONFIRMATION_THRESHOLD = 0.6
+              FEATURE_SALIENCE_FLOOR = 0.05
+
+              FEATURE_DIMENSIONS = %i[
+                shape color size motion texture location
+                pitch volume timbre temporal_pattern
+                semantic syntactic pragmatic
+                valence arousal familiarity
+              ].freeze
+
+              BINDING_STATE_LABELS = {
+                bound:     'features unified into coherent object',
+                tentative: 'binding forming, not yet confirmed',
+                illusory:  'incorrect binding (conjunction error)',
+                unbound:   'features floating in pre-attentive field'
+              }.freeze
+
+              STRENGTH_LABELS = {
+                (0.8..)     => :solid,
+                (0.6...0.8) => :firm,
+                (0.4...0.6) => :forming,
+                (0.2...0.4) => :weak,
+                (..0.2)     => :dissolving
+              }.freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/feature_binding/helpers/feature.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module FeatureBinding
+          module Helpers
+            class Feature
+              include Constants
+
+              attr_reader :id, :dimension, :value, :source, :detected_at
+              attr_accessor :salience
+
+              def initialize(id:, dimension:, value:, source: :perception, salience: 0.5)
+                @id          = id
+                @dimension   = dimension
+                @value       = value
+                @source      = source
+                @salience    = salience.to_f.clamp(0.0, 1.0)
+                @detected_at = Time.now.utc
+              end
+
+              def salient?
+                @salience > FEATURE_SALIENCE_FLOOR
+              end
+
+              def decay
+                @salience = [@salience - BINDING_DECAY, 0.0].max
+              end
+
+              def faded?
+                @salience <= FEATURE_SALIENCE_FLOOR
+              end
+
+              def to_h
+                {
+                  id:          @id,
+                  dimension:   @dimension,
+                  value:       @value,
+                  source:      @source,
+                  salience:    @salience.round(4),
+                  detected_at: @detected_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/feature_binding/runners/feature_binding.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module FeatureBinding
+          module Runners
+            module FeatureBinding
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def register_feature(id:, dimension:, value:, source: :perception, salience: 0.5, **)
+                Legion::Logging.debug "[feature_binding] register: id=#{id} dim=#{dimension} val=#{value}"
+                feature = field.register_feature(id: id, dimension: dimension, value: value, source: source,
+                                                 salience: salience)
+                if feature
+                  { success: true, feature: feature.to_h, total_features: field.feature_count }
+                else
+                  { success: false, reason: :limit_reached }
+                end
+              end
+
+              def bind_features(feature_ids:, attention: false, **)
+                Legion::Logging.debug "[feature_binding] bind: features=#{feature_ids} attention=#{attention}"
+                obj = field.bind(feature_ids: feature_ids, attention: attention)
+                if obj
+                  { success: true, object: obj.to_h, total_objects: field.object_count }
+                else
+                  { success: false, reason: :insufficient_features }
+                end
+              end
+
+              def attend_object(object_id:, **)
+                Legion::Logging.debug "[feature_binding] attend: object=#{object_id}"
+                obj = field.attend(object_id: object_id.to_sym)
+                if obj
+                  { success: true, object: obj.to_h }
+                else
+                  { success: false, reason: :not_found }
+                end
+              end
+
+              def unbind_object(object_id:, **)
+                Legion::Logging.debug "[feature_binding] unbind: object=#{object_id}"
+                removed = field.unbind(object_id: object_id.to_sym)
+                { success: removed }
+              end
+
+              def features_of_object(object_id:, **)
+                features = field.features_of(object_id: object_id.to_sym)
+                Legion::Logging.debug "[feature_binding] features_of: object=#{object_id} count=#{features.size}"
+                { success: true, features: features, count: features.size }
+              end
+
+              def objects_with(feature_id:, **)
+                objects = field.objects_with_feature(feature_id: feature_id)
+                Legion::Logging.debug "[feature_binding] objects_with: feature=#{feature_id} count=#{objects.size}"
+                { success: true, objects: objects, count: objects.size }
+              end
+
+              def illusory_conjunctions(**)
+                illusions = field.illusory_conjunctions
+                Legion::Logging.debug "[feature_binding] illusory: #{illusions.size}"
+                { success: true, illusory: illusions, count: illusions.size }
+              end
+
+              def unbound_features(**)
+                unbound = field.unbound_features
+                Legion::Logging.debug "[feature_binding] unbound: #{unbound.size}"
+                { success: true, unbound: unbound, count: unbound.size }
+              end
+
+              def search_features(dimension:, value: nil, **)
+                results = field.search_by_dimension(dimension: dimension, value: value)
+                Legion::Logging.debug "[feature_binding] search: dim=#{dimension} found=#{results.size}"
+                { success: true, results: results, count: results.size }
+              end
+
+              def update_feature_binding(**)
+                Legion::Logging.debug '[feature_binding] tick'
+                field.decay_all
+                { success: true, features: field.feature_count, objects: field.object_count }
+              end
+
+              def feature_binding_stats(**)
+                Legion::Logging.debug '[feature_binding] stats'
+                { success: true, stats: field.to_h }
+              end
+
+              private
+
+              def field
+                @field ||= Helpers::BindingField.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/feature_binding/version.rb

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

data/lib/legion/extensions/agentic/attention/feature_binding.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/attention/feature_binding/version'
+require 'legion/extensions/agentic/attention/feature_binding/helpers/constants'
+require 'legion/extensions/agentic/attention/feature_binding/helpers/feature'
+require 'legion/extensions/agentic/attention/feature_binding/helpers/bound_object'
+require 'legion/extensions/agentic/attention/feature_binding/helpers/binding_field'
+require 'legion/extensions/agentic/attention/feature_binding/runners/feature_binding'
+require 'legion/extensions/agentic/attention/feature_binding/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module FeatureBinding
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/focus/client.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/attention/focus/helpers/constants'
+require 'legion/extensions/agentic/attention/focus/helpers/focus'
+require 'legion/extensions/agentic/attention/focus/helpers/focus_manager'
+require 'legion/extensions/agentic/attention/focus/helpers/habituation'
+require 'legion/extensions/agentic/attention/focus/runners/attention'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Focus
+          class Client
+            include Runners::Attention
+
+            def initialize(**)
+              @focus_manager = Helpers::FocusManager.new
+              @habituation_model = Helpers::Habituation.new
+            end
+
+            private
+
+            attr_reader :focus_manager, :habituation_model
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/focus/helpers/constants.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Focus
+          module Helpers
+            module Constants
+              # Miller's law: 7 +/- 2 simultaneous attention targets
+              ATTENTIONAL_CAPACITY = 7
+
+              # Score weights
+              INTRINSIC_WEIGHT = 0.3
+              GOAL_RELEVANCE_WEIGHT = 0.3
+              NOVELTY_WEIGHT      = 0.2
+              HABITUATION_WEIGHT  = 0.2
+
+              # Habituation
+              HABITUATION_RATE    = 0.15  # how fast habituation builds per encounter
+              HABITUATION_DECAY   = 0.05  # how fast habituation fades per tick without signal
+              HABITUATION_CEILING = 0.95  # max habituation (never fully ignore)
+              NOVELTY_RESET_FACTOR = 0.3  # how much novelty reduces habituation
+
+              # Filtering thresholds
+              BACKGROUND_THRESHOLD = 0.2  # below this, signal is tagged :background
+              MINIMUM_THRESHOLD    = 0.05 # below this, signal is dropped entirely
+
+              # Focus
+              MAX_MANUAL_FOCUS    = 3     # max manually focused domains
+              FOCUS_BOOST         = 0.3   # attention boost for manually focused domains
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/focus/helpers/focus.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Focus
+          module Helpers
+            module Focus
+              module_function
+
+              def score_signal(signal, habituation_level: 0.0, goal_relevance: 0.0)
+                intrinsic = extract_salience(signal)
+                novelty = extract_novelty(signal)
+
+                weighted = (intrinsic * Constants::INTRINSIC_WEIGHT) +
+                           (goal_relevance * Constants::GOAL_RELEVANCE_WEIGHT) +
+                           (novelty * Constants::NOVELTY_WEIGHT) +
+                           ((1.0 - habituation_level) * Constants::HABITUATION_WEIGHT)
+
+                weighted.clamp(0.0, 1.0)
+              end
+
+              def extract_salience(signal)
+                return 0.0 unless signal.is_a?(Hash)
+
+                signal[:salience] || signal[:attention_score] || 0.0
+              end
+
+              def extract_novelty(signal)
+                return 0.5 unless signal.is_a?(Hash)
+
+                signal[:novelty] || 0.5
+              end
+
+              def extract_domain(signal)
+                return :general unless signal.is_a?(Hash)
+
+                signal[:domain] || signal[:source_type] || :general
+              end
+
+              def tag_signal(signal, attention_score:, attention_tier:)
+                return signal unless signal.is_a?(Hash)
+
+                signal.merge(attention_score: attention_score, attention_tier: attention_tier)
+              end
+
+              def attention_tier(score)
+                if score >= 0.7    then :spotlight
+                elsif score >= 0.4 then :peripheral
+                elsif score >= Constants::BACKGROUND_THRESHOLD then :background
+                else :filtered
+                end
+              end
+
+              def deduplicate(signals)
+                seen = {}
+                signals.each_with_object([]) do |signal, unique|
+                  key = signal_identity(signal)
+                  unless seen[key]
+                    seen[key] = true
+                    unique << signal
+                  end
+                end
+              end
+
+              def signal_identity(signal)
+                return signal.object_id unless signal.is_a?(Hash)
+
+                [signal[:source_type], signal[:domain], signal[:value]].hash
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/focus/helpers/focus_manager.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Focus
+          module Helpers
+            class FocusManager
+              attr_reader :manual_focus
+
+              def initialize
+                @manual_focus = {}
+              end
+
+              def focus_on(domain, reason: nil)
+                domain = domain.to_sym
+                return :already_focused if @manual_focus.key?(domain)
+                return :capacity_full if @manual_focus.size >= Constants::MAX_MANUAL_FOCUS
+
+                @manual_focus[domain] = { reason: reason, focused_at: Time.now.utc }
+                :focused
+              end
+
+              def release(domain)
+                domain = domain.to_sym
+                return :not_focused unless @manual_focus.key?(domain)
+
+                @manual_focus.delete(domain)
+                :released
+              end
+
+              def focused?(domain)
+                @manual_focus.key?(domain.to_sym)
+              end
+
+              def focus_boost(domain)
+                focused?(domain) ? Constants::FOCUS_BOOST : 0.0
+              end
+
+              def goal_relevance(signal, active_wonders: [])
+                domain = Focus.extract_domain(signal)
+                base_relevance = focus_boost(domain)
+
+                wonder_relevance = compute_wonder_relevance(signal, active_wonders)
+                [base_relevance + wonder_relevance, 1.0].min
+              end
+
+              private
+
+              def compute_wonder_relevance(signal, active_wonders)
+                return 0.0 if active_wonders.empty?
+
+                domain = Focus.extract_domain(signal)
+                matching = active_wonders.select { |w| w.is_a?(Hash) && w[:domain] == domain }
+                return 0.0 if matching.empty?
+
+                max_score = matching.map { |w| w[:salience] || 0.5 }.max
+                max_score * 0.5
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end