lex-agentic-attention 0.1.0

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

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

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/attention/signal_detection/version'
+require 'legion/extensions/agentic/attention/signal_detection/helpers/constants'
+require 'legion/extensions/agentic/attention/signal_detection/helpers/detector'
+require 'legion/extensions/agentic/attention/signal_detection/helpers/detection_engine'
+require 'legion/extensions/agentic/attention/signal_detection/runners/signal_detection'
+require 'legion/extensions/agentic/attention/signal_detection/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module SignalDetection
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/attention/spotlight/helpers/constants'
+require 'legion/extensions/agentic/attention/spotlight/helpers/attention_target'
+require 'legion/extensions/agentic/attention/spotlight/helpers/spotlight'
+require 'legion/extensions/agentic/attention/spotlight/helpers/spotlight_engine'
+require 'legion/extensions/agentic/attention/spotlight/runners/attention_spotlight'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Spotlight
+          class Client
+            include Runners::AttentionSpotlight
+
+            def initialize(engine: nil, **)
+              @engine = engine || Helpers::SpotlightEngine.new
+            end
+
+            private
+
+            attr_reader :engine
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/spotlight/helpers/attention_target.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Spotlight
+          module Helpers
+            class AttentionTarget
+              include Constants
+
+              attr_reader   :id, :label, :domain, :created_at
+              attr_accessor :salience, :relevance, :in_spotlight, :in_periphery,
+                            :capture_count, :last_attended_at
+
+              def initialize(label:, domain:, salience: 0.5, relevance: 0.5)
+                @id             = SecureRandom.uuid
+                @label          = label
+                @domain         = domain
+                @salience       = salience.clamp(0.0, 1.0)
+                @relevance      = relevance.clamp(0.0, 1.0)
+                @in_spotlight   = false
+                @in_periphery   = false
+                @capture_count  = 0
+                @created_at     = Time.now.utc
+                @last_attended_at = nil
+              end
+
+              def compelling?
+                @salience >= Constants::CAPTURE_THRESHOLD
+              end
+
+              def salient?
+                @salience >= Constants::PERIPHERAL_DETECTION_THRESHOLD
+              end
+
+              def to_h
+                {
+                  id:               @id,
+                  label:            @label,
+                  domain:           @domain,
+                  salience:         @salience.round(10),
+                  relevance:        @relevance.round(10),
+                  in_spotlight:     @in_spotlight,
+                  in_periphery:     @in_periphery,
+                  capture_count:    @capture_count,
+                  compelling:       compelling?,
+                  salient:          salient?,
+                  created_at:       @created_at,
+                  last_attended_at: @last_attended_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Spotlight
+          module Helpers
+            module Constants
+              MAX_TARGETS                    = 200
+              MAX_PERIPHERAL                 = 100
+              DEFAULT_INTENSITY              = 0.5
+              DEFAULT_BREADTH                = 0.5
+              ZOOM_STEP                      = 0.1
+              INTENSITY_GAIN                 = 0.15
+              INTENSITY_LOSS                 = 0.1
+              PERIPHERAL_DETECTION_THRESHOLD = 0.3
+              CAPTURE_THRESHOLD              = 0.8
+
+              ZOOM_LEVELS = %i[laser narrow moderate wide diffuse].freeze
+              MODE_LABELS = %i[focused scanning captured idle].freeze
+
+              ZOOM_RANGES = [
+                { range: (0.0..0.2),  level: :laser    },
+                { range: (0.21..0.4), level: :narrow   },
+                { range: (0.41..0.6), level: :moderate },
+                { range: (0.61..0.8), level: :wide     },
+                { range: (0.81..1.0), level: :diffuse  }
+              ].freeze
+
+              INTENSITY_LABELS = [
+                { range: (0.8..1.0),  label: :blazing  },
+                { range: (0.6..0.79), label: :bright   },
+                { range: (0.4..0.59), label: :moderate },
+                { range: (0.2..0.39), label: :dim      },
+                { range: (0.0..0.19), label: :dark     }
+              ].freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Spotlight
+          module Helpers
+            class Spotlight
+              include Constants
+
+              attr_reader :center_target_id, :intensity, :breadth, :mode
+
+              def initialize
+                @center_target_id = nil
+                @intensity        = Constants::DEFAULT_INTENSITY
+                @breadth          = Constants::DEFAULT_BREADTH
+                @mode             = :idle
+              end
+
+              def focus_on!(target_id)
+                @center_target_id = target_id
+                @mode             = :focused
+                @intensity        = (@intensity + Constants::INTENSITY_GAIN).clamp(0.0, 1.0).round(10)
+              end
+
+              def broaden!
+                @breadth    = (@breadth + Constants::ZOOM_STEP).clamp(0.0, 1.0).round(10)
+                @intensity  = (@intensity - Constants::INTENSITY_LOSS).clamp(0.0, 1.0).round(10)
+                @mode       = :scanning if @mode == :focused
+              end
+
+              def narrow!
+                @breadth    = (@breadth - Constants::ZOOM_STEP).clamp(0.0, 1.0).round(10)
+                @intensity  = (@intensity + Constants::INTENSITY_GAIN).clamp(0.0, 1.0).round(10)
+                @mode       = :focused if @center_target_id && @mode == :scanning
+              end
+
+              def capture!(target_id)
+                @center_target_id = target_id
+                @mode             = :captured
+                @intensity        = 1.0
+              end
+
+              def release!
+                @center_target_id = nil
+                @mode             = :idle
+                @intensity        = Constants::DEFAULT_INTENSITY
+                @breadth          = Constants::DEFAULT_BREADTH
+              end
+
+              def zoom_level
+                entry = Constants::ZOOM_RANGES.find { |z| z[:range].cover?(@breadth) }
+                entry&.fetch(:level, :moderate) || :moderate
+              end
+
+              def intensity_label
+                entry = Constants::INTENSITY_LABELS.find { |il| il[:range].cover?(@intensity) }
+                entry&.fetch(:label, :moderate) || :moderate
+              end
+
+              def to_h
+                {
+                  center_target_id: @center_target_id,
+                  intensity:        @intensity.round(10),
+                  breadth:          @breadth.round(10),
+                  mode:             @mode,
+                  zoom_level:       zoom_level,
+                  intensity_label:  intensity_label
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/spotlight/helpers/spotlight_engine.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Spotlight
+          module Helpers
+            class SpotlightEngine
+              include Constants
+
+              attr_reader :targets, :spotlight, :peripheral
+
+              def initialize
+                @targets    = {}
+                @spotlight  = Spotlight.new
+                @peripheral = []
+              end
+
+              def register_target(label:, domain:, salience: 0.5, relevance: 0.5)
+                return { registered: false, reason: :max_targets_reached, limit: Constants::MAX_TARGETS } if @targets.size >= Constants::MAX_TARGETS
+
+                target = AttentionTarget.new(label: label, domain: domain,
+                                             salience: salience, relevance: relevance)
+                @targets[target.id] = target
+                { registered: true, target_id: target.id, label: label, domain: domain }
+              end
+
+              def focus(target_id:)
+                target = @targets[target_id]
+                return { focused: false, reason: :not_found } unless target
+
+                clear_spotlight_flags
+                @spotlight.focus_on!(target_id)
+                target.in_spotlight = true
+                target.last_attended_at = Time.now.utc
+                { focused: true, target_id: target_id, mode: @spotlight.mode, intensity: @spotlight.intensity }
+              end
+
+              def broaden
+                @spotlight.broaden!
+                mark_spotlight_coverage
+                { broadened: true, breadth: @spotlight.breadth, zoom_level: @spotlight.zoom_level }
+              end
+
+              def narrow
+                @spotlight.narrow!
+                mark_spotlight_coverage
+                { narrowed: true, breadth: @spotlight.breadth, zoom_level: @spotlight.zoom_level }
+              end
+
+              def scan
+                @spotlight.instance_variable_set(:@mode, :scanning)
+                mark_spotlight_coverage
+                sorted = @targets.values.sort_by { |t| -t.salience }
+                sorted.each { |t| t.last_attended_at = Time.now.utc }
+                { scanning: true, targets_swept: sorted.size }
+              end
+
+              def check_peripheral
+                outside = @targets.values.reject(&:in_spotlight)
+                detected = outside.select(&:salient?).first(Constants::MAX_PERIPHERAL)
+                @peripheral = detected.map(&:id)
+                detected.each { |t| t.in_periphery = true }
+                (outside - detected).each { |t| t.in_periphery = false }
+                { detected: @peripheral.size, peripheral_ids: @peripheral }
+              end
+
+              def check_capture
+                candidate = @targets.values
+                                    .reject(&:in_spotlight)
+                                    .select(&:compelling?)
+                                    .max_by(&:salience)
+                return { captured: false } unless candidate
+
+                clear_spotlight_flags
+                @spotlight.capture!(candidate.id)
+                candidate.in_spotlight = true
+                candidate.capture_count += 1
+                candidate.last_attended_at = Time.now.utc
+                mark_spotlight_coverage
+                { captured: true, target_id: candidate.id, salience: candidate.salience }
+              end
+
+              def release_focus
+                clear_spotlight_flags
+                @spotlight.release!
+                { released: true }
+              end
+
+              def targets_in_spotlight
+                @targets.values.select(&:in_spotlight)
+              end
+
+              def peripheral_alerts
+                @peripheral.filter_map { |id| @targets[id] }
+              end
+
+              def most_salient(limit: 5)
+                @targets.values.sort_by { |t| -t.salience }.first(limit)
+              end
+
+              def spotlight_report
+                {
+                  spotlight:        @spotlight.to_h,
+                  in_spotlight:     targets_in_spotlight.map(&:to_h),
+                  in_periphery:     peripheral_alerts.map(&:to_h),
+                  most_salient:     most_salient.map(&:to_h),
+                  total_targets:    @targets.size,
+                  peripheral_count: @peripheral.size
+                }
+              end
+
+              def to_h
+                {
+                  spotlight:         @spotlight.to_h,
+                  target_count:      @targets.size,
+                  peripheral_count:  @peripheral.size,
+                  spotlight_targets: targets_in_spotlight.map(&:to_h)
+                }
+              end
+
+              private
+
+              def clear_spotlight_flags
+                @targets.each_value { |t| t.in_spotlight = false }
+              end
+
+              def covered_target_ids
+                center_id = @spotlight.center_target_id
+                return [] unless center_id
+                return [center_id] if @spotlight.breadth <= 0.2
+
+                count = breadth_to_count(@spotlight.breadth)
+                sorted_by_salience = @targets.values.sort_by { |t| -t.salience }
+                candidates = sorted_by_salience.first(count)
+                result = [center_id]
+                candidates.each { |t| result << t.id unless result.include?(t.id) }
+                result.first(count)
+              end
+
+              def breadth_to_count(breadth)
+                return 1  if breadth <= 0.2
+                return 3  if breadth <= 0.4
+                return 7  if breadth <= 0.6
+                return 15 if breadth <= 0.8
+
+                [30, @targets.size].min
+              end
+
+              def mark_spotlight_coverage
+                covered = covered_target_ids.to_set
+                @targets.each_value do |t|
+                  t.in_spotlight = covered.include?(t.id)
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/spotlight/runners/attention_spotlight.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Spotlight
+          module Runners
+            module AttentionSpotlight
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def register_target(label:, domain:, salience: 0.5, relevance: 0.5, **)
+                Legion::Logging.debug "[attention_spotlight] register target label=#{label} domain=#{domain}"
+                result = engine.register_target(label: label, domain: domain,
+                                                salience: salience, relevance: relevance)
+                { success: result[:registered], **result }
+              rescue StandardError => e
+                Legion::Logging.error "[attention_spotlight] register_target error: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def focus_spotlight(target_id:, **)
+                Legion::Logging.debug "[attention_spotlight] focus target_id=#{target_id[0..7]}"
+                result = engine.focus(target_id: target_id)
+                { success: result[:focused], **result }
+              rescue StandardError => e
+                Legion::Logging.error "[attention_spotlight] focus_spotlight error: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def broaden_spotlight(**)
+                Legion::Logging.debug '[attention_spotlight] broadening spotlight'
+                result = engine.broaden
+                { success: true, **result }
+              rescue StandardError => e
+                Legion::Logging.error "[attention_spotlight] broaden_spotlight error: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def narrow_spotlight(**)
+                Legion::Logging.debug '[attention_spotlight] narrowing spotlight'
+                result = engine.narrow
+                { success: true, **result }
+              rescue StandardError => e
+                Legion::Logging.error "[attention_spotlight] narrow_spotlight error: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def scan_targets(**)
+                Legion::Logging.debug '[attention_spotlight] initiating scan'
+                result = engine.scan
+                { success: true, **result }
+              rescue StandardError => e
+                Legion::Logging.error "[attention_spotlight] scan_targets error: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def check_peripheral(**)
+                Legion::Logging.debug '[attention_spotlight] checking periphery'
+                result = engine.check_peripheral
+                { success: true, **result }
+              rescue StandardError => e
+                Legion::Logging.error "[attention_spotlight] check_peripheral error: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def check_capture(**)
+                Legion::Logging.debug '[attention_spotlight] checking for attention capture'
+                result = engine.check_capture
+                { success: true, **result }
+              rescue StandardError => e
+                Legion::Logging.error "[attention_spotlight] check_capture error: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def release_focus(**)
+                Legion::Logging.debug '[attention_spotlight] releasing focus'
+                result = engine.release_focus
+                { success: true, **result }
+              rescue StandardError => e
+                Legion::Logging.error "[attention_spotlight] release_focus error: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def spotlight_report(**)
+                Legion::Logging.debug '[attention_spotlight] generating report'
+                report = engine.spotlight_report
+                { success: true, **report }
+              rescue StandardError => e
+                Legion::Logging.error "[attention_spotlight] spotlight_report error: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def most_salient(limit: 5, **)
+                Legion::Logging.debug "[attention_spotlight] most_salient limit=#{limit}"
+                targets = engine.most_salient(limit: limit)
+                { success: true, targets: targets.map(&:to_h), count: targets.size }
+              rescue StandardError => e
+                Legion::Logging.error "[attention_spotlight] most_salient error: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def spotlight_state(**)
+                { success: true, **engine.to_h }
+              rescue StandardError => e
+                Legion::Logging.error "[attention_spotlight] spotlight_state error: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              private
+
+              def engine
+                @engine ||= Helpers::SpotlightEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/attention/spotlight/version'
+require 'legion/extensions/agentic/attention/spotlight/helpers/constants'
+require 'legion/extensions/agentic/attention/spotlight/helpers/attention_target'
+require 'legion/extensions/agentic/attention/spotlight/helpers/spotlight'
+require 'legion/extensions/agentic/attention/spotlight/helpers/spotlight_engine'
+require 'legion/extensions/agentic/attention/spotlight/runners/attention_spotlight'
+require 'legion/extensions/agentic/attention/spotlight/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Spotlight
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Subliminal
+          class Client
+            include Runners::Subliminal
+
+            def initialize
+              @default_engine = Helpers::SubliminalEngine.new
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Subliminal
+          module Helpers
+            module Constants
+              MAX_TRACES = 500
+              MAX_INFLUENCES = 1000
+
+              # Threshold boundaries
+              CONSCIOUS_THRESHOLD = 0.4
+              SUBLIMINAL_CEILING = 0.39
+              SUBLIMINAL_FLOOR = 0.02
+              EXTINCTION_THRESHOLD = 0.01
+
+              # Dynamics
+              DEFAULT_ACTIVATION = 0.2
+              ACTIVATION_BOOST = 0.08
+              ACTIVATION_DECAY = 0.015
+              INFLUENCE_STRENGTH = 0.05
+              ACCUMULATION_RATE = 0.03
+
+              # Influence caps
+              MAX_INFLUENCE_PER_DOMAIN = 0.3
+              MAX_TOTAL_INFLUENCE = 0.5
+
+              TRACE_TYPES = %i[
+                perceptual emotional associative procedural
+                semantic motivational aversive appetitive
+              ].freeze
+
+              INFLUENCE_TARGETS = %i[
+                attention emotion decision memory
+                preference avoidance approach valence
+              ].freeze
+
+              ACTIVATION_LABELS = {
+                (0.3...0.4)  => :near_threshold,
+                (0.2...0.3)  => :moderate,
+                (0.1...0.2)  => :faint,
+                (0.02...0.1) => :trace,
+                (..0.02)     => :extinct
+              }.freeze
+
+              INFLUENCE_LABELS = {
+                (0.2..)       => :strong,
+                (0.1...0.2)   => :moderate,
+                (0.05...0.1)  => :subtle,
+                (0.01...0.05) => :minimal,
+                (..0.01)      => :none
+              }.freeze
+
+              SATURATION_LABELS = {
+                (0.8..)     => :saturated,
+                (0.6...0.8) => :heavy,
+                (0.4...0.6) => :moderate,
+                (0.2...0.4) => :light,
+                (..0.2)     => :clear
+              }.freeze
+
+              def self.label_for(labels, value)
+                labels.each { |range, label| return label if range.cover?(value) }
+                :unknown
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end