lex-agentic-attention 0.1.0

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

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module SensoryGating
+          module Helpers
+            class SensoryFilter
+              include Constants
+
+              attr_reader :id, :modality, :gate_threshold, :habituation_level,
+                          :stimuli_passed, :stimuli_blocked, :created_at
+
+              def initialize(modality:, gate_threshold: DEFAULT_GATE_THRESHOLD)
+                @id                = SecureRandom.uuid
+                @modality          = modality.to_sym
+                @gate_threshold    = gate_threshold.to_f.clamp(0.0, 1.0)
+                @habituation_level = 0.0
+                @stimuli_passed    = 0
+                @stimuli_blocked   = 0
+                @created_at        = Time.now.utc
+              end
+
+              def process(intensity:)
+                effective_threshold = (@gate_threshold + @habituation_level).clamp(0.0, 1.0).round(10)
+                if intensity >= effective_threshold
+                  @stimuli_passed += 1
+                  habituate!
+                  :passed
+                else
+                  @stimuli_blocked += 1
+                  :blocked
+                end
+              end
+
+              def open_gate!(amount: GATE_ADJUSTMENT)
+                @gate_threshold = (@gate_threshold - amount).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def close_gate!(amount: GATE_ADJUSTMENT)
+                @gate_threshold = (@gate_threshold + amount).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def sensitize!(amount: SENSITIZATION_RATE)
+                @habituation_level = (@habituation_level - amount).clamp(-0.5, 0.5).round(10)
+                self
+              end
+
+              def habituate!(amount: HABITUATION_RATE)
+                @habituation_level = (@habituation_level + amount).clamp(-0.5, 0.5).round(10)
+                self
+              end
+
+              def reset_habituation!
+                @habituation_level = 0.0
+                self
+              end
+
+              def effective_threshold
+                (@gate_threshold + @habituation_level).clamp(0.0, 1.0).round(10)
+              end
+
+              def pass_rate
+                total = @stimuli_passed + @stimuli_blocked
+                return 0.0 if total.zero?
+
+                (@stimuli_passed.to_f / total).round(4)
+              end
+
+              def gate_label
+                match = GATE_LABELS.find { |range, _| range.cover?(@gate_threshold) }
+                match ? match.last : :blocked
+              end
+
+              def to_h
+                {
+                  id:                  @id,
+                  modality:            @modality,
+                  gate_threshold:      @gate_threshold,
+                  effective_threshold: effective_threshold,
+                  habituation_level:   @habituation_level,
+                  gate_label:          gate_label,
+                  stimuli_passed:      @stimuli_passed,
+                  stimuli_blocked:     @stimuli_blocked,
+                  pass_rate:           pass_rate,
+                  created_at:          @created_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module SensoryGating
+          module Runners
+            module SensoryGating
+              include Helpers::Constants
+
+              include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+              def create_filter(modality:, engine: nil, gate_threshold: DEFAULT_GATE_THRESHOLD, **)
+                eng = engine || default_engine
+                filter = eng.create_filter(modality: modality, gate_threshold: gate_threshold)
+                { success: true, filter: filter.to_h }
+              end
+
+              def process_stimulus(filter_id:, intensity:, engine: nil, **)
+                eng = engine || default_engine
+                result = eng.process_stimulus(filter_id: filter_id, intensity: intensity)
+                return { success: false, error: 'filter not found' } unless result
+
+                { success: true, outcome: result[:outcome], filter: result[:filter].to_h }
+              end
+
+              def open_gate(filter_id:, engine: nil, amount: GATE_ADJUSTMENT, **)
+                eng = engine || default_engine
+                result = eng.open_gate(filter_id: filter_id, amount: amount)
+                return { success: false, error: 'filter not found' } unless result
+
+                { success: true, filter: result.to_h }
+              end
+
+              def close_gate(filter_id:, engine: nil, amount: GATE_ADJUSTMENT, **)
+                eng = engine || default_engine
+                result = eng.close_gate(filter_id: filter_id, amount: amount)
+                return { success: false, error: 'filter not found' } unless result
+
+                { success: true, filter: result.to_h }
+              end
+
+              def sensitize(filter_id:, engine: nil, amount: SENSITIZATION_RATE, **)
+                eng = engine || default_engine
+                result = eng.sensitize(filter_id: filter_id, amount: amount)
+                return { success: false, error: 'filter not found' } unless result
+
+                { success: true, filter: result.to_h }
+              end
+
+              def average_pass_rate(engine: nil, **)
+                eng = engine || default_engine
+                { success: true, pass_rate: eng.average_pass_rate }
+              end
+
+              def gating_report(engine: nil, **)
+                eng = engine || default_engine
+                { success: true, report: eng.gating_report }
+              end
+
+              private
+
+              def default_engine
+                @default_engine ||= Helpers::GatingEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'sensory_gating/version'
+require_relative 'sensory_gating/helpers/constants'
+require_relative 'sensory_gating/helpers/sensory_filter'
+require_relative 'sensory_gating/helpers/gating_engine'
+require_relative 'sensory_gating/runners/sensory_gating'
+require_relative 'sensory_gating/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module SensoryGating
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+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'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module SignalDetection
+          class Client
+            include Runners::SignalDetection
+
+            def initialize(**)
+              @detection_engine = Helpers::DetectionEngine.new
+            end
+
+            private
+
+            attr_reader :detection_engine
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module SignalDetection
+          module Helpers
+            module Constants
+              MAX_DETECTORS = 100
+              MAX_TRIALS    = 1000
+              MAX_HISTORY   = 300
+
+              DEFAULT_SENSITIVITY = 1.0
+              SENSITIVITY_FLOOR   = 0.0
+              SENSITIVITY_CEILING = 5.0
+
+              DEFAULT_CRITERION = 0.0
+              CRITERION_FLOOR   = -3.0
+              CRITERION_CEILING = 3.0
+
+              LEARNING_RATE = 0.05
+              DECAY_RATE    = 0.01
+
+              TRIAL_OUTCOMES = %i[hit miss false_alarm correct_rejection].freeze
+
+              SENSITIVITY_LABELS = {
+                (3.0..)     => :exceptional,
+                (2.0...3.0) => :excellent,
+                (1.0...2.0) => :good,
+                (0.5...1.0) => :moderate,
+                (..0.5)     => :poor
+              }.freeze
+
+              BIAS_LABELS = {
+                (1.0..)       => :very_conservative,
+                (0.3...1.0)   => :conservative,
+                (-0.3...0.3)  => :neutral,
+                (-1.0...-0.3) => :liberal,
+                (...-1.0)     => :very_liberal
+              }.freeze
+
+              module_function
+
+              def sensitivity_label(d_prime)
+                SENSITIVITY_LABELS.find { |range, _| range.cover?(d_prime) }&.last || :poor
+              end
+
+              def bias_label(criterion)
+                BIAS_LABELS.find { |range, _| range.cover?(criterion) }&.last || :neutral
+              end
+
+              def clamp_sensitivity(value)
+                value.clamp(SENSITIVITY_FLOOR, SENSITIVITY_CEILING)
+              end
+
+              def clamp_criterion(value)
+                value.clamp(CRITERION_FLOOR, CRITERION_CEILING)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module SignalDetection
+          module Helpers
+            class DetectionEngine
+              def initialize
+                @detectors = {}
+              end
+
+              def create_detector(domain:)
+                raise ArgumentError, "max detectors reached (#{Constants::MAX_DETECTORS})" if @detectors.size >= Constants::MAX_DETECTORS
+
+                detector = Detector.new(domain: domain)
+                @detectors[detector.id] = detector
+                detector
+              end
+
+              def record_trial(detector_id:, signal_present:, responded_present:)
+                detector = fetch!(detector_id)
+                outcome  = classify_outcome(signal_present: signal_present, responded_present: responded_present)
+                detector.record_trial(outcome: outcome)
+                { detector_id: detector_id, outcome: outcome, trial_count: detector.trial_count }
+              end
+
+              def compute_sensitivity(detector_id:)
+                detector = fetch!(detector_id)
+                {
+                  detector_id:       detector_id,
+                  d_prime:           detector.compute_dprime,
+                  criterion:         detector.compute_criterion,
+                  accuracy:          detector.accuracy,
+                  hit_rate:          detector.hit_rate,
+                  false_alarm_rate:  detector.false_alarm_rate,
+                  sensitivity_label: detector.sensitivity_label,
+                  bias_label:        detector.bias_label
+                }
+              end
+
+              def adjust_bias(detector_id:, amount:)
+                detector = fetch!(detector_id)
+                detector.adjust_criterion(amount: amount)
+                { detector_id: detector_id, criterion: detector.criterion, bias_label: detector.bias_label }
+              end
+
+              def best_detectors(limit: 5)
+                @detectors.values
+                          .sort_by { |d| -d.sensitivity }
+                          .first(limit)
+                          .map(&:to_h)
+              end
+
+              def by_domain(domain:)
+                @detectors.values.select { |d| d.domain == domain }.map(&:to_h)
+              end
+
+              def optimal_criterion(detector_id:, signal_probability: 0.5)
+                detector = fetch!(detector_id)
+                # Optimal criterion for equal cost: c* = 0.5 * ln((1-p)/p) in likelihood ratio terms
+                # In SDT criterion units: shift from neutral based on prior probability
+                prior_ratio = (1.0 - signal_probability) / signal_probability.clamp(0.001, 0.999)
+                optimal = 0.5 * Math.log(prior_ratio)
+                {
+                  detector_id:        detector_id,
+                  optimal_criterion:  Constants.clamp_criterion(optimal),
+                  current_criterion:  detector.criterion,
+                  signal_probability: signal_probability
+                }
+              end
+
+              def roc_point(detector_id:)
+                detector = fetch!(detector_id)
+                {
+                  detector_id:      detector_id,
+                  hit_rate:         detector.hit_rate,
+                  false_alarm_rate: detector.false_alarm_rate,
+                  d_prime:          detector.sensitivity
+                }
+              end
+
+              def decay_all
+                count = 0
+                @detectors.each_value do |detector|
+                  next if detector.trial_count.zero?
+
+                  detector.adjust_criterion(amount: Constants::DECAY_RATE * -detector.criterion.clamp(-1, 1))
+                  count += 1
+                end
+                count
+              end
+
+              def get(detector_id)
+                @detectors[detector_id]
+              end
+
+              def count
+                @detectors.size
+              end
+
+              def to_h
+                {
+                  detector_count: @detectors.size,
+                  detectors:      @detectors.transform_values(&:to_h)
+                }
+              end
+
+              private
+
+              def fetch!(detector_id)
+                @detectors.fetch(detector_id) { raise KeyError, "detector not found: #{detector_id}" }
+              end
+
+              def classify_outcome(signal_present:, responded_present:)
+                if signal_present && responded_present then :hit
+                elsif signal_present && !responded_present then :miss
+                elsif !signal_present && responded_present then :false_alarm
+                else :correct_rejection
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module SignalDetection
+          module Helpers
+            class Detector
+              include Constants
+
+              attr_reader :id, :domain, :hits, :misses, :false_alarms, :correct_rejections,
+                          :trial_count, :created_at, :last_trial_at, :sensitivity, :criterion
+
+              def initialize(domain:)
+                @id               = SecureRandom.uuid
+                @domain           = domain
+                @sensitivity      = Constants::DEFAULT_SENSITIVITY
+                @criterion        = Constants::DEFAULT_CRITERION
+                @hits             = 0
+                @misses           = 0
+                @false_alarms     = 0
+                @correct_rejections = 0
+                @trial_count      = 0
+                @created_at       = Time.now.utc
+                @last_trial_at    = nil
+              end
+
+              def record_trial(outcome:)
+                raise ArgumentError, "invalid outcome: #{outcome}" unless Constants::TRIAL_OUTCOMES.include?(outcome)
+
+                case outcome
+                when :hit               then @hits += 1
+                when :miss              then @misses += 1
+                when :false_alarm       then @false_alarms += 1
+                when :correct_rejection then @correct_rejections += 1
+                end
+
+                @trial_count   += 1
+                @last_trial_at  = Time.now.utc
+
+                update_sensitivity
+              end
+
+              def hit_rate
+                signal_total = @hits + @misses + 1
+                (@hits + 0.5) / signal_total.to_f
+              end
+
+              def false_alarm_rate
+                noise_total = @false_alarms + @correct_rejections + 1
+                (@false_alarms + 0.5) / noise_total.to_f
+              end
+
+              def compute_dprime
+                d = z_score(hit_rate) - z_score(false_alarm_rate)
+                Constants.clamp_sensitivity(d)
+              end
+
+              def compute_criterion
+                c = -0.5 * (z_score(hit_rate) + z_score(false_alarm_rate))
+                Constants.clamp_criterion(c)
+              end
+
+              def accuracy
+                return 0.0 if @trial_count.zero?
+
+                (@hits + @correct_rejections).to_f / @trial_count
+              end
+
+              def sensitivity_label
+                Constants.sensitivity_label(@sensitivity)
+              end
+
+              def bias_label
+                Constants.bias_label(@criterion)
+              end
+
+              def adjust_criterion(amount:)
+                @criterion = Constants.clamp_criterion(@criterion + amount)
+              end
+
+              def to_h
+                {
+                  id:                 @id,
+                  domain:             @domain,
+                  sensitivity:        @sensitivity,
+                  criterion:          @criterion,
+                  hits:               @hits,
+                  misses:             @misses,
+                  false_alarms:       @false_alarms,
+                  correct_rejections: @correct_rejections,
+                  trial_count:        @trial_count,
+                  hit_rate:           hit_rate,
+                  false_alarm_rate:   false_alarm_rate,
+                  accuracy:           accuracy,
+                  sensitivity_label:  sensitivity_label,
+                  bias_label:         bias_label,
+                  created_at:         @created_at,
+                  last_trial_at:      @last_trial_at
+                }
+              end
+
+              private
+
+              def update_sensitivity
+                return if @trial_count < 2
+
+                @sensitivity = compute_dprime
+                @criterion   = compute_criterion
+              end
+
+              def z_score(probability)
+                prob = probability.clamp(0.001, 0.999)
+                Math.sqrt(2.0) * erfinv((2.0 * prob) - 1.0)
+              end
+
+              def erfinv(val)
+                # Winitzki (2008) rational approximation for inverse error function
+                a = 0.147
+                ln_term = Math.log(1.0 - (val * val))
+                two_pi_a = (2.0 / (Math::PI * a))
+                half_ln = ln_term / 2.0
+
+                inner = two_pi_a + half_ln
+                Math.sqrt(Math.sqrt((inner * inner) - (ln_term / a)) - inner) * (val.negative? ? -1 : 1)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module SignalDetection
+          module Runners
+            module SignalDetection
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def create_detector(domain:, **)
+                detector = detection_engine.create_detector(domain: domain)
+                Legion::Logging.info "[signal_detection] created detector id=#{detector.id[0..7]} domain=#{domain}"
+                { created: true, detector_id: detector.id, domain: domain }
+              rescue ArgumentError => e
+                Legion::Logging.warn "[signal_detection] create_detector failed: #{e.message}"
+                { created: false, reason: e.message }
+              end
+
+              def record_detection_trial(detector_id:, signal_present:, responded_present:, **)
+                result = detection_engine.record_trial(
+                  detector_id:       detector_id,
+                  signal_present:    signal_present,
+                  responded_present: responded_present
+                )
+                Legion::Logging.debug "[signal_detection] trial: id=#{detector_id[0..7]} outcome=#{result[:outcome]} count=#{result[:trial_count]}"
+                result
+              rescue KeyError => e
+                Legion::Logging.warn "[signal_detection] record_trial failed: #{e.message}"
+                { recorded: false, reason: :not_found }
+              end
+
+              def compute_detector_sensitivity(detector_id:, **)
+                result = detection_engine.compute_sensitivity(detector_id: detector_id)
+                Legion::Logging.debug "[signal_detection] sensitivity: id=#{detector_id[0..7]} " \
+                                      "d_prime=#{result[:d_prime].round(3)} label=#{result[:sensitivity_label]}"
+                result
+              rescue KeyError => e
+                Legion::Logging.warn "[signal_detection] compute_sensitivity failed: #{e.message}"
+                { found: false, reason: :not_found }
+              end
+
+              def adjust_detector_bias(detector_id:, amount:, **)
+                result = detection_engine.adjust_bias(detector_id: detector_id, amount: amount)
+                Legion::Logging.debug "[signal_detection] bias adjusted: id=#{detector_id[0..7]} " \
+                                      "criterion=#{result[:criterion].round(3)} label=#{result[:bias_label]}"
+                result
+              rescue KeyError => e
+                Legion::Logging.warn "[signal_detection] adjust_bias failed: #{e.message}"
+                { adjusted: false, reason: :not_found }
+              end
+
+              def best_detectors(limit: 5, **)
+                detectors = detection_engine.best_detectors(limit: limit)
+                Legion::Logging.debug "[signal_detection] best detectors: count=#{detectors.size} limit=#{limit}"
+                { detectors: detectors, count: detectors.size }
+              end
+
+              def domain_detectors(domain:, **)
+                detectors = detection_engine.by_domain(domain: domain)
+                Legion::Logging.debug "[signal_detection] domain detectors: domain=#{domain} count=#{detectors.size}"
+                { detectors: detectors, count: detectors.size, domain: domain }
+              end
+
+              def optimal_detector_criterion(detector_id:, signal_probability: 0.5, **)
+                result = detection_engine.optimal_criterion(
+                  detector_id:        detector_id,
+                  signal_probability: signal_probability
+                )
+                Legion::Logging.debug "[signal_detection] optimal criterion: id=#{detector_id[0..7]} optimal=#{result[:optimal_criterion].round(3)}"
+                result
+              rescue KeyError => e
+                Legion::Logging.warn "[signal_detection] optimal_criterion failed: #{e.message}"
+                { found: false, reason: :not_found }
+              end
+
+              def detector_roc_point(detector_id:, **)
+                result = detection_engine.roc_point(detector_id: detector_id)
+                Legion::Logging.debug "[signal_detection] roc point: id=#{detector_id[0..7]} " \
+                                      "hr=#{result[:hit_rate].round(3)} far=#{result[:false_alarm_rate].round(3)}"
+                result
+              rescue KeyError => e
+                Legion::Logging.warn "[signal_detection] roc_point failed: #{e.message}"
+                { found: false, reason: :not_found }
+              end
+
+              def update_signal_detection(**)
+                decayed = detection_engine.decay_all
+                Legion::Logging.debug "[signal_detection] decay cycle: detectors_updated=#{decayed}"
+                { decayed: decayed }
+              end
+
+              def signal_detection_stats(**)
+                {
+                  total_detectors: detection_engine.count,
+                  top_detectors:   detection_engine.best_detectors(limit: 3)
+                }
+              end
+
+              private
+
+              def detection_engine
+                @detection_engine ||= Helpers::DetectionEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end