lex-attention 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5881f7686d12eba793b2952b24ad0c7c4fe67588d22640abc144e0744897d790
+  data.tar.gz: 924c52406ed8d9cf75da4ba6caf78d89dc56c057901c9977e1f63162cd899c91
+SHA512:
+  metadata.gz: 3d5eabbff72fad98045ddb012f26cea8291eed742277e329e83b74bc7412b625dc0651be523286c9d7f157a28ee2e893f22feca7623171930f485237be0b9462
+  data.tar.gz: d70ff18a5153263d6788343abb36ccee991bc8bfd588e371a60ab259aecdb79c1322485e45bc53a5e18986ac1593247d7e5b3a3fc2da2452833feea7209016f7

data/Gemfile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+gemspec
+
+group :test do
+  gem 'rake'
+  gem 'rspec'
+  gem 'rspec_junit_formatter'
+  gem 'rubocop', require: false
+  gem 'rubocop-rspec', require: false
+  gem 'simplecov'
+end
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Esity
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,56 @@
+# lex-attention
+
+Selective attention filter for the LegionIO brain-modeled cognitive architecture.
+
+## What It Does
+
+Models the thalamic reticular nucleus and prefrontal attention systems. Filters and prioritizes incoming signals before they enter the cognitive pipeline. Implements spotlight attention, goal-directed amplification, habituation, and capacity limits.
+
+```ruby
+client = Legion::Extensions::Attention::Client.new
+
+# Filter incoming signals
+result = client.filter_signals(
+  signals: [
+    { salience: 0.9, domain: :terraform, novelty: 0.8 },
+    { salience: 0.1, domain: :heartbeat, novelty: 0.0 },
+    { salience: 0.5, domain: :vault, novelty: 0.6 }
+  ],
+  active_wonders: [
+    { domain: :terraform, salience: 0.7 }
+  ]
+)
+# => { filtered: [...], spotlight: 1, peripheral: 1, background: 0, dropped: 1 }
+
+# Manual focus
+client.focus_on(domain: :security, reason: 'incident response')
+client.attention_status
+```
+
+## Attention Tiers
+
+| Tier | Score Range | Meaning |
+|------|------------|---------|
+| `:spotlight` | >= 0.7 | Full cognitive processing |
+| `:peripheral` | >= 0.4 | Reduced processing, may promote |
+| `:background` | >= 0.2 | Minimal processing, logged |
+| `:filtered` | < 0.2 | Dropped entirely |
+
+## Key Features
+
+- **Habituation**: Repeated signals in same domain become less salient
+- **Goal amplification**: Signals related to active curiosity wonders get boosted
+- **Capacity limit**: Max 7 spotlight items (Miller's law)
+- **Manual focus**: Direct attention to specific domains
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-attention.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/attention/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-attention'
+  spec.version       = Legion::Extensions::Attention::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Attention'
+  spec.description   = 'Selective attention filter for brain-modeled agentic AI'
+  spec.homepage      = 'https://github.com/LegionIO/lex-attention'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/LegionIO/lex-attention'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-attention'
+  spec.metadata['changelog_uri'] = 'https://github.com/LegionIO/lex-attention'
+  spec.metadata['bug_tracker_uri'] = 'https://github.com/LegionIO/lex-attention/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-attention.gemspec Gemfile LICENSE README.md]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/attention/helpers/constants'
+require 'legion/extensions/attention/helpers/focus'
+require 'legion/extensions/attention/helpers/focus_manager'
+require 'legion/extensions/attention/helpers/habituation'
+require 'legion/extensions/attention/runners/attention'
+
+module Legion
+  module Extensions
+    module Attention
+      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

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

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

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

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

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

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

data/lib/legion/extensions/attention/helpers/habituation.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Attention
+      module Helpers
+        class Habituation
+          def initialize
+            @domain_exposure = Hash.new(0.0)
+            @domain_last_seen = {}
+          end
+
+          def record(domain)
+            domain = domain.to_sym
+            @domain_exposure[domain] = [
+              @domain_exposure[domain] + Constants::HABITUATION_RATE,
+              Constants::HABITUATION_CEILING
+            ].min
+            @domain_last_seen[domain] = Time.now.utc
+          end
+
+          def level(domain)
+            domain = domain.to_sym
+            @domain_exposure[domain]
+          end
+
+          def apply_novelty_reset(domain, novelty: 0.5)
+            domain = domain.to_sym
+            return unless novelty > 0.5
+
+            reduction = (novelty - 0.5) * Constants::NOVELTY_RESET_FACTOR
+            @domain_exposure[domain] = [@domain_exposure[domain] - reduction, 0.0].max
+          end
+
+          def decay_all
+            @domain_exposure.each_key do |domain|
+              @domain_exposure[domain] = [
+                @domain_exposure[domain] - Constants::HABITUATION_DECAY,
+                0.0
+              ].max
+            end
+
+            @domain_exposure.delete_if { |_, v| v <= 0.0 }
+          end
+
+          def stats
+            @domain_exposure.transform_values { |v| v.round(3) }
+          end
+
+          def habituated_domains(threshold: 0.5)
+            @domain_exposure.select { |_, v| v >= threshold }.keys
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Attention
+      module Runners
+        module Attention
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def filter_signals(signals: [], active_wonders: [], **)
+            return { filtered: [], spotlight: 0, peripheral: 0, background: 0, dropped: 0 } if signals.empty?
+
+            unique = Helpers::Focus.deduplicate(signals)
+            scored = score_all(unique, active_wonders)
+            categorized = categorize(scored)
+
+            habituation_model.decay_all
+
+            Legion::Logging.debug "[attention] filtered #{signals.size}->#{categorized[:spotlight].size + categorized[:peripheral].size} " \
+                                  "(spotlight=#{categorized[:spotlight].size} peripheral=#{categorized[:peripheral].size} " \
+                                  "background=#{categorized[:background].size} dropped=#{categorized[:dropped]})"
+
+            {
+              filtered:   categorized[:spotlight] + categorized[:peripheral],
+              spotlight:  categorized[:spotlight].size,
+              peripheral: categorized[:peripheral].size,
+              background: categorized[:background].size,
+              dropped:    categorized[:dropped]
+            }
+          end
+
+          def attention_status(**)
+            {
+              manual_focus:       focus_manager.manual_focus,
+              habituated_domains: habituation_model.habituated_domains,
+              habituation_stats:  habituation_model.stats,
+              capacity:           Helpers::Constants::ATTENTIONAL_CAPACITY,
+              focus_count:        focus_manager.manual_focus.size
+            }
+          end
+
+          def focus_on(domain:, reason: nil, **)
+            result = focus_manager.focus_on(domain, reason: reason)
+            Legion::Logging.info "[attention] focus_on #{domain}: #{result}"
+            { status: result, domain: domain }
+          end
+
+          def release_focus(domain:, **)
+            result = focus_manager.release(domain)
+            Legion::Logging.info "[attention] release_focus #{domain}: #{result}"
+            { status: result, domain: domain }
+          end
+
+          def habituation_stats(**)
+            { domains: habituation_model.stats, habituated: habituation_model.habituated_domains }
+          end
+
+          private
+
+          def focus_manager
+            @focus_manager ||= Helpers::FocusManager.new
+          end
+
+          def habituation_model
+            @habituation_model ||= Helpers::Habituation.new
+          end
+
+          def score_all(signals, active_wonders)
+            signals.map do |signal|
+              domain = Helpers::Focus.extract_domain(signal)
+              habituation_model.record(domain)
+
+              novelty = Helpers::Focus.extract_novelty(signal)
+              habituation_model.apply_novelty_reset(domain, novelty: novelty)
+
+              goal_rel = focus_manager.goal_relevance(signal, active_wonders: active_wonders)
+              hab_level = habituation_model.level(domain)
+              score = Helpers::Focus.score_signal(signal, habituation_level: hab_level, goal_relevance: goal_rel)
+              tier = Helpers::Focus.attention_tier(score)
+
+              Helpers::Focus.tag_signal(signal, attention_score: score, attention_tier: tier)
+            end
+          end
+
+          def categorize(scored_signals)
+            result = { spotlight: [], peripheral: [], background: [], dropped: 0 }
+
+            scored_signals.each do |signal|
+              case signal[:attention_tier]
+              when :spotlight  then result[:spotlight] << signal
+              when :peripheral then result[:peripheral] << signal
+              when :background then result[:background] << signal
+              else result[:dropped] += 1
+              end
+            end
+
+            enforce_capacity(result)
+          end
+
+          def enforce_capacity(categorized)
+            capacity = Helpers::Constants::ATTENTIONAL_CAPACITY
+            spotlight = categorized[:spotlight].sort_by { |s| -(s[:attention_score] || 0) }
+
+            if spotlight.size > capacity
+              overflow = spotlight[capacity..]
+              categorized[:spotlight] = spotlight.first(capacity)
+              categorized[:peripheral].concat(overflow)
+            end
+
+            categorized
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/attention.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/attention/version'
+require 'legion/extensions/attention/helpers/constants'
+require 'legion/extensions/attention/helpers/focus'
+require 'legion/extensions/attention/helpers/focus_manager'
+require 'legion/extensions/attention/helpers/habituation'
+require 'legion/extensions/attention/runners/attention'
+require 'legion/extensions/attention/client'
+
+module Legion
+  module Extensions
+    module Attention
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Attention::Client do
+  subject(:client) { described_class.new }
+
+  it 'initializes with default focus manager and habituation model' do
+    status = client.attention_status
+    expect(status[:manual_focus]).to eq({})
+    expect(status[:capacity]).to eq(Legion::Extensions::Attention::Helpers::Constants::ATTENTIONAL_CAPACITY)
+  end
+
+  it 'includes the Attention runner' do
+    expect(client).to respond_to(:filter_signals)
+    expect(client).to respond_to(:attention_status)
+    expect(client).to respond_to(:focus_on)
+    expect(client).to respond_to(:release_focus)
+    expect(client).to respond_to(:habituation_stats)
+  end
+end

data/spec/legion/extensions/attention/helpers/focus_manager_spec.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Attention::Helpers::FocusManager do
+  subject(:manager) { described_class.new }
+
+  describe '#focus_on' do
+    it 'focuses on a domain' do
+      expect(manager.focus_on(:terraform)).to eq(:focused)
+      expect(manager.focused?(:terraform)).to be true
+    end
+
+    it 'converts string domains to symbols' do
+      manager.focus_on('vault')
+      expect(manager.focused?(:vault)).to be true
+    end
+
+    it 'returns :already_focused for duplicate focus' do
+      manager.focus_on(:terraform)
+      expect(manager.focus_on(:terraform)).to eq(:already_focused)
+    end
+
+    it 'returns :capacity_full when max is reached' do
+      Legion::Extensions::Attention::Helpers::Constants::MAX_MANUAL_FOCUS.times do |i|
+        manager.focus_on(:"domain_#{i}")
+      end
+      expect(manager.focus_on(:overflow)).to eq(:capacity_full)
+    end
+
+    it 'stores reason with the focus' do
+      manager.focus_on(:security, reason: 'incident response')
+      expect(manager.manual_focus[:security][:reason]).to eq('incident response')
+    end
+  end
+
+  describe '#release' do
+    it 'releases a focused domain' do
+      manager.focus_on(:terraform)
+      expect(manager.release(:terraform)).to eq(:released)
+      expect(manager.focused?(:terraform)).to be false
+    end
+
+    it 'returns :not_focused for unfocused domains' do
+      expect(manager.release(:nonexistent)).to eq(:not_focused)
+    end
+  end
+
+  describe '#focused?' do
+    it 'returns true for focused domains' do
+      manager.focus_on(:vault)
+      expect(manager.focused?(:vault)).to be true
+    end
+
+    it 'returns false for unfocused domains' do
+      expect(manager.focused?(:vault)).to be false
+    end
+  end
+
+  describe '#focus_boost' do
+    it 'returns FOCUS_BOOST for focused domains' do
+      manager.focus_on(:terraform)
+      expect(manager.focus_boost(:terraform)).to eq(
+        Legion::Extensions::Attention::Helpers::Constants::FOCUS_BOOST
+      )
+    end
+
+    it 'returns 0.0 for unfocused domains' do
+      expect(manager.focus_boost(:terraform)).to eq(0.0)
+    end
+  end
+
+  describe '#goal_relevance' do
+    it 'returns 0.0 with no focus or wonders' do
+      signal = { domain: :terraform, salience: 0.5 }
+      expect(manager.goal_relevance(signal)).to eq(0.0)
+    end
+
+    it 'returns boost for manually focused domain' do
+      manager.focus_on(:terraform)
+      signal = { domain: :terraform, salience: 0.5 }
+      expect(manager.goal_relevance(signal)).to be > 0.0
+    end
+
+    it 'returns relevance for domain matching an active wonder' do
+      signal = { domain: :terraform, salience: 0.5 }
+      wonders = [{ domain: :terraform, salience: 0.8 }]
+      relevance = manager.goal_relevance(signal, active_wonders: wonders)
+      expect(relevance).to be > 0.0
+    end
+
+    it 'returns 0.0 for non-matching wonder domains' do
+      signal = { domain: :terraform, salience: 0.5 }
+      wonders = [{ domain: :vault, salience: 0.8 }]
+      relevance = manager.goal_relevance(signal, active_wonders: wonders)
+      expect(relevance).to eq(0.0)
+    end
+
+    it 'caps at 1.0 even with focus and wonders combined' do
+      manager.focus_on(:terraform)
+      signal = { domain: :terraform, salience: 0.5 }
+      wonders = [{ domain: :terraform, salience: 1.0 }]
+      relevance = manager.goal_relevance(signal, active_wonders: wonders)
+      expect(relevance).to be <= 1.0
+    end
+  end
+end

data/spec/legion/extensions/attention/helpers/focus_spec.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Attention::Helpers::Focus do
+  let(:focus) { described_class }
+
+  describe '.score_signal' do
+    it 'returns a float between 0 and 1' do
+      score = focus.score_signal({ salience: 0.5, novelty: 0.5 })
+      expect(score).to be_between(0.0, 1.0)
+    end
+
+    it 'returns higher scores for high salience signals' do
+      high = focus.score_signal({ salience: 0.9, novelty: 0.5 })
+      low = focus.score_signal({ salience: 0.1, novelty: 0.5 })
+      expect(high).to be > low
+    end
+
+    it 'reduces score with high habituation' do
+      fresh = focus.score_signal({ salience: 0.5 }, habituation_level: 0.0)
+      habituated = focus.score_signal({ salience: 0.5 }, habituation_level: 0.9)
+      expect(fresh).to be > habituated
+    end
+
+    it 'increases score with goal relevance' do
+      no_goal = focus.score_signal({ salience: 0.5 }, goal_relevance: 0.0)
+      with_goal = focus.score_signal({ salience: 0.5 }, goal_relevance: 1.0)
+      expect(with_goal).to be > no_goal
+    end
+
+    it 'clamps result to 1.0 max' do
+      score = focus.score_signal({ salience: 1.0, novelty: 1.0 },
+                                 habituation_level: 0.0, goal_relevance: 1.0)
+      expect(score).to eq(1.0)
+    end
+  end
+
+  describe '.extract_salience' do
+    it 'returns salience from signal hash' do
+      expect(focus.extract_salience({ salience: 0.7 })).to eq(0.7)
+    end
+
+    it 'falls back to attention_score' do
+      expect(focus.extract_salience({ attention_score: 0.4 })).to eq(0.4)
+    end
+
+    it 'defaults to 0.0 for non-hash' do
+      expect(focus.extract_salience('not a hash')).to eq(0.0)
+    end
+
+    it 'defaults to 0.0 for missing key' do
+      expect(focus.extract_salience({})).to eq(0.0)
+    end
+  end
+
+  describe '.extract_novelty' do
+    it 'returns novelty from signal hash' do
+      expect(focus.extract_novelty({ novelty: 0.8 })).to eq(0.8)
+    end
+
+    it 'defaults to 0.5' do
+      expect(focus.extract_novelty({})).to eq(0.5)
+    end
+
+    it 'defaults to 0.5 for non-hash' do
+      expect(focus.extract_novelty(42)).to eq(0.5)
+    end
+  end
+
+  describe '.extract_domain' do
+    it 'returns domain from signal hash' do
+      expect(focus.extract_domain({ domain: :terraform })).to eq(:terraform)
+    end
+
+    it 'falls back to source_type' do
+      expect(focus.extract_domain({ source_type: :consul })).to eq(:consul)
+    end
+
+    it 'defaults to :general' do
+      expect(focus.extract_domain({})).to eq(:general)
+    end
+
+    it 'defaults to :general for non-hash' do
+      expect(focus.extract_domain(nil)).to eq(:general)
+    end
+  end
+
+  describe '.tag_signal' do
+    it 'merges attention metadata into the signal' do
+      signal = { salience: 0.8, domain: :terraform }
+      tagged = focus.tag_signal(signal, attention_score: 0.75, attention_tier: :spotlight)
+      expect(tagged[:attention_score]).to eq(0.75)
+      expect(tagged[:attention_tier]).to eq(:spotlight)
+      expect(tagged[:salience]).to eq(0.8)
+    end
+
+    it 'returns non-hash signals unchanged' do
+      result = focus.tag_signal('string', attention_score: 0.5, attention_tier: :peripheral)
+      expect(result).to eq('string')
+    end
+  end
+
+  describe '.attention_tier' do
+    it 'returns :spotlight for >= 0.7' do
+      expect(focus.attention_tier(0.7)).to eq(:spotlight)
+      expect(focus.attention_tier(0.95)).to eq(:spotlight)
+    end
+
+    it 'returns :peripheral for >= 0.4' do
+      expect(focus.attention_tier(0.4)).to eq(:peripheral)
+      expect(focus.attention_tier(0.69)).to eq(:peripheral)
+    end
+
+    it 'returns :background for >= BACKGROUND_THRESHOLD' do
+      expect(focus.attention_tier(0.2)).to eq(:background)
+      expect(focus.attention_tier(0.39)).to eq(:background)
+    end
+
+    it 'returns :filtered for below BACKGROUND_THRESHOLD' do
+      expect(focus.attention_tier(0.19)).to eq(:filtered)
+      expect(focus.attention_tier(0.0)).to eq(:filtered)
+    end
+  end
+
+  describe '.deduplicate' do
+    it 'removes duplicate signals by identity' do
+      signals = [
+        { domain: :terraform, source_type: :event, value: 'deploy' },
+        { domain: :terraform, source_type: :event, value: 'deploy' },
+        { domain: :vault, source_type: :event, value: 'rotate' }
+      ]
+      result = focus.deduplicate(signals)
+      expect(result.size).to eq(2)
+    end
+
+    it 'preserves unique signals' do
+      signals = [
+        { domain: :a, value: 1 },
+        { domain: :b, value: 2 },
+        { domain: :c, value: 3 }
+      ]
+      expect(focus.deduplicate(signals).size).to eq(3)
+    end
+
+    it 'returns empty array for empty input' do
+      expect(focus.deduplicate([])).to eq([])
+    end
+  end
+end

data/spec/legion/extensions/attention/helpers/habituation_spec.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Attention::Helpers::Habituation do
+  subject(:model) { described_class.new }
+
+  describe '#record' do
+    it 'increases habituation level for a domain' do
+      model.record(:terraform)
+      expect(model.level(:terraform)).to be > 0.0
+    end
+
+    it 'accumulates with repeated recordings' do
+      3.times { model.record(:terraform) }
+      expect(model.level(:terraform)).to be > model.level(:vault).to_f
+    end
+
+    it 'caps at HABITUATION_CEILING' do
+      ceiling = Legion::Extensions::Attention::Helpers::Constants::HABITUATION_CEILING
+      20.times { model.record(:terraform) }
+      expect(model.level(:terraform)).to be <= ceiling
+    end
+
+    it 'converts string domains to symbols' do
+      model.record('terraform')
+      expect(model.level(:terraform)).to be > 0.0
+    end
+  end
+
+  describe '#level' do
+    it 'returns 0.0 for unknown domains' do
+      expect(model.level(:unknown)).to eq(0.0)
+    end
+  end
+
+  describe '#apply_novelty_reset' do
+    it 'does nothing when novelty <= 0.5' do
+      model.record(:terraform)
+      level_before = model.level(:terraform)
+      model.apply_novelty_reset(:terraform, novelty: 0.3)
+      expect(model.level(:terraform)).to eq(level_before)
+    end
+
+    it 'reduces habituation when novelty > 0.5' do
+      5.times { model.record(:terraform) }
+      level_before = model.level(:terraform)
+      model.apply_novelty_reset(:terraform, novelty: 0.9)
+      expect(model.level(:terraform)).to be < level_before
+    end
+
+    it 'never reduces below 0.0' do
+      model.record(:terraform)
+      model.apply_novelty_reset(:terraform, novelty: 1.0)
+      expect(model.level(:terraform)).to be >= 0.0
+    end
+  end
+
+  describe '#decay_all' do
+    it 'reduces habituation for all recorded domains' do
+      3.times { model.record(:terraform) }
+      3.times { model.record(:vault) }
+      tf_before = model.level(:terraform)
+      v_before = model.level(:vault)
+
+      model.decay_all
+      expect(model.level(:terraform)).to be < tf_before
+      expect(model.level(:vault)).to be < v_before
+    end
+
+    it 'removes domains that decay to zero' do
+      model.record(:terraform)
+      model.apply_novelty_reset(:terraform, novelty: 1.0)
+      model.decay_all
+      expect(model.stats).not_to have_key(:terraform)
+    end
+  end
+
+  describe '#stats' do
+    it 'returns rounded exposure levels' do
+      model.record(:terraform)
+      stats = model.stats
+      expect(stats[:terraform]).to be_a(Float)
+      expect(stats[:terraform].to_s.split('.').last.length).to be <= 3
+    end
+  end
+
+  describe '#habituated_domains' do
+    it 'returns domains above threshold' do
+      10.times { model.record(:terraform) }
+      expect(model.habituated_domains).to include(:terraform)
+    end
+
+    it 'excludes domains below threshold' do
+      model.record(:terraform)
+      expect(model.habituated_domains(threshold: 0.5)).not_to include(:terraform)
+    end
+  end
+end

data/spec/legion/extensions/attention/runners/attention_spec.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Attention::Runners::Attention do
+  let(:client) { Legion::Extensions::Attention::Client.new }
+
+  describe '#filter_signals' do
+    it 'returns empty result for empty input' do
+      result = client.filter_signals(signals: [])
+      expect(result[:filtered]).to eq([])
+      expect(result[:spotlight]).to eq(0)
+      expect(result[:peripheral]).to eq(0)
+      expect(result[:background]).to eq(0)
+      expect(result[:dropped]).to eq(0)
+    end
+
+    it 'categorizes high-salience signals as spotlight with goal boost' do
+      signals = [{ salience: 0.9, domain: :terraform, novelty: 0.8 }]
+      wonders = [{ domain: :terraform, salience: 0.9 }]
+      result = client.filter_signals(signals: signals, active_wonders: wonders)
+      expect(result[:spotlight]).to be >= 1
+    end
+
+    it 'categorizes high-salience signals into filtered output' do
+      signals = [{ salience: 0.9, domain: :terraform, novelty: 0.8 }]
+      result = client.filter_signals(signals: signals)
+      expect(result[:filtered].size).to be >= 1
+    end
+
+    it 'drops low-salience signals' do
+      signals = [{ salience: 0.01, domain: :heartbeat, novelty: 0.0 }]
+      result = client.filter_signals(signals: signals)
+      expect(result[:dropped]).to be >= 0
+      expect(result[:filtered].size).to be <= 1
+    end
+
+    it 'boosts signals matching active wonders' do
+      signals = [{ salience: 0.3, domain: :terraform, novelty: 0.3 }]
+      wonders = [{ domain: :terraform, salience: 0.9 }]
+
+      without = client.filter_signals(signals: signals)
+      # New client to avoid habituation carryover
+      fresh = Legion::Extensions::Attention::Client.new
+      with_wonders = fresh.filter_signals(signals: signals, active_wonders: wonders)
+
+      # With wonder boost, the signal should score higher
+      with_total = with_wonders[:spotlight] + with_wonders[:peripheral]
+      without_total = without[:spotlight] + without[:peripheral]
+      expect(with_total).to be >= without_total
+    end
+
+    it 'deduplicates identical signals' do
+      signals = [
+        { salience: 0.8, domain: :terraform, source_type: :event, value: 'deploy' },
+        { salience: 0.8, domain: :terraform, source_type: :event, value: 'deploy' }
+      ]
+      result = client.filter_signals(signals: signals)
+      expect(result[:spotlight] + result[:peripheral] + result[:background]).to be <= 1
+    end
+
+    it 'enforces attentional capacity' do
+      signals = 10.times.map { |i| { salience: 0.9, domain: :"domain_#{i}", novelty: 0.9 } }
+      result = client.filter_signals(signals: signals)
+      expect(result[:spotlight]).to be <= Legion::Extensions::Attention::Helpers::Constants::ATTENTIONAL_CAPACITY
+    end
+
+    it 'habituates repeated domain signals' do
+      first_client = Legion::Extensions::Attention::Client.new
+      signals = [{ salience: 0.6, domain: :terraform, novelty: 0.3 }]
+
+      first_result = first_client.filter_signals(signals: signals)
+      # Record same domain multiple times to build habituation
+      10.times { first_client.filter_signals(signals: signals) }
+      later_result = first_client.filter_signals(signals: signals)
+
+      first_scores = first_result[:filtered].map { |s| s[:attention_score] || 0 }
+      later_scores = later_result[:filtered].map { |s| s[:attention_score] || 0 }
+
+      # Later scores should be lower due to habituation (if signal still passes)
+      expect(later_scores.max).to be <= first_scores.max if first_scores.any? && later_scores.any?
+    end
+  end
+
+  describe '#attention_status' do
+    it 'returns status hash' do
+      status = client.attention_status
+      expect(status[:manual_focus]).to eq({})
+      expect(status[:habituated_domains]).to eq([])
+      expect(status[:capacity]).to eq(Legion::Extensions::Attention::Helpers::Constants::ATTENTIONAL_CAPACITY)
+      expect(status[:focus_count]).to eq(0)
+    end
+  end
+
+  describe '#focus_on' do
+    it 'focuses on a domain' do
+      result = client.focus_on(domain: :terraform, reason: 'deployment')
+      expect(result[:status]).to eq(:focused)
+      expect(result[:domain]).to eq(:terraform)
+    end
+
+    it 'updates attention status' do
+      client.focus_on(domain: :security, reason: 'incident')
+      status = client.attention_status
+      expect(status[:focus_count]).to eq(1)
+    end
+  end
+
+  describe '#release_focus' do
+    it 'releases a focused domain' do
+      client.focus_on(domain: :terraform)
+      result = client.release_focus(domain: :terraform)
+      expect(result[:status]).to eq(:released)
+    end
+
+    it 'returns :not_focused for unknown domain' do
+      result = client.release_focus(domain: :unknown)
+      expect(result[:status]).to eq(:not_focused)
+    end
+  end
+
+  describe '#habituation_stats' do
+    it 'returns stats hash' do
+      stats = client.habituation_stats
+      expect(stats[:domains]).to be_a(Hash)
+      expect(stats[:habituated]).to be_an(Array)
+    end
+
+    it 'reflects domain exposure after filtering' do
+      signals = [{ salience: 0.8, domain: :terraform, novelty: 0.3 }]
+      5.times { client.filter_signals(signals: signals) }
+      stats = client.habituation_stats
+      expect(stats[:domains]).to have_key(:terraform)
+    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'
+
+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
+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: Selective attention filter for brain-modeled agentic AI
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE
+- README.md
+- lex-attention.gemspec
+- lib/legion/extensions/attention.rb
+- lib/legion/extensions/attention/client.rb
+- lib/legion/extensions/attention/helpers/constants.rb
+- lib/legion/extensions/attention/helpers/focus.rb
+- lib/legion/extensions/attention/helpers/focus_manager.rb
+- lib/legion/extensions/attention/helpers/habituation.rb
+- lib/legion/extensions/attention/runners/attention.rb
+- lib/legion/extensions/attention/version.rb
+- spec/legion/extensions/attention/client_spec.rb
+- spec/legion/extensions/attention/helpers/focus_manager_spec.rb
+- spec/legion/extensions/attention/helpers/focus_spec.rb
+- spec/legion/extensions/attention/helpers/habituation_spec.rb
+- spec/legion/extensions/attention/runners/attention_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-attention
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-attention
+  source_code_uri: https://github.com/LegionIO/lex-attention
+  documentation_uri: https://github.com/LegionIO/lex-attention
+  changelog_uri: https://github.com/LegionIO/lex-attention
+  bug_tracker_uri: https://github.com/LegionIO/lex-attention/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
+test_files: []