lex-attention-schema 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 26066d98d084abc8e93fce8bfe09e7ef1e5c9ce0f26178264c869700de98f425
+  data.tar.gz: 2e9e273d38e278b3798d426c778fe030e4819edd1197a8ecf88f7ced1f16d64e
+SHA512:
+  metadata.gz: 856518fd4426d3a60e16a1616c054225fa949e7ad839da093f07c321dd538e258cdbcf1c10143e84b57a808f0cc62619a1c9731ccaff71d1e5cc4733e374f258
+  data.tar.gz: 99e3002b9ee3cb8260cdec4d4c3a144c0949d43327a889144209ebf57cdcbb126b1b8ea383bb658f5f4cb40c8e859bda546329751a6498f81df6dec5e2bd21e1

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/attention_schema/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-attention-schema'
+  spec.version       = Legion::Extensions::AttentionSchema::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Attention Schema'
+  spec.description   = "Graziano's Attention Schema Theory for brain-modeled agentic AI — the agent " \
+                       'maintains a simplified internal model of its own attention process, enabling ' \
+                       'awareness attribution, social attention modeling, meta-attention monitoring, ' \
+                       'and natural-language attention reports.'
+  spec.homepage      = 'https://github.com/LegionIO/lex-attention-schema'
+  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-attention-schema'
+  spec.metadata['documentation_uri']     = 'https://github.com/LegionIO/lex-attention-schema'
+  spec.metadata['changelog_uri']         = 'https://github.com/LegionIO/lex-attention-schema'
+  spec.metadata['bug_tracker_uri']       = 'https://github.com/LegionIO/lex-attention-schema/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-attention-schema.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/attention_schema/helpers/constants'
+require 'legion/extensions/attention_schema/helpers/schema_item'
+require 'legion/extensions/attention_schema/helpers/attention_schema_model'
+require 'legion/extensions/attention_schema/runners/attention_schema'
+
+module Legion
+  module Extensions
+    module AttentionSchema
+      class Client
+        include Runners::AttentionSchema
+
+        def initialize(schema_model: nil, **)
+          @schema_model = schema_model || Helpers::AttentionSchemaModel.new
+        end
+
+        private
+
+        attr_reader :schema_model
+      end
+    end
+  end
+end

data/lib/legion/extensions/attention_schema/helpers/attention_schema_model.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module AttentionSchema
+      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(n = 3)
+            @schema_items.values
+                         .sort_by { |i| -i.awareness_level }
+                         .first(n)
+                         .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

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

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

data/lib/legion/extensions/attention_schema/helpers/schema_item.rb

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

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

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

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

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

data/lib/legion/extensions/attention_schema.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/attention_schema/version'
+require 'legion/extensions/attention_schema/helpers/constants'
+require 'legion/extensions/attention_schema/helpers/schema_item'
+require 'legion/extensions/attention_schema/helpers/attention_schema_model'
+require 'legion/extensions/attention_schema/runners/attention_schema'
+require 'legion/extensions/attention_schema/client'
+
+module Legion
+  module Extensions
+    module AttentionSchema
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::AttentionSchema::Client do
+  subject(:client) { described_class.new }
+
+  it 'includes Runners::AttentionSchema' do
+    expect(described_class.ancestors).to include(Legion::Extensions::AttentionSchema::Runners::AttentionSchema)
+  end
+
+  it 'supports full attention lifecycle' do
+    # Focus on items
+    client.focus_on(target: :code_review, domain: :work, reason: 'PR needs review', source: :external)
+    client.focus_on(target: :test_results, domain: :ci, reason: 'tests running', source: :internal)
+
+    # Query awareness
+    aware = client.am_i_aware_of(target: :code_review)
+    expect(aware[:aware]).to be true
+
+    # Report
+    report = client.report_awareness
+    expect(report[:items].size).to eq(2)
+
+    # Model another agent
+    client.model_other_attention(agent_id: :validator, target: :code_review, awareness: 0.9)
+    other = client.query_other_attention(agent_id: :validator)
+    expect(other[:model]).not_to be_nil
+
+    # Meta-check
+    meta = client.meta_check
+    expect(meta[:schema_size]).to eq(2)
+
+    # Meta-accuracy feedback
+    client.update_meta_accuracy(was_correct: true)
+
+    # Decay
+    client.decay_schema
+
+    # Stats
+    stats = client.schema_stats
+    expect(stats[:success]).to be true
+
+    # Defocus
+    client.defocus(target: :test_results)
+    final = client.am_i_aware_of(target: :test_results)
+    expect(final[:aware]).to be false
+  end
+end

data/spec/legion/extensions/attention_schema/helpers/attention_schema_model_spec.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::AttentionSchema::Helpers::AttentionSchemaModel do
+  subject(:model) { described_class.new }
+
+  let(:constants) { Legion::Extensions::AttentionSchema::Helpers::Constants }
+
+  describe '#focus_on' do
+    it 'adds an item to the schema' do
+      item = model.focus_on(target: :task, domain: :work, reason: 'priority', source: :external)
+      expect(item.target).to eq('task')
+      expect(model.schema_size).to eq(1)
+    end
+
+    it 'boosts existing items on re-focus' do
+      model.focus_on(target: :task, domain: :work, reason: 'init', source: :external)
+      first_level = model.schema_items['task'].awareness_level
+      model.focus_on(target: :task, domain: :work, reason: 'again', source: :external)
+      expect(model.schema_items['task'].awareness_level).to be > first_level
+      expect(model.schema_size).to eq(1)
+    end
+
+    it 'prunes to capacity when full' do
+      constants::MAX_SCHEMA_ITEMS.times do |i|
+        model.focus_on(target: "item_#{i}", domain: :d, reason: :r, source: :s)
+      end
+      expect(model.schema_size).to eq(constants::MAX_SCHEMA_ITEMS)
+      model.focus_on(target: :overflow, domain: :d, reason: :r, source: :s)
+      expect(model.schema_size).to eq(constants::MAX_SCHEMA_ITEMS)
+    end
+
+    it 'records focus event in history' do
+      model.focus_on(target: :task, domain: :work, reason: 'test', source: :external)
+      expect(model.attention_history.size).to eq(1)
+      expect(model.attention_history.first[:event]).to eq(:focused)
+    end
+
+    it 'records refocused event on re-focus' do
+      model.focus_on(target: :task, domain: :work, reason: 'init', source: :external)
+      model.focus_on(target: :task, domain: :work, reason: 'again', source: :external)
+      expect(model.attention_history.last[:event]).to eq(:refocused)
+    end
+  end
+
+  describe '#defocus' do
+    it 'removes an item from the schema' do
+      model.focus_on(target: :task, domain: :work, reason: 'r', source: :s)
+      removed = model.defocus(target: :task)
+      expect(removed).to be true
+      expect(model.schema_size).to eq(0)
+    end
+
+    it 'returns false for unknown target' do
+      expect(model.defocus(target: :missing)).to be false
+    end
+  end
+
+  describe '#am_i_aware_of' do
+    it 'returns aware: true for focused items' do
+      model.focus_on(target: :task, domain: :work, reason: 'r', source: :s)
+      result = model.am_i_aware_of(target: :task)
+      expect(result[:aware]).to be true
+      expect(result[:awareness_level]).to be > 0
+    end
+
+    it 'returns aware: false for unknown targets' do
+      result = model.am_i_aware_of(target: :unknown)
+      expect(result[:aware]).to be false
+      expect(result[:awareness_level]).to eq(0.0)
+      expect(result[:label]).to eq(:unconscious)
+    end
+  end
+
+  describe '#attention_state' do
+    it 'returns :distracted when empty' do
+      expect(model.attention_state).to eq(:distracted)
+    end
+
+    it 'returns :focused with a moderate item' do
+      model.focus_on(target: :task, domain: :work, reason: 'r', source: :s)
+      model.schema_items['task'].awareness_level = 0.7
+      expect(model.attention_state).to eq(:focused)
+    end
+
+    it 'returns :hyperfocused with high awareness' do
+      model.focus_on(target: :task, domain: :work, reason: 'r', source: :s)
+      model.schema_items['task'].awareness_level = 0.9
+      expect(model.attention_state).to eq(:hyperfocused)
+    end
+
+    it 'returns :drifting when average is low with few items' do
+      model.focus_on(target: :task, domain: :work, reason: 'r', source: :s)
+      model.schema_items['task'].awareness_level = 0.15
+      expect(model.attention_state).to eq(:drifting)
+    end
+
+    it 'returns :distracted with many low-awareness items' do
+      5.times { |i| model.focus_on(target: "t_#{i}", domain: :d, reason: :r, source: :s) }
+      model.schema_items.each_value { |v| v.awareness_level = 0.15 }
+      expect(model.attention_state).to eq(:distracted)
+    end
+  end
+
+  describe '#report_awareness' do
+    it 'reports no items when empty' do
+      report = model.report_awareness
+      expect(report[:state]).to eq(:distracted)
+      expect(report[:items]).to be_empty
+      expect(report[:report]).to include('No active')
+    end
+
+    it 'generates summary with items' do
+      model.focus_on(target: :task, domain: :work, reason: 'priority', source: :external)
+      report = model.report_awareness
+      expect(report[:report]).to include('task')
+      expect(report[:items].size).to eq(1)
+    end
+
+    it 'includes secondary items in report' do
+      model.focus_on(target: :a, domain: :work, reason: 'r', source: :s)
+      model.focus_on(target: :b, domain: :play, reason: 'r', source: :s)
+      report = model.report_awareness
+      expect(report[:items].size).to eq(2)
+      expect(report[:report]).to include('Also attending to')
+    end
+  end
+
+  describe '#model_other_attention' do
+    it 'records another agent attention model' do
+      model.model_other_attention(agent_id: :agent_a, target: :task, awareness: 0.8)
+      result = model.query_other_attention(agent_id: :agent_a)
+      expect(result[:target]).to eq('task')
+      expect(result[:awareness]).to eq(0.8)
+    end
+
+    it 'clamps awareness' do
+      model.model_other_attention(agent_id: :agent_a, target: :task, awareness: 1.5)
+      result = model.query_other_attention(agent_id: :agent_a)
+      expect(result[:awareness]).to eq(1.0)
+    end
+
+    it 'returns nil for unknown agent' do
+      expect(model.query_other_attention(agent_id: :unknown)).to be_nil
+    end
+
+    it 'prunes oldest social model when full' do
+      constants::MAX_SOCIAL_MODELS.times do |i|
+        model.model_other_attention(agent_id: "agent_#{i}", target: :t, awareness: 0.5)
+      end
+      model.model_other_attention(agent_id: :overflow, target: :t, awareness: 0.5)
+      expect(model.social_models.size).to eq(constants::MAX_SOCIAL_MODELS)
+    end
+  end
+
+  describe '#meta_check' do
+    it 'returns meta-attention state' do
+      result = model.meta_check
+      expect(result).to include(:state, :signals, :top_awareness, :avg_awareness, :schema_size, :meta_accuracy)
+    end
+
+    it 'includes :drifting signal when distracted' do
+      result = model.meta_check
+      expect(result[:signals]).to include(:drifting)
+    end
+
+    it 'includes :hyperfocus signal when hyperfocused' do
+      model.focus_on(target: :task, domain: :work, reason: 'r', source: :s)
+      model.schema_items['task'].awareness_level = 0.9
+      result = model.meta_check
+      expect(result[:signals]).to include(:hyperfocus)
+    end
+
+    it 'includes :normal when state is normal' do
+      model.focus_on(target: :task, domain: :work, reason: 'r', source: :s)
+      model.schema_items['task'].awareness_level = 0.5
+      result = model.meta_check
+      expect(result[:signals]).to include(:normal)
+    end
+  end
+
+  describe '#update_meta_accuracy' do
+    it 'increases accuracy when correct' do
+      before = model.meta_accuracy
+      model.update_meta_accuracy(was_correct: true)
+      expect(model.meta_accuracy).to be > before
+    end
+
+    it 'decreases accuracy when incorrect' do
+      before = model.meta_accuracy
+      model.update_meta_accuracy(was_correct: false)
+      expect(model.meta_accuracy).to be < before
+    end
+  end
+
+  describe '#decay_all' do
+    it 'decays all items' do
+      model.focus_on(target: :task, domain: :work, reason: 'r', source: :s)
+      before = model.schema_items['task'].awareness_level
+      model.decay_all
+      expect(model.schema_items['task']&.awareness_level || 0).to be < before
+    end
+
+    it 'prunes faded items' do
+      model.focus_on(target: :task, domain: :work, reason: 'r', source: :s)
+      model.schema_items['task'].awareness_level = constants::AWARENESS_FLOOR + 0.01
+      model.decay_all
+      expect(model.schema_size).to eq(0)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns stats hash' do
+      model.focus_on(target: :task, domain: :work, reason: 'r', source: :s)
+      h = model.to_h
+      expect(h).to include(:state, :state_label, :schema_size, :meta_accuracy, :top_awareness, :avg_awareness, :social_models, :items)
+      expect(h[:schema_size]).to eq(1)
+    end
+  end
+end

data/spec/legion/extensions/attention_schema/helpers/schema_item_spec.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::AttentionSchema::Helpers::SchemaItem do
+  subject(:item) do
+    described_class.new(target: 'task_queue', domain: :work, reason: 'priority', source: :external)
+  end
+
+  let(:constants) { Legion::Extensions::AttentionSchema::Helpers::Constants }
+
+  describe '#initialize' do
+    it 'sets attributes' do
+      expect(item.target).to eq('task_queue')
+      expect(item.domain).to eq(:work)
+      expect(item.reason).to eq('priority')
+      expect(item.source).to eq(:external)
+    end
+
+    it 'uses default awareness level' do
+      expect(item.awareness_level).to eq(constants::DEFAULT_AWARENESS)
+    end
+
+    it 'clamps awareness to 0..1' do
+      high = described_class.new(target: :x, domain: :d, reason: :r, source: :s, awareness_level: 1.5)
+      low  = described_class.new(target: :y, domain: :d, reason: :r, source: :s, awareness_level: -0.5)
+      expect(high.awareness_level).to eq(1.0)
+      expect(low.awareness_level).to eq(0.0)
+    end
+
+    it 'records created_at' do
+      expect(item.created_at).to be_a(Time)
+    end
+  end
+
+  describe '#duration' do
+    it 'returns elapsed time' do
+      expect(item.duration).to be >= 0.0
+    end
+  end
+
+  describe '#boost' do
+    it 'increases awareness by AWARENESS_BOOST' do
+      before = item.awareness_level
+      item.boost
+      expect(item.awareness_level).to eq(before + constants::AWARENESS_BOOST)
+    end
+
+    it 'caps at 1.0' do
+      item.awareness_level = 0.95
+      item.boost
+      expect(item.awareness_level).to eq(1.0)
+    end
+  end
+
+  describe '#decay' do
+    it 'decreases awareness by AWARENESS_DECAY' do
+      item.awareness_level = 0.5
+      item.decay
+      expect(item.awareness_level).to eq(0.5 - constants::AWARENESS_DECAY)
+    end
+
+    it 'does not drop below AWARENESS_FLOOR' do
+      item.awareness_level = constants::AWARENESS_FLOOR + 0.001
+      item.decay
+      expect(item.awareness_level).to eq(constants::AWARENESS_FLOOR)
+    end
+  end
+
+  describe '#faded?' do
+    it 'returns true at floor' do
+      item.awareness_level = constants::AWARENESS_FLOOR
+      expect(item.faded?).to be true
+    end
+
+    it 'returns false above floor' do
+      item.awareness_level = constants::AWARENESS_FLOOR + 0.01
+      expect(item.faded?).to be false
+    end
+  end
+
+  describe '#label' do
+    it 'returns :vivid for high awareness' do
+      item.awareness_level = 0.9
+      expect(item.label).to eq(:vivid)
+    end
+
+    it 'returns :unconscious for very low awareness' do
+      item.awareness_level = 0.1
+      expect(item.label).to eq(:unconscious)
+    end
+
+    it 'returns :clear for mid-high awareness' do
+      item.awareness_level = 0.7
+      expect(item.label).to eq(:clear)
+    end
+
+    it 'returns :dim for mid awareness' do
+      item.awareness_level = 0.5
+      expect(item.label).to eq(:dim)
+    end
+
+    it 'returns :peripheral for low awareness' do
+      item.awareness_level = 0.25
+      expect(item.label).to eq(:peripheral)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns hash with all fields' do
+      h = item.to_h
+      expect(h).to include(:target, :domain, :awareness_level, :label, :reason, :source, :duration, :created_at)
+      expect(h[:target]).to eq('task_queue')
+    end
+  end
+end

data/spec/legion/extensions/attention_schema/runners/attention_schema_spec.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::AttentionSchema::Runners::AttentionSchema do
+  let(:client) { Legion::Extensions::AttentionSchema::Client.new }
+
+  describe '#focus_on' do
+    it 'focuses on a target' do
+      result = client.focus_on(target: :task, domain: :work, reason: 'priority', source: :external)
+      expect(result[:success]).to be true
+      expect(result[:target]).to eq('task')
+      expect(result[:awareness_level]).to be > 0
+      expect(result[:label]).to be_a(Symbol)
+    end
+
+    it 'boosts on re-focus' do
+      first = client.focus_on(target: :task, domain: :work, reason: 'r', source: :s)
+      second = client.focus_on(target: :task, domain: :work, reason: 'r', source: :s)
+      expect(second[:awareness_level]).to be > first[:awareness_level]
+    end
+  end
+
+  describe '#defocus' do
+    it 'removes a target' do
+      client.focus_on(target: :task, domain: :work, reason: 'r', source: :s)
+      result = client.defocus(target: :task)
+      expect(result[:success]).to be true
+      expect(result[:removed]).to be true
+    end
+
+    it 'returns removed: false for unknown' do
+      result = client.defocus(target: :missing)
+      expect(result[:removed]).to be false
+    end
+  end
+
+  describe '#am_i_aware_of' do
+    it 'returns aware: true for focused target' do
+      client.focus_on(target: :task, domain: :work, reason: 'r', source: :s)
+      result = client.am_i_aware_of(target: :task)
+      expect(result[:success]).to be true
+      expect(result[:aware]).to be true
+    end
+
+    it 'returns aware: false for unknown target' do
+      result = client.am_i_aware_of(target: :unknown)
+      expect(result[:aware]).to be false
+    end
+  end
+
+  describe '#report_awareness' do
+    it 'returns awareness report' do
+      client.focus_on(target: :task, domain: :work, reason: 'priority', source: :external)
+      result = client.report_awareness
+      expect(result[:success]).to be true
+      expect(result[:report]).to be_a(String)
+      expect(result[:items]).to be_an(Array)
+    end
+  end
+
+  describe '#attention_state' do
+    it 'returns current state' do
+      result = client.attention_state
+      expect(result[:success]).to be true
+      expect(result[:state]).to be_a(Symbol)
+      expect(result[:label]).to be_a(String)
+    end
+  end
+
+  describe '#model_other_attention' do
+    it 'records other agent attention' do
+      result = client.model_other_attention(agent_id: :agent_a, target: :task, awareness: 0.8)
+      expect(result[:success]).to be true
+      expect(result[:agent_id]).to eq(:agent_a)
+    end
+  end
+
+  describe '#query_other_attention' do
+    it 'queries modeled attention' do
+      client.model_other_attention(agent_id: :agent_a, target: :task, awareness: 0.8)
+      result = client.query_other_attention(agent_id: :agent_a)
+      expect(result[:success]).to be true
+      expect(result[:model]).not_to be_nil
+    end
+
+    it 'returns nil model for unknown agent' do
+      result = client.query_other_attention(agent_id: :unknown)
+      expect(result[:model]).to be_nil
+    end
+  end
+
+  describe '#meta_check' do
+    it 'returns meta-attention signals' do
+      result = client.meta_check
+      expect(result[:success]).to be true
+      expect(result[:state]).to be_a(Symbol)
+      expect(result[:signals]).to be_an(Array)
+    end
+  end
+
+  describe '#update_meta_accuracy' do
+    it 'updates meta-accuracy with feedback' do
+      result = client.update_meta_accuracy(was_correct: true)
+      expect(result[:success]).to be true
+      expect(result[:meta_accuracy]).to be > 0.5
+    end
+  end
+
+  describe '#decay_schema' do
+    it 'decays and reports' do
+      client.focus_on(target: :task, domain: :work, reason: 'r', source: :s)
+      result = client.decay_schema
+      expect(result[:success]).to be true
+      expect(result[:before]).to eq(1)
+      expect(result).to have_key(:after)
+      expect(result).to have_key(:pruned)
+    end
+  end
+
+  describe '#schema_stats' do
+    it 'returns stats hash' do
+      result = client.schema_stats
+      expect(result[:success]).to be true
+      expect(result[:stats]).to include(:state, :schema_size, :meta_accuracy)
+    end
+
+    it 'reports zero schema_size when empty' do
+      result = client.schema_stats
+      expect(result[:stats][:schema_size]).to eq(0)
+    end
+
+    it 'includes items array in stats' do
+      client.focus_on(target: :task, domain: :work, reason: 'r', source: :s)
+      result = client.schema_stats
+      expect(result[:stats][:items]).to be_an(Array)
+      expect(result[:stats][:items].size).to eq(1)
+    end
+  end
+
+  describe '#focus_on schema_size tracking' do
+    it 'tracks schema_size correctly through multiple targets' do
+      client.focus_on(target: :a, domain: :d, reason: 'r', source: :s)
+      r2 = client.focus_on(target: :b, domain: :d, reason: 'r', source: :s)
+      r3 = client.focus_on(target: :c, domain: :d, reason: 'r', source: :s)
+      expect(r2[:schema_size]).to eq(2)
+      expect(r3[:schema_size]).to eq(3)
+    end
+  end
+
+  describe '#report_awareness empty state' do
+    it 'returns empty items when nothing focused' do
+      result = client.report_awareness
+      expect(result[:items]).to be_empty
+    end
+
+    it 'includes state_label string' do
+      result = client.report_awareness
+      expect(result[:state_label]).to be_a(String)
+    end
+  end
+
+  describe '#meta_check state labeling' do
+    it 'returns :distracted state with empty schema' do
+      result = client.meta_check
+      expect(result[:state]).to eq(:distracted)
+    end
+
+    it 'returns numeric top_awareness and avg_awareness' do
+      result = client.meta_check
+      expect(result[:top_awareness]).to be_a(Float)
+      expect(result[:avg_awareness]).to be_a(Float)
+    end
+  end
+
+  describe '#update_meta_accuracy boundary behavior' do
+    it 'correct=false reduces meta_accuracy below initial' do
+      result = client.update_meta_accuracy(was_correct: false)
+      expect(result[:meta_accuracy]).to be < 0.5
+    end
+
+    it 'returns the was_correct value echoed back' do
+      result = client.update_meta_accuracy(was_correct: false)
+      expect(result[:was_correct]).to be false
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+module Legion
+  module Logging
+    def self.debug(_msg); end
+    def self.info(_msg); end
+    def self.warn(_msg); end
+    def self.error(_msg); end
+  end
+end
+
+require 'legion/extensions/attention_schema'
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = '.rspec_status'
+  config.disable_monkey_patching!
+  config.expect_with(:rspec) { |c| c.syntax = :expect }
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: lex-attention-schema
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Esity
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: legion-gaia
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Graziano's Attention Schema Theory for brain-modeled agentic AI — the
+  agent maintains a simplified internal model of its own attention process, enabling
+  awareness attribution, social attention modeling, meta-attention monitoring, and
+  natural-language attention reports.
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-attention-schema.gemspec
+- lib/legion/extensions/attention_schema.rb
+- lib/legion/extensions/attention_schema/actors/decay.rb
+- lib/legion/extensions/attention_schema/client.rb
+- lib/legion/extensions/attention_schema/helpers/attention_schema_model.rb
+- lib/legion/extensions/attention_schema/helpers/constants.rb
+- lib/legion/extensions/attention_schema/helpers/schema_item.rb
+- lib/legion/extensions/attention_schema/runners/attention_schema.rb
+- lib/legion/extensions/attention_schema/version.rb
+- spec/legion/extensions/attention_schema/client_spec.rb
+- spec/legion/extensions/attention_schema/helpers/attention_schema_model_spec.rb
+- spec/legion/extensions/attention_schema/helpers/schema_item_spec.rb
+- spec/legion/extensions/attention_schema/runners/attention_schema_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-attention-schema
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-attention-schema
+  source_code_uri: https://github.com/LegionIO/lex-attention-schema
+  documentation_uri: https://github.com/LegionIO/lex-attention-schema
+  changelog_uri: https://github.com/LegionIO/lex-attention-schema
+  bug_tracker_uri: https://github.com/LegionIO/lex-attention-schema/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: LEX Attention Schema
+test_files: []