lex-agentic-attention 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 11316e7a48a460b4bfb317d22f335cf149e138d329df2f1ffbb91c6439915463
+  data.tar.gz: 94a927cd12dde2ec8212462a6c504839096cb5a074945c8f89b65ebde28bf06e
+SHA512:
+  metadata.gz: 177772a3cf51ff7e3d799445014bf601ac106070a26a5130a12110164133cc82baa38651108eae9ea9c0cdbaec0ba2984e38ff197af6e5c3f6bba669e54ee833
+  data.tar.gz: 80ec4fb94b4ff8129ca765ff4e90a22429cd65155f00849a7845e8e8f23159e23ed3286039db62620f9584517637e74caee81e392a42005f4c22213a6ccd1627

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-18
+
+### Added
+- Initial release as domain consolidation gem
+- Consolidated source extensions into unified domain gem under `Legion::Extensions::Agentic::<Domain>`
+- All sub-modules loaded from single entry point
+- Full spec suite with zero failures
+- RuboCop compliance across all files

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Iverson
+
+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,13 @@
+# lex-agentic-attention
+
+LEX agentic attention domain: focus, salience, cognitive control
+
+## Sub-modules
+
+*(populated as extensions are consolidated)*
+
+## Installation
+
+```ruby
+gem 'lex-agentic-attention'
+```

data/lex-agentic-attention.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/agentic/attention/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-agentic-attention'
+  spec.version       = Legion::Extensions::Agentic::Attention::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Agentic Attention'
+  spec.description   = 'LEX agentic attention domain: focus, salience, cognitive control'
+  spec.homepage      = 'https://github.com/LegionIO/lex-agentic-attention'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']      = spec.homepage
+  spec.metadata['source_code_uri']   = spec.homepage
+  spec.metadata['changelog_uri']     = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir.glob('{lib,spec}/**/*.rb') + %w[lex-agentic-attention.gemspec Gemfile LICENSE README.md CHANGELOG.md]
+  end
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'rspec', '~> 3.13'
+  spec.add_development_dependency 'rubocop', '~> 1.60'
+  spec.add_development_dependency 'rubocop-rspec', '~> 2.26'
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/attention/arousal/helpers/constants'
+require 'legion/extensions/agentic/attention/arousal/helpers/arousal_model'
+require 'legion/extensions/agentic/attention/arousal/runners/arousal'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Arousal
+          class Client
+            include Runners::Arousal
+
+            def initialize(**)
+              @arousal_model = Helpers::ArousalModel.new
+            end
+
+            private
+
+            attr_reader :arousal_model
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/arousal/helpers/arousal_model.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Arousal
+          module Helpers
+            class ArousalModel
+              include Constants
+
+              attr_reader :arousal, :arousal_history, :performance_last
+
+              def initialize
+                @arousal = DEFAULT_AROUSAL
+                @arousal_history = []
+                @performance_last = 0.0
+              end
+
+              def stimulate(amount:, source: :unknown)
+                boost = amount || BOOST_FACTOR
+                raw = @arousal + boost.to_f.clamp(0.0, 1.0)
+                update_arousal(raw, source: source)
+              end
+
+              def calm(amount:)
+                reduction = amount || CALM_FACTOR
+                raw = @arousal - reduction.to_f.clamp(0.0, 1.0)
+                update_arousal(raw, source: :calm)
+              end
+
+              def decay
+                delta = (@arousal - DEFAULT_AROUSAL) * DECAY_RATE
+                raw = @arousal - delta
+                update_arousal(raw, source: :decay)
+              end
+
+              def performance(task_complexity: :moderate)
+                optimal = optimal_for(task_complexity)
+                diff = @arousal - optimal
+                @performance_last = Math.exp(-PERFORMANCE_SENSITIVITY * (diff**2))
+                @performance_last
+              end
+
+              def arousal_label
+                AROUSAL_LABELS.each do |range, label|
+                  return label if range.cover?(@arousal)
+                end
+                :dormant
+              end
+
+              def optimal_for(complexity)
+                TASK_COMPLEXITIES.fetch(complexity, OPTIMAL_AROUSAL_DEFAULT)
+              end
+
+              def to_h
+                {
+                  arousal:          @arousal,
+                  label:            arousal_label,
+                  performance_last: @performance_last,
+                  history_size:     @arousal_history.size
+                }
+              end
+
+              private
+
+              def update_arousal(raw, source: :unknown)
+                clamped = raw.clamp(AROUSAL_FLOOR, AROUSAL_CEILING)
+                @arousal = (AROUSAL_ALPHA * clamped) + ((1.0 - AROUSAL_ALPHA) * @arousal)
+                record_history(source)
+                @arousal
+              end
+
+              def record_history(source)
+                @arousal_history << { arousal: @arousal, source: source, at: Time.now.utc }
+                @arousal_history.shift while @arousal_history.size > MAX_AROUSAL_HISTORY
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Arousal
+          module Helpers
+            module Constants
+              DEFAULT_AROUSAL          = 0.3
+              AROUSAL_ALPHA            = 0.15
+              DECAY_RATE               = 0.05
+              OPTIMAL_AROUSAL_SIMPLE   = 0.7
+              OPTIMAL_AROUSAL_COMPLEX  = 0.4
+              OPTIMAL_AROUSAL_DEFAULT  = 0.5
+              PERFORMANCE_SENSITIVITY  = 4.0
+              BOOST_FACTOR             = 0.2
+              CALM_FACTOR              = 0.15
+              AROUSAL_FLOOR            = 0.0
+              AROUSAL_CEILING          = 1.0
+              MAX_AROUSAL_HISTORY      = 200
+
+              TASK_COMPLEXITIES = {
+                trivial:  0.8,
+                simple:   0.7,
+                moderate: 0.5,
+                complex:  0.4,
+                extreme:  0.3
+              }.freeze
+
+              AROUSAL_LABELS = {
+                (0.8..)     => :panic,
+                (0.6...0.8) => :high,
+                (0.4...0.6) => :optimal,
+                (0.2...0.4) => :low,
+                (..0.2)     => :dormant
+              }.freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Arousal
+          module Runners
+            module Arousal
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def stimulate(amount: nil, source: :unknown, **)
+                model = arousal_model
+                amount ||= Helpers::Constants::BOOST_FACTOR
+                new_level = model.stimulate(amount: amount, source: source)
+                Legion::Logging.debug "[arousal] stimulate: source=#{source} amount=#{amount.round(2)} level=#{new_level.round(3)}"
+                {
+                  success: true,
+                  arousal: new_level,
+                  label:   model.arousal_label,
+                  source:  source
+                }
+              end
+
+              def calm(amount: nil, **)
+                model = arousal_model
+                amount ||= Helpers::Constants::CALM_FACTOR
+                new_level = model.calm(amount: amount)
+                Legion::Logging.debug "[arousal] calm: amount=#{amount.round(2)} level=#{new_level.round(3)}"
+                {
+                  success: true,
+                  arousal: new_level,
+                  label:   model.arousal_label
+                }
+              end
+
+              def update_arousal(**)
+                model = arousal_model
+                model.decay
+                perf = model.performance
+                Legion::Logging.debug "[arousal] update: level=#{model.arousal.round(3)} label=#{model.arousal_label} perf=#{perf.round(3)}"
+                {
+                  success:     true,
+                  arousal:     model.arousal,
+                  label:       model.arousal_label,
+                  performance: perf
+                }
+              end
+
+              def check_performance(task_complexity: :moderate, **)
+                model = arousal_model
+                perf = model.performance(task_complexity: task_complexity)
+                optimal = model.optimal_for(task_complexity)
+                msg = "[arousal] performance: complexity=#{task_complexity} " \
+                      "arousal=#{model.arousal.round(3)} optimal=#{optimal} perf=#{perf.round(3)}"
+                Legion::Logging.debug msg
+                {
+                  success:         true,
+                  performance:     perf,
+                  arousal:         model.arousal,
+                  optimal_arousal: optimal,
+                  task_complexity: task_complexity
+                }
+              end
+
+              def arousal_status(**)
+                model = arousal_model
+                perf = model.performance
+                Legion::Logging.debug "[arousal] status: level=#{model.arousal.round(3)} label=#{model.arousal_label}"
+                {
+                  success:      true,
+                  arousal:      model.arousal,
+                  label:        model.arousal_label,
+                  performance:  perf,
+                  history_size: model.arousal_history.size
+                }
+              end
+
+              def arousal_guidance(task_complexity: :moderate, **)
+                model = arousal_model
+                current = model.arousal
+                optimal = model.optimal_for(task_complexity)
+                perf = model.performance(task_complexity: task_complexity)
+                guidance = compute_guidance(current, optimal)
+                Legion::Logging.debug "[arousal] guidance: complexity=#{task_complexity} current=#{current.round(3)} optimal=#{optimal} guidance=#{guidance}"
+                {
+                  success:         true,
+                  guidance:        guidance,
+                  arousal:         current,
+                  optimal_arousal: optimal,
+                  performance:     perf,
+                  task_complexity: task_complexity
+                }
+              end
+
+              private
+
+              def arousal_model
+                @arousal_model ||= Helpers::ArousalModel.new
+              end
+
+              def compute_guidance(current, optimal)
+                gap = current - optimal
+                if gap > 0.15
+                  :throttle
+                elsif gap < -0.15
+                  :boost
+                else
+                  :maintain
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/attention/arousal/version'
+require 'legion/extensions/agentic/attention/arousal/helpers/constants'
+require 'legion/extensions/agentic/attention/arousal/helpers/arousal_model'
+require 'legion/extensions/agentic/attention/arousal/runners/arousal'
+require 'legion/extensions/agentic/attention/arousal/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Arousal
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Blindspot
+          class Client
+            include Runners::CognitiveBlindspot
+
+            def engine
+              @engine ||= Helpers::BlindspotEngine.new
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Blindspot
+          module Helpers
+            class Blindspot
+              include Constants
+
+              attr_reader :id, :domain, :discovered_by, :severity, :description,
+                          :status, :created_at, :acknowledged_at, :mitigated_at, :resolved_at
+
+              def initialize(domain:, discovered_by:, description:, severity: DEFAULT_SEVERITY)
+                @id             = SecureRandom.uuid
+                @domain         = domain.to_sym
+                @discovered_by  = discovered_by.to_sym
+                @description    = description.to_s
+                @severity       = severity.to_f.clamp(0.0, 1.0)
+                @status         = :active
+                @created_at     = Time.now.utc
+                @acknowledged_at = nil
+                @mitigated_at   = nil
+                @resolved_at    = nil
+              end
+
+              def severity_label
+                Constants.label_for(SEVERITY_LABELS, @severity) || :negligible
+              end
+
+              def active?
+                @status == :active
+              end
+
+              def acknowledged?
+                @status == :acknowledged || @status == :mitigated || @status == :resolved
+              end
+
+              def resolved?
+                @status == :resolved
+              end
+
+              def acknowledge!
+                return self if @status != :active
+
+                @status          = :acknowledged
+                @acknowledged_at = Time.now.utc
+                self
+              end
+
+              def mitigate!(boost: SEVERITY_BOOST)
+                acknowledge! if @status == :active
+                @status        = :mitigated
+                @mitigated_at  = Time.now.utc
+                @severity      = (@severity - boost).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def resolve!
+                acknowledge! if @status == :active
+                @status      = :resolved
+                @resolved_at = Time.now.utc
+                self
+              end
+
+              def boost_severity!(amount: SEVERITY_BOOST)
+                @severity = (@severity + amount).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def to_h
+                {
+                  id:              @id,
+                  domain:          @domain,
+                  discovered_by:   @discovered_by,
+                  description:     @description,
+                  severity:        @severity,
+                  severity_label:  severity_label,
+                  status:          @status,
+                  active:          active?,
+                  acknowledged:    acknowledged?,
+                  resolved:        resolved?,
+                  created_at:      @created_at,
+                  acknowledged_at: @acknowledged_at,
+                  mitigated_at:    @mitigated_at,
+                  resolved_at:     @resolved_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end