lex-agentic-attention 0.1.0

data/lib/legion/extensions/agentic/attention/schema/helpers/attention_schema_model.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Schema
+          module Helpers
+            class AttentionSchemaModel
+              include Constants
+
+              attr_reader :schema_items, :social_models, :meta_accuracy, :attention_history
+
+              def initialize
+                @schema_items    = {}    # target => SchemaItem
+                @social_models   = {}    # agent_id => { target:, awareness:, updated_at: }
+                @meta_accuracy   = 0.5   # EMA confidence in schema self-accuracy
+                @attention_history = []  # ring buffer of { target:, event:, at: }
+              end
+
+              # --- Focus Management ---
+
+              # Add or boost an item in the attention schema
+              def focus_on(target:, domain:, reason:, source:)
+                target = target.to_s
+                if @schema_items.key?(target)
+                  @schema_items[target].boost
+                  record_history(target, :refocused)
+                else
+                  prune_to_capacity if @schema_items.size >= MAX_SCHEMA_ITEMS
+                  @schema_items[target] = SchemaItem.new(
+                    target:          target,
+                    domain:          domain,
+                    reason:          reason,
+                    source:          source,
+                    awareness_level: DEFAULT_AWARENESS + AWARENESS_BOOST
+                  )
+                  record_history(target, :focused)
+                end
+                @schema_items[target]
+              end
+
+              # Remove an item from the schema entirely
+              def defocus(target:)
+                target = target.to_s
+                removed = @schema_items.delete(target)
+                record_history(target, :defocused) if removed
+                !removed.nil?
+              end
+
+              # --- Awareness Query (core AST operation) ---
+
+              # "Am I aware of X?" — the central Graziano query
+              def am_i_aware_of(target:)
+                item = @schema_items[target.to_s]
+                return { aware: false, awareness_level: 0.0, label: :unconscious } unless item
+
+                { aware: item.awareness_level > AWARENESS_FLOOR, awareness_level: item.awareness_level.round(4), label: item.label }
+              end
+
+              # --- Attention Report ---
+
+              # Natural-language-style summary of current attention state
+              def report_awareness
+                state     = attention_state
+                state_str = ATTENTION_STATE_LABELS[state] || 'in an unknown state'
+                top_items = top_schema_items(3)
+
+                return { state: state, state_label: state_str, report: 'No active attention targets.', items: [] } if top_items.empty?
+
+                primary  = top_items.first
+                summary  = "I am #{state_str}, primarily attending to '#{primary[:target]}' " \
+                           "(#{primary[:label]}, #{primary[:awareness_level]}). " \
+                           "Reason: #{primary[:reason]}."
+
+                if top_items.size > 1
+                  secondary = top_items[1..]
+                              .map { |i| "'#{i[:target]}' (#{i[:label]})" }
+                              .join(', ')
+                  summary += " Also attending to: #{secondary}."
+                end
+
+                { state: state, state_label: state_str, report: summary, items: top_items }
+              end
+
+              # --- Attention State Classification ---
+
+              # Overall qualitative attention state
+              def attention_state
+                return :distracted if @schema_items.empty?
+
+                top = top_awareness
+                avg = average_awareness
+
+                if top >= HYPERFOCUS_THRESHOLD
+                  :hyperfocused
+                elsif avg < DRIFT_THRESHOLD && @schema_items.size > 3
+                  :distracted
+                elsif avg < DRIFT_THRESHOLD
+                  :drifting
+                elsif top >= 0.6
+                  :focused
+                else
+                  :normal
+                end
+              end
+
+              # --- Social Attention Modeling ---
+
+              # Record what another agent appears to be attending to
+              def model_other_attention(agent_id:, target:, awareness:)
+                agent_id = agent_id.to_s
+                prune_social_models if @social_models.size >= MAX_SOCIAL_MODELS && !@social_models.key?(agent_id)
+                @social_models[agent_id] = {
+                  target:     target.to_s,
+                  awareness:  awareness.clamp(0.0, 1.0),
+                  updated_at: Time.now.utc
+                }
+              end
+
+              # Query what another agent is modeled as attending to
+              def query_other_attention(agent_id:)
+                @social_models[agent_id.to_s]
+              end
+
+              # --- Meta-Attention ---
+
+              # Assess whether meta-attention signals are active
+              def meta_check
+                state = attention_state
+                signals = []
+
+                signals << :drifting   if %i[drifting distracted].include?(state)
+                signals << :hyperfocus if state == :hyperfocused
+                signals << :normal     if signals.empty?
+
+                top = top_awareness
+                avg = average_awareness
+
+                {
+                  state:         state,
+                  signals:       signals,
+                  top_awareness: top.round(4),
+                  avg_awareness: avg.round(4),
+                  schema_size:   @schema_items.size,
+                  meta_accuracy: @meta_accuracy.round(4)
+                }
+              end
+
+              # Update the EMA tracking how well the schema predicted actual attention
+              def update_meta_accuracy(was_correct:)
+                correction = was_correct ? 1.0 : 0.0
+                @meta_accuracy += (META_ATTENTION_ALPHA * (correction - @meta_accuracy))
+              end
+
+              # --- Decay ---
+
+              # Apply per-tick decay to all schema items and prune faded ones
+              def decay_all
+                @schema_items.each_value(&:decay)
+                @schema_items.reject! { |_, item| item.faded? }
+              end
+
+              # --- Accessors ---
+
+              def schema_size
+                @schema_items.size
+              end
+
+              def to_h
+                {
+                  state:         attention_state,
+                  state_label:   ATTENTION_STATE_LABELS[attention_state],
+                  schema_size:   schema_size,
+                  meta_accuracy: @meta_accuracy.round(4),
+                  top_awareness: top_awareness.round(4),
+                  avg_awareness: average_awareness.round(4),
+                  social_models: @social_models.size,
+                  items:         @schema_items.values.map(&:to_h)
+                }
+              end
+
+              private
+
+              def top_awareness
+                return 0.0 if @schema_items.empty?
+
+                @schema_items.values.map(&:awareness_level).max
+              end
+
+              def average_awareness
+                return 0.0 if @schema_items.empty?
+
+                vals = @schema_items.values.map(&:awareness_level)
+                vals.sum / vals.size
+              end
+
+              def top_schema_items(count = 3)
+                @schema_items.values
+                             .sort_by { |i| -i.awareness_level }
+                             .first(count)
+                             .map(&:to_h)
+              end
+
+              def prune_to_capacity
+                # Remove the item with the lowest awareness
+                weakest = @schema_items.min_by { |_, item| item.awareness_level }&.first
+                @schema_items.delete(weakest) if weakest
+              end
+
+              def prune_social_models
+                oldest = @social_models.min_by { |_, v| v[:updated_at] }&.first
+                @social_models.delete(oldest) if oldest
+              end
+
+              def record_history(target, event)
+                @attention_history << { target: target, event: event, at: Time.now.utc }
+                @attention_history.shift while @attention_history.size > MAX_HISTORY
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Schema
+          module Helpers
+            module Constants
+              # Maximum items the schema can model simultaneously
+              MAX_SCHEMA_ITEMS = 15
+
+              # Maximum other agents whose attention we model socially
+              MAX_SOCIAL_MODELS = 10
+
+              # EMA alpha for schema update speed
+              SCHEMA_UPDATE_ALPHA = 0.15
+
+              # Default awareness level for newly focused items
+              DEFAULT_AWARENESS = 0.3
+
+              # Minimum awareness before item is pruned from schema
+              AWARENESS_FLOOR = 0.05
+
+              # Per-tick decay applied to all schema items
+              AWARENESS_DECAY = 0.02
+
+              # Awareness boost applied when re-focusing an existing item
+              AWARENESS_BOOST = 0.15
+
+              # Below this awareness average: attention is drifting
+              DRIFT_THRESHOLD = 0.3
+
+              # Above this awareness (for top item): attention is hyper-focused
+              HYPERFOCUS_THRESHOLD = 0.85
+
+              # EMA alpha for meta-attention accuracy tracking
+              META_ATTENTION_ALPHA = 0.1
+
+              # Maximum entries kept in attention history ring buffer
+              MAX_HISTORY = 200
+
+              # Human-readable labels keyed by awareness level range
+              AWARENESS_LABELS = {
+                (0.8..)     => :vivid,
+                (0.6...0.8) => :clear,
+                (0.4...0.6) => :dim,
+                (0.2...0.4) => :peripheral,
+                (..0.2)     => :unconscious
+              }.freeze
+
+              # Human-readable attention-state labels
+              ATTENTION_STATE_LABELS = {
+                hyperfocused: 'deeply engaged',
+                focused:      'actively attending',
+                normal:       'casually aware',
+                drifting:     'attention waning',
+                distracted:   'attention scattered'
+              }.freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/schema/helpers/schema_item.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Schema
+          module Helpers
+            class SchemaItem
+              include Constants
+
+              attr_reader :target, :domain, :reason, :source, :created_at
+              attr_accessor :awareness_level
+
+              def initialize(target:, domain:, reason:, source:, awareness_level: DEFAULT_AWARENESS)
+                @target          = target
+                @domain          = domain
+                @reason          = reason
+                @source          = source
+                @awareness_level = awareness_level.clamp(0.0, 1.0)
+                @created_at      = Time.now.utc
+              end
+
+              # Duration in seconds since this item entered the schema
+              def duration
+                Time.now.utc - @created_at
+              end
+
+              # Apply a one-time boost (re-focus event)
+              def boost
+                @awareness_level = [@awareness_level + AWARENESS_BOOST, 1.0].min
+              end
+
+              # Apply per-tick decay
+              def decay
+                @awareness_level = [@awareness_level - AWARENESS_DECAY, AWARENESS_FLOOR].max
+              end
+
+              # True when awareness has dropped to the pruning floor
+              def faded?
+                @awareness_level <= AWARENESS_FLOOR
+              end
+
+              # Symbolic label describing current awareness intensity
+              def label
+                AWARENESS_LABELS.each { |range, lbl| return lbl if range.cover?(@awareness_level) }
+                :unconscious
+              end
+
+              def to_h
+                {
+                  target:          @target,
+                  domain:          @domain,
+                  awareness_level: @awareness_level.round(4),
+                  label:           label,
+                  reason:          @reason,
+                  source:          @source,
+                  duration:        duration.round(2),
+                  created_at:      @created_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/schema/runners/attention_schema.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Schema
+          module Runners
+            module AttentionSchema
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              # Focus attention on a target — adds or boosts it in the schema
+              def focus_on(target:, domain:, reason:, source: :external, **)
+                Legion::Logging.debug "[attention_schema] focus_on: target=#{target} domain=#{domain} source=#{source}"
+                item = schema_model.focus_on(target: target, domain: domain, reason: reason, source: source)
+                {
+                  success:         true,
+                  target:          item.target,
+                  domain:          item.domain,
+                  awareness_level: item.awareness_level.round(4),
+                  label:           item.label,
+                  schema_size:     schema_model.schema_size
+                }
+              end
+
+              # Remove a target from the attention schema
+              def defocus(target:, **)
+                Legion::Logging.debug "[attention_schema] defocus: target=#{target}"
+                removed = schema_model.defocus(target: target)
+                { success: true, target: target, removed: removed, schema_size: schema_model.schema_size }
+              end
+
+              # Core AST query: "am I aware of X?"
+              def am_i_aware_of(target:, **)
+                result = schema_model.am_i_aware_of(target: target)
+                Legion::Logging.debug "[attention_schema] am_i_aware_of: target=#{target} aware=#{result[:aware]} level=#{result[:awareness_level]}"
+                result.merge(success: true)
+              end
+
+              # Generate a natural-language attention awareness report
+              def report_awareness(**)
+                report = schema_model.report_awareness
+                Legion::Logging.debug "[attention_schema] report_awareness: state=#{report[:state]} items=#{report[:items].size}"
+                report.merge(success: true)
+              end
+
+              # Return the current qualitative attention state symbol
+              def attention_state(**)
+                state = schema_model.attention_state
+                label = Helpers::Constants::ATTENTION_STATE_LABELS[state]
+                Legion::Logging.debug "[attention_schema] attention_state: state=#{state}"
+                { success: true, state: state, label: label }
+              end
+
+              # Model another agent's attention (social attention modeling)
+              def model_other_attention(agent_id:, target:, awareness:, **)
+                Legion::Logging.debug "[attention_schema] model_other: agent=#{agent_id} target=#{target} awareness=#{awareness}"
+                schema_model.model_other_attention(agent_id: agent_id, target: target, awareness: awareness.to_f)
+                { success: true, agent_id: agent_id, target: target, awareness: awareness.to_f.clamp(0.0, 1.0).round(4) }
+              end
+
+              # Query what another agent is modeled as attending to
+              def query_other_attention(agent_id:, **)
+                model = schema_model.query_other_attention(agent_id: agent_id)
+                Legion::Logging.debug "[attention_schema] query_other: agent=#{agent_id} found=#{!model.nil?}"
+                { success: true, agent_id: agent_id, model: model }
+              end
+
+              # Run meta-attention check: detect drifting, hyper-focus, etc.
+              def meta_check(**)
+                result = schema_model.meta_check
+                Legion::Logging.debug "[attention_schema] meta_check: state=#{result[:state]} signals=#{result[:signals]}"
+                result.merge(success: true)
+              end
+
+              # Record whether the schema accurately predicted actual attention (accuracy feedback)
+              def update_meta_accuracy(was_correct:, **)
+                schema_model.update_meta_accuracy(was_correct: was_correct)
+                accuracy = schema_model.meta_accuracy
+                Legion::Logging.debug "[attention_schema] meta_accuracy: was_correct=#{was_correct} accuracy=#{accuracy.round(3)}"
+                { success: true, was_correct: was_correct, meta_accuracy: accuracy.round(4) }
+              end
+
+              # Tick decay: decay all schema items and prune faded ones
+              def decay_schema(**)
+                before = schema_model.schema_size
+                schema_model.decay_all
+                after = schema_model.schema_size
+                Legion::Logging.debug "[attention_schema] decay: before=#{before} after=#{after} pruned=#{before - after}"
+                {
+                  success: true,
+                  before:  before,
+                  after:   after,
+                  pruned:  before - after,
+                  state:   schema_model.attention_state
+                }
+              end
+
+              # Return full schema stats snapshot
+              def schema_stats(**)
+                Legion::Logging.debug "[attention_schema] stats: size=#{schema_model.schema_size}"
+                { success: true, stats: schema_model.to_h }
+              end
+
+              private
+
+              def schema_model
+                @schema_model ||= Helpers::AttentionSchemaModel.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/attention/schema/version'
+require 'legion/extensions/agentic/attention/schema/helpers/constants'
+require 'legion/extensions/agentic/attention/schema/helpers/schema_item'
+require 'legion/extensions/agentic/attention/schema/helpers/attention_schema_model'
+require 'legion/extensions/agentic/attention/schema/runners/attention_schema'
+require 'legion/extensions/agentic/attention/schema/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Schema
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module SensoryGating
+          class Client
+            include Runners::SensoryGating
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module SensoryGating
+          module Helpers
+            module Constants
+              MAX_STIMULI = 500
+              MAX_FILTERS = 100
+
+              DEFAULT_GATE_THRESHOLD = 0.5
+              GATE_ADJUSTMENT = 0.05
+              HABITUATION_RATE = 0.02
+              SENSITIZATION_RATE = 0.08
+
+              GATE_LABELS = {
+                (0.8..)     => :wide_open,
+                (0.6...0.8) => :permissive,
+                (0.4...0.6) => :selective,
+                (0.2...0.4) => :restrictive,
+                (..0.2)     => :blocked
+              }.freeze
+
+              STIMULUS_LABELS = {
+                (0.8..)     => :overwhelming,
+                (0.6...0.8) => :strong,
+                (0.4...0.6) => :moderate,
+                (0.2...0.4) => :mild,
+                (..0.2)     => :subliminal
+              }.freeze
+
+              MODALITY_TYPES = %i[
+                visual auditory textual semantic
+                emotional temporal social
+              ].freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/sensory_gating/helpers/gating_engine.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module SensoryGating
+          module Helpers
+            class GatingEngine
+              include Constants
+
+              def initialize
+                @filters = {}
+              end
+
+              def create_filter(modality:, gate_threshold: DEFAULT_GATE_THRESHOLD)
+                prune_if_needed
+                filter = SensoryFilter.new(modality: modality, gate_threshold: gate_threshold)
+                @filters[filter.id] = filter
+                filter
+              end
+
+              def process_stimulus(filter_id:, intensity:)
+                filter = @filters[filter_id]
+                return nil unless filter
+
+                outcome = filter.process(intensity: intensity)
+                { outcome: outcome, filter: filter }
+              end
+
+              def open_gate(filter_id:, amount: GATE_ADJUSTMENT)
+                filter = @filters[filter_id]
+                return nil unless filter
+
+                filter.open_gate!(amount: amount)
+              end
+
+              def close_gate(filter_id:, amount: GATE_ADJUSTMENT)
+                filter = @filters[filter_id]
+                return nil unless filter
+
+                filter.close_gate!(amount: amount)
+              end
+
+              def sensitize(filter_id:, amount: SENSITIZATION_RATE)
+                filter = @filters[filter_id]
+                return nil unless filter
+
+                filter.sensitize!(amount: amount)
+              end
+
+              def reset_habituation(filter_id:)
+                filter = @filters[filter_id]
+                return nil unless filter
+
+                filter.reset_habituation!
+              end
+
+              def filters_by_modality(modality:)
+                m = modality.to_sym
+                @filters.values.select { |f| f.modality == m }
+              end
+
+              def average_pass_rate
+                return 0.0 if @filters.empty?
+
+                rates = @filters.values.map(&:pass_rate)
+                (rates.sum / rates.size).round(10)
+              end
+
+              def most_restrictive(limit: 5)
+                @filters.values.sort_by(&:effective_threshold).reverse.first(limit)
+              end
+
+              def most_permissive(limit: 5)
+                @filters.values.sort_by(&:effective_threshold).first(limit)
+              end
+
+              def gating_report
+                {
+                  total_filters:     @filters.size,
+                  average_pass_rate: average_pass_rate,
+                  most_restrictive:  most_restrictive(limit: 3).map(&:to_h),
+                  most_permissive:   most_permissive(limit: 3).map(&:to_h)
+                }
+              end
+
+              def to_h
+                {
+                  total_filters:     @filters.size,
+                  average_pass_rate: average_pass_rate
+                }
+              end
+
+              private
+
+              def prune_if_needed
+                return if @filters.size < MAX_FILTERS
+
+                oldest = @filters.values.min_by(&:created_at)
+                @filters.delete(oldest.id) if oldest
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end