lex-agentic-attention 0.1.0

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

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Blindspot
+          module Helpers
+            class BlindspotEngine
+              include Constants
+
+              attr_reader :awareness_score
+
+              def initialize
+                @blindspots      = {}
+                @boundaries      = {}
+                @awareness_score = 1.0
+              end
+
+              def register_blindspot(domain:, discovered_by:, description:, severity: DEFAULT_SEVERITY)
+                prune_blindspots_if_needed
+                blindspot = Blindspot.new(domain: domain, discovered_by: discovered_by,
+                                          description: description, severity: severity)
+                @blindspots[blindspot.id] = blindspot
+                recalculate_awareness
+                blindspot
+              end
+
+              def acknowledge_blindspot(blindspot_id:)
+                blindspot = @blindspots.fetch(blindspot_id, nil)
+                return { found: false, blindspot_id: blindspot_id } unless blindspot
+
+                blindspot.acknowledge!
+                recalculate_awareness
+                { found: true, blindspot_id: blindspot_id, status: blindspot.status,
+                  awareness_score: @awareness_score.round(10) }
+              end
+
+              def mitigate_blindspot(blindspot_id:, boost: SEVERITY_BOOST)
+                blindspot = @blindspots.fetch(blindspot_id, nil)
+                return { found: false, blindspot_id: blindspot_id } unless blindspot
+
+                blindspot.mitigate!(boost: boost)
+                recalculate_awareness
+                { found: true, blindspot_id: blindspot_id, status: blindspot.status,
+                  severity: blindspot.severity, awareness_score: @awareness_score.round(10) }
+              end
+
+              def resolve_blindspot(blindspot_id:)
+                blindspot = @blindspots.fetch(blindspot_id, nil)
+                return { found: false, blindspot_id: blindspot_id } unless blindspot
+
+                blindspot.resolve!
+                recalculate_awareness
+                { found: true, blindspot_id: blindspot_id, status: blindspot.status,
+                  awareness_score: @awareness_score.round(10) }
+              end
+
+              def set_boundary(domain:, confidence: 0.5, coverage_estimate: 0.5)
+                prune_boundaries_if_needed
+                existing = boundary_for_domain(domain)
+                return update_boundary!(existing, confidence, coverage_estimate) if existing
+
+                boundary = KnowledgeBoundary.new(domain: domain, confidence: confidence,
+                                                 coverage_estimate: coverage_estimate)
+                @boundaries[boundary.id] = boundary
+                boundary
+              end
+
+              def detect_boundary_gap(domain:, error_occurred: false)
+                boundary = boundary_for_domain(domain)
+                return { gap_detected: false, domain: domain, reason: :no_boundary } unless boundary
+
+                { gap_detected: boundary.gap_detected?(error_occurred: error_occurred),
+                  domain: domain, confidence: boundary.confidence,
+                  coverage: boundary.coverage_estimate }
+              end
+
+              def blindspots_by_domain(domain)
+                d = domain.to_sym
+                @blindspots.values.select { |b| b.domain == d }
+              end
+
+              def active_blindspots       = @blindspots.values.select(&:active?)
+              def acknowledged_blindspots = @blindspots.values.select { |b| b.status == :acknowledged }
+              def resolved_blindspots     = @blindspots.values.select(&:resolved?)
+
+              def most_severe(limit: 5)
+                @blindspots.values.sort_by { |b| -b.severity }.first(limit)
+              end
+
+              def mitigation_strategies(domain: nil)
+                spots = domain ? blindspots_by_domain(domain) : @blindspots.values
+                spots.select(&:active?).map do |b|
+                  { blindspot_id: b.id, domain: b.domain, severity: b.severity, strategy: strategy_for(b) }
+                end
+              end
+
+              def coverage_report  = @boundaries.values.map(&:to_h)
+              def awareness_label  = Constants.label_for(AWARENESS_LABELS, @awareness_score) || :unaware
+              def awareness_gap    = (1.0 - @awareness_score).clamp(0.0, 1.0).round(10)
+
+              def johari_report
+                { total_blindspots:   @blindspots.size,
+                  active:             active_blindspots.size,
+                  acknowledged:       acknowledged_blindspots.size,
+                  resolved:           resolved_blindspots.size,
+                  awareness_score:    @awareness_score.round(10),
+                  awareness_label:    awareness_label,
+                  awareness_gap:      awareness_gap,
+                  boundaries_tracked: @boundaries.size,
+                  most_severe:        most_severe(limit: 3).map(&:to_h) }
+              end
+
+              def to_h
+                { total_blindspots: @blindspots.size,
+                  active:           active_blindspots.size,
+                  acknowledged:     acknowledged_blindspots.size,
+                  resolved:         resolved_blindspots.size,
+                  awareness_score:  @awareness_score.round(10),
+                  awareness_label:  awareness_label }
+              end
+
+              private
+
+              def update_boundary!(boundary, confidence, coverage_estimate)
+                boundary.update_confidence!(confidence)
+                boundary.update_coverage!(coverage_estimate)
+                boundary
+              end
+
+              def boundary_for_domain(domain)
+                d = domain.to_sym
+                @boundaries.values.find { |b| b.domain == d }
+              end
+
+              def recalculate_awareness
+                total = @blindspots.size.to_f
+                return @awareness_score = 1.0 if total.zero?
+
+                not_active = @blindspots.values.count { |b| !b.active? }.to_f
+                @awareness_score = (not_active / total).clamp(0.0, 1.0).round(10)
+              end
+
+              def strategy_for(blindspot)
+                case blindspot.severity
+                when (0.8..) then :immediate_external_audit
+                when (0.6...0.8) then :cross_domain_check
+                when (0.4...0.6) then :peer_feedback
+                else :self_reflection
+                end
+              end
+
+              def prune_blindspots_if_needed
+                return if @blindspots.size < MAX_BLINDSPOTS
+
+                target = resolved_blindspots.min_by(&:created_at) ||
+                         @blindspots.values.min_by(&:severity)
+                @blindspots.delete(target.id) if target
+              end
+
+              def prune_boundaries_if_needed
+                return if @boundaries.size < MAX_BOUNDARIES
+
+                oldest = @boundaries.values.min_by(&:created_at)
+                @boundaries.delete(oldest.id) if oldest
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Blindspot
+          module Helpers
+            module Constants
+              MAX_BLINDSPOTS  = 300
+              MAX_BOUNDARIES  = 50
+              DEFAULT_SEVERITY = 0.5
+              SEVERITY_BOOST   = 0.1
+              AWARENESS_THRESHOLD = 0.6
+
+              DISCOVERY_METHODS = %i[
+                error_analysis peer_feedback cross_domain_check
+                contradiction_detection confidence_calibration
+                external_audit self_reflection unknown
+              ].freeze
+
+              SEVERITY_LABELS = {
+                (0.8..)     => :critical,
+                (0.6...0.8) => :high,
+                (0.4...0.6) => :moderate,
+                (0.2...0.4) => :low,
+                (..0.2)     => :negligible
+              }.freeze
+
+              AWARENESS_LABELS = {
+                (0.8..)     => :highly_aware,
+                (0.6...0.8) => :aware,
+                (0.4...0.6) => :partially_blind,
+                (0.2...0.4) => :mostly_blind,
+                (..0.2)     => :unaware
+              }.freeze
+
+              COVERAGE_LABELS = {
+                (0.8..)     => :comprehensive,
+                (0.6...0.8) => :substantial,
+                (0.4...0.6) => :partial,
+                (0.2...0.4) => :limited,
+                (..0.2)     => :minimal
+              }.freeze
+
+              STATUS_LABELS = {
+                active:       'Unknown unknown — not yet surfaced to awareness',
+                acknowledged: 'Known unknown — surfaced, not yet mitigated',
+                mitigated:    'Known unknown — mitigated with partial coverage',
+                resolved:     'Known unknown — fully addressed'
+              }.freeze
+
+              def self.label_for(labels, value)
+                match = labels.find { |range, _| range.cover?(value) }
+                match&.last
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Blindspot
+          module Helpers
+            class KnowledgeBoundary
+              include Constants
+
+              attr_reader :id, :domain, :confidence, :coverage_estimate, :created_at, :updated_at
+
+              def initialize(domain:, confidence: 0.5, coverage_estimate: 0.5)
+                @id               = SecureRandom.uuid
+                @domain           = domain.to_sym
+                @confidence       = confidence.to_f.clamp(0.0, 1.0)
+                @coverage_estimate = coverage_estimate.to_f.clamp(0.0, 1.0)
+                @created_at       = Time.now.utc
+                @updated_at       = Time.now.utc
+              end
+
+              def coverage_label
+                Constants.label_for(COVERAGE_LABELS, @coverage_estimate) || :minimal
+              end
+
+              def gap_detected?(error_occurred: false)
+                error_occurred && @confidence >= AWARENESS_THRESHOLD
+              end
+
+              def update_confidence!(new_confidence)
+                @confidence  = new_confidence.to_f.clamp(0.0, 1.0)
+                @updated_at  = Time.now.utc
+                self
+              end
+
+              def update_coverage!(new_coverage)
+                @coverage_estimate = new_coverage.to_f.clamp(0.0, 1.0)
+                @updated_at        = Time.now.utc
+                self
+              end
+
+              def to_h
+                {
+                  id:                @id,
+                  domain:            @domain,
+                  confidence:        @confidence,
+                  coverage_estimate: @coverage_estimate,
+                  coverage_label:    coverage_label,
+                  created_at:        @created_at,
+                  updated_at:        @updated_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/blindspot/runners/cognitive_blindspot.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Blindspot
+          module Runners
+            module CognitiveBlindspot
+              include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+              def register_blindspot(domain:, discovered_by:, description:,
+                                     severity: nil, **)
+                sev = severity || Helpers::Constants::DEFAULT_SEVERITY
+                spot = engine.register_blindspot(
+                  domain:        domain,
+                  discovered_by: discovered_by,
+                  description:   description,
+                  severity:      sev
+                )
+                { success: true }.merge(spot.to_h)
+              end
+
+              def acknowledge_blindspot(blindspot_id:, **)
+                result = engine.acknowledge_blindspot(blindspot_id: blindspot_id)
+                return { success: false, error: 'blindspot not found' } unless result[:found]
+
+                { success: true }.merge(result)
+              end
+
+              def mitigate_blindspot(blindspot_id:, boost: nil, **)
+                b = boost || Helpers::Constants::SEVERITY_BOOST
+                result = engine.mitigate_blindspot(blindspot_id: blindspot_id, boost: b)
+                return { success: false, error: 'blindspot not found' } unless result[:found]
+
+                { success: true }.merge(result)
+              end
+
+              def resolve_blindspot(blindspot_id:, **)
+                result = engine.resolve_blindspot(blindspot_id: blindspot_id)
+                return { success: false, error: 'blindspot not found' } unless result[:found]
+
+                { success: true }.merge(result)
+              end
+
+              def set_knowledge_boundary(domain:, confidence: 0.5, coverage_estimate: 0.5, **)
+                boundary = engine.set_boundary(
+                  domain:            domain,
+                  confidence:        confidence,
+                  coverage_estimate: coverage_estimate
+                )
+                { success: true }.merge(boundary.to_h)
+              end
+
+              def detect_boundary_gap(domain:, error_occurred: false, **)
+                result = engine.detect_boundary_gap(domain: domain, error_occurred: error_occurred)
+                { success: true }.merge(result)
+              end
+
+              def active_blindspots_report(**)
+                spots = engine.active_blindspots
+                { success: true, count: spots.size, blindspots: spots.map(&:to_h) }
+              end
+
+              def most_severe_report(limit: 5, **)
+                spots = engine.most_severe(limit: limit)
+                { success: true, limit: limit, blindspots: spots.map(&:to_h) }
+              end
+
+              def mitigation_strategies_report(domain: nil, **)
+                strategies = engine.mitigation_strategies(domain: domain)
+                { success: true, count: strategies.size, strategies: strategies }
+              end
+
+              def coverage_report(**)
+                boundaries = engine.coverage_report
+                { success: true, count: boundaries.size, boundaries: boundaries }
+              end
+
+              def johari_report(**)
+                engine.johari_report
+              end
+
+              def awareness_score_report(**)
+                score = engine.awareness_score
+                {
+                  success:         true,
+                  awareness_score: score.round(10),
+                  awareness_label: engine.awareness_label,
+                  awareness_gap:   engine.awareness_gap
+                }
+              end
+
+              def blindspot_stats(**)
+                engine.to_h
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'blindspot/version'
+require_relative 'blindspot/helpers/constants'
+require_relative 'blindspot/helpers/blindspot'
+require_relative 'blindspot/helpers/knowledge_boundary'
+require_relative 'blindspot/helpers/blindspot_engine'
+require_relative 'blindspot/runners/cognitive_blindspot'
+require_relative 'blindspot/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Blindspot
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/agentic/attention/blink/helpers/blink_engine.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Blink
+          module Helpers
+            class BlinkEngine
+              include Constants
+
+              def initialize
+                @stimuli       = {}
+                @blink_active  = false
+                @blink_start   = nil
+                @blink_duration = DEFAULT_BLINK_DURATION
+                @recovery      = 1.0
+                @total_blinks  = 0
+                @total_misses  = 0
+              end
+
+              def submit_stimulus(stimulus_type:, content:, salience: 0.5)
+                prune_stimuli_if_needed
+                stimulus = Stimulus.new(
+                  stimulus_type: stimulus_type,
+                  content:       content,
+                  salience:      salience
+                )
+
+                quality = compute_processing_quality(stimulus)
+                stimulus.process!(quality: quality)
+
+                trigger_blink!(stimulus) if stimulus.salient? && !@blink_active
+                @total_misses += 1 if stimulus.missed?
+
+                @stimuli[stimulus.id] = stimulus
+                stimulus
+              end
+
+              def blink_active?
+                return false unless @blink_active
+
+                elapsed = Time.now.utc.to_f - @blink_start
+                if elapsed >= @blink_duration
+                  @blink_active = false
+                  @recovery = 1.0
+                  return false
+                end
+
+                true
+              end
+
+              def recovery_level
+                return 1.0 unless @blink_active
+
+                elapsed = Time.now.utc.to_f - @blink_start
+                progress = (elapsed / @blink_duration).clamp(0.0, 1.0)
+                (progress**0.5).round(10)
+              end
+
+              def recovery_label
+                match = RECOVERY_LABELS.find { |range, _| range.cover?(recovery_level) }
+                match ? match.last : :saturated
+              end
+
+              def force_blink!(duration: DEFAULT_BLINK_DURATION)
+                @blink_active = true
+                @blink_start = Time.now.utc.to_f
+                @blink_duration = duration.to_f.clamp(MIN_BLINK_DURATION, MAX_BLINK_DURATION)
+                @recovery = 0.0
+                @total_blinks += 1
+                { blink_active: true, duration: @blink_duration, total_blinks: @total_blinks }
+              end
+
+              def force_recover!
+                @blink_active = false
+                @recovery = 1.0
+                @blink_start = nil
+                { blink_active: false, recovery: 1.0 }
+              end
+
+              def adjust_blink_duration(duration:)
+                @blink_duration = duration.to_f.clamp(MIN_BLINK_DURATION, MAX_BLINK_DURATION)
+              end
+
+              def miss_rate
+                return 0.0 if @stimuli.empty?
+
+                (@total_misses.to_f / @stimuli.size).round(10)
+              end
+
+              def recent_stimuli(limit: 10)
+                @stimuli.values.sort_by { |s| -s.arrival_time }.first(limit)
+              end
+
+              def missed_stimuli
+                @stimuli.values.select(&:missed?)
+              end
+
+              def stimuli_by_type(stimulus_type:)
+                st = stimulus_type.to_sym
+                @stimuli.values.select { |s| s.stimulus_type == st }
+              end
+
+              def processing_quality_average
+                return 0.0 if @stimuli.empty?
+
+                qualities = @stimuli.values.map(&:processing_quality)
+                (qualities.sum / qualities.size).round(10)
+              end
+
+              def blink_report
+                {
+                  total_stimuli:  @stimuli.size,
+                  total_blinks:   @total_blinks,
+                  total_misses:   @total_misses,
+                  miss_rate:      miss_rate,
+                  blink_active:   blink_active?,
+                  recovery_level: recovery_level,
+                  recovery_label: recovery_label,
+                  blink_duration: @blink_duration,
+                  avg_quality:    processing_quality_average,
+                  recent_missed:  missed_stimuli.last(5).map(&:to_h)
+                }
+              end
+
+              def to_h
+                {
+                  total_stimuli: @stimuli.size,
+                  total_blinks:  @total_blinks,
+                  miss_rate:     miss_rate,
+                  blink_active:  blink_active?,
+                  avg_quality:   processing_quality_average
+                }
+              end
+
+              private
+
+              def compute_processing_quality(stimulus)
+                if blink_active?
+                  lag1_sparing = stimulus.salience >= (1.0 - LAG1_SPARING_THRESHOLD) ? 0.3 : 0.0
+                  base = (recovery_level * 0.5) + lag1_sparing
+                  [base, stimulus.salience * 0.3].max.clamp(0.0, 1.0).round(10)
+                else
+                  base = 0.6 + (stimulus.salience * 0.4)
+                  base.clamp(0.0, 1.0).round(10)
+                end
+              end
+
+              def trigger_blink!(stimulus)
+                @blink_active = true
+                @blink_start = Time.now.utc.to_f
+                scaled_duration = @blink_duration * (0.5 + (stimulus.salience * 0.5))
+                @blink_duration = scaled_duration.clamp(MIN_BLINK_DURATION, MAX_BLINK_DURATION)
+                @recovery = 0.0
+                @total_blinks += 1
+              end
+
+              def prune_stimuli_if_needed
+                return if @stimuli.size < MAX_STIMULI
+
+                oldest = @stimuli.values.min_by(&:arrival_time)
+                @stimuli.delete(oldest.id) if oldest
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Blink
+          module Helpers
+            module Constants
+              MAX_STIMULI = 500
+              MAX_BLINKS = 200
+
+              DEFAULT_BLINK_DURATION = 3.0
+              MIN_BLINK_DURATION = 0.5
+              MAX_BLINK_DURATION = 10.0
+              RECOVERY_RATE = 0.15
+              SALIENCE_THRESHOLD = 0.6
+              LAG1_SPARING_THRESHOLD = 0.3
+
+              PROCESSING_LABELS = {
+                (0.8..)     => :fully_available,
+                (0.6...0.8) => :mostly_available,
+                (0.4...0.6) => :partially_suppressed,
+                (0.2...0.4) => :mostly_suppressed,
+                (..0.2)     => :blinked
+              }.freeze
+
+              RECOVERY_LABELS = {
+                (0.8..)     => :recovered,
+                (0.6...0.8) => :recovering,
+                (0.4...0.6) => :refractory,
+                (0.2...0.4) => :deep_blink,
+                (..0.2)     => :saturated
+              }.freeze
+
+              STIMULUS_TYPES = %i[
+                visual auditory semantic emotional
+                social threat reward novelty
+              ].freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end