lex-agentic-attention 0.1.0

data/lib/legion/extensions/agentic/attention/lens/helpers/lens_engine.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Lens
+          module Helpers
+            class LensEngine
+              include Constants
+
+              attr_reader :lenses, :stacks
+
+              def initialize
+                @lenses = {}
+                @stacks = {}
+              end
+
+              def create_lens(lens_type:, magnification: nil, clarity: 1.0, distortion: nil, aperture: nil, **)
+                lens = Lens.new(
+                  lens_type:     lens_type,
+                  magnification: magnification,
+                  clarity:       clarity,
+                  distortion:    distortion,
+                  aperture:      aperture
+                )
+                @lenses[lens.id] = lens
+                lens
+              end
+
+              def stack_lenses(lens_ids:, stack_id: nil, **)
+                stack_id ||= SecureRandom.uuid
+                stack = LensStack.new
+
+                lens_ids.each do |lid|
+                  lens = @lenses[lid]
+                  raise ArgumentError, "lens not found: #{lid}" unless lens
+
+                  stack.push_lens(lens)
+                end
+
+                @stacks[stack_id] = stack
+                { stack_id: stack_id, stack: stack }
+              end
+
+              def view_through_stack(stack_id:, content:, **)
+                stack = @stacks[stack_id]
+                raise ArgumentError, "stack not found: #{stack_id}" unless stack
+
+                result = stack.view_through(content)
+                Legion::Logging.debug "[cognitive_lens] view_through stack=#{stack_id} " \
+                                      "perceived=#{result[:perceived].round(4)} " \
+                                      "magnification=#{result[:combined_magnification].round(2)} " \
+                                      "distortion=#{result[:combined_distortion].round(2)} " \
+                                      "clarity=#{result[:stack_clarity].round(2)}"
+                result
+              end
+
+              def degrade_all!(rate: Constants::SMUDGE_RATE_DEFAULT)
+                @lenses.each_value { |l| l.smudge!(rate) }
+                { degraded: @lenses.size, rate: rate }
+              end
+
+              def clearest_lenses(limit: 3)
+                @lenses.values
+                       .sort_by { |l| -l.clarity }
+                       .first(limit)
+                       .map(&:to_h)
+              end
+
+              def most_distorted(limit: 3)
+                @lenses.values
+                       .sort_by { |l| -l.distortion }
+                       .first(limit)
+                       .map(&:to_h)
+              end
+
+              def lens_report
+                return { lens_count: 0, stack_count: 0, lenses: [], stacks: [] } if @lenses.empty?
+
+                avg_clarity    = (@lenses.values.sum(&:clarity) / @lenses.size).round(10)
+                avg_distortion = (@lenses.values.sum(&:distortion) / @lenses.size).round(10)
+
+                {
+                  lens_count:     @lenses.size,
+                  stack_count:    @stacks.size,
+                  avg_clarity:    avg_clarity,
+                  avg_distortion: avg_distortion,
+                  sharp_count:    @lenses.values.count(&:sharp?),
+                  blurry_count:   @lenses.values.count(&:blurry?),
+                  lenses:         @lenses.values.map(&:to_h),
+                  stacks:         @stacks.transform_values(&:to_h)
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/lens/helpers/lens_stack.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Lens
+          module Helpers
+            class LensStack
+              include Constants
+
+              attr_reader :lenses
+
+              def initialize
+                @lenses = []
+              end
+
+              def push_lens(lens)
+                raise ArgumentError, 'expected a Lens instance' unless lens.is_a?(Lens)
+                raise ArgumentError, "stack is full (max #{Constants::MAX_LENSES})" if @lenses.size >= Constants::MAX_LENSES
+
+                @lenses << lens
+                self
+              end
+
+              def pop_lens
+                @lenses.pop
+              end
+
+              def size
+                @lenses.size
+              end
+
+              def empty?
+                @lenses.empty?
+              end
+
+              def combined_magnification
+                return 1.0 if @lenses.empty?
+
+                # Sub-linear compounding via exponent to avoid extreme values
+                base = @lenses.reduce(1.0) { |acc, l| acc * l.magnification }
+                base**Constants::STACK_MAGNIFICATION_EXPONENT
+              end
+
+              def combined_distortion
+                return 0.0 if @lenses.empty?
+
+                max_dist   = @lenses.map(&:distortion).max
+                mean_dist  = @lenses.sum(&:distortion) / @lenses.size
+                # Blend toward worst distortion
+                ((max_dist * Constants::STACK_DISTORTION_BLEND) +
+                 (mean_dist * (1.0 - Constants::STACK_DISTORTION_BLEND))).clamp(0.0, 1.0).round(10)
+              end
+
+              def stack_clarity
+                return 1.0 if @lenses.empty?
+
+                base = @lenses.map(&:clarity).min
+                decay = Constants::STACK_CLARITY_DECAY**(@lenses.size - 1)
+                (base * decay).clamp(0.0, 1.0).round(10)
+              end
+
+              # Apply all lenses to a content value (numeric 0.0-1.0) or hash with :value key
+              def view_through(content)
+                return content if @lenses.empty?
+
+                raw_value = extract_value(content)
+                magnified  = apply_magnification(raw_value)
+                distorted  = apply_distortion(magnified)
+                filtered   = apply_clarity(distorted)
+
+                {
+                  original:               raw_value,
+                  perceived:              filtered.round(10),
+                  combined_magnification: combined_magnification.round(10),
+                  combined_distortion:    combined_distortion.round(10),
+                  stack_clarity:          stack_clarity.round(10),
+                  lens_count:             @lenses.size,
+                  focus_active:           @lenses.any?(&:focused?)
+                }
+              end
+
+              def to_h
+                {
+                  lens_count:             @lenses.size,
+                  combined_magnification: combined_magnification.round(10),
+                  combined_distortion:    combined_distortion.round(10),
+                  stack_clarity:          stack_clarity.round(10),
+                  lenses:                 @lenses.map(&:to_h)
+                }
+              end
+
+              private
+
+              def extract_value(content)
+                if content.is_a?(Hash)
+                  content.fetch(:value, 0.5).clamp(0.0, 1.0)
+                else
+                  content.to_f.clamp(0.0, 1.0)
+                end
+              end
+
+              def apply_magnification(value)
+                mag = combined_magnification
+                # Magnification centers around 0.5; scale distance from center
+                center    = 0.5
+                distance  = value - center
+                (center + (distance * mag)).clamp(0.0, 1.0)
+              end
+
+              def apply_distortion(value)
+                dist = combined_distortion
+                return value if dist.zero?
+
+                # Barrel distortion pushes values toward extremes
+                noise = (value - 0.5).abs * dist * 0.2
+                sign  = value >= 0.5 ? 1 : -1
+                (value + (sign * noise)).clamp(0.0, 1.0)
+              end
+
+              def apply_clarity(value)
+                clarity = stack_clarity
+                # Low clarity pulls perceived value toward neutral (0.5)
+                center = 0.5
+                (center + ((value - center) * clarity)).clamp(0.0, 1.0)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/lens/runners/cognitive_lens.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Lens
+          module Runners
+            module CognitiveLens
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def create_lens(lens_type:, magnification: nil, clarity: 1.0, distortion: nil, aperture: nil,
+                              engine: nil, **)
+                raise ArgumentError, "unknown lens_type: #{lens_type}" unless Helpers::Constants::LENS_TYPES.include?(lens_type)
+
+                eng  = engine || lens_engine
+                lens = eng.create_lens(
+                  lens_type:     lens_type,
+                  magnification: magnification,
+                  clarity:       clarity,
+                  distortion:    distortion,
+                  aperture:      aperture
+                )
+                Legion::Logging.debug "[cognitive_lens] created lens id=#{lens.id} type=#{lens_type} " \
+                                      "mag=#{lens.magnification.round(2)} clarity=#{lens.clarity.round(2)}"
+                { success: true, lens: lens.to_h }
+              rescue ArgumentError => e
+                Legion::Logging.warn "[cognitive_lens] create_lens failed: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def stack_lenses(lens_ids:, stack_id: nil, engine: nil, **)
+                raise ArgumentError, 'lens_ids must be an array' unless lens_ids.is_a?(Array)
+
+                eng    = engine || lens_engine
+                result = eng.stack_lenses(lens_ids: lens_ids, stack_id: stack_id)
+                Legion::Logging.debug "[cognitive_lens] stacked #{lens_ids.size} lenses stack_id=#{result[:stack_id]}"
+                { success: true, stack_id: result[:stack_id], stack: result[:stack].to_h }
+              rescue ArgumentError => e
+                Legion::Logging.warn "[cognitive_lens] stack_lenses failed: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def view_through_stack(stack_id:, content:, engine: nil, **)
+                eng    = engine || lens_engine
+                result = eng.view_through_stack(stack_id: stack_id, content: content)
+                { success: true, **result }
+              rescue ArgumentError => e
+                Legion::Logging.warn "[cognitive_lens] view_through_stack failed: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def degrade_all(rate: Helpers::Constants::SMUDGE_RATE_DEFAULT, engine: nil, **)
+                eng    = engine || lens_engine
+                result = eng.degrade_all!(rate: rate)
+                Legion::Logging.debug "[cognitive_lens] degraded #{result[:degraded]} lenses at rate=#{rate}"
+                { success: true, **result }
+              end
+
+              def lens_report(engine: nil, **)
+                eng    = engine || lens_engine
+                report = eng.lens_report
+                { success: true, **report }
+              end
+
+              def clearest_lenses(limit: 3, engine: nil, **)
+                eng = engine || lens_engine
+                lenses = eng.clearest_lenses(limit: limit)
+                { success: true, lenses: lenses }
+              end
+
+              def most_distorted(limit: 3, engine: nil, **)
+                eng = engine || lens_engine
+                lenses = eng.most_distorted(limit: limit)
+                { success: true, lenses: lenses }
+              end
+
+              private
+
+              def lens_engine
+                @lens_engine ||= Helpers::LensEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+require_relative 'lens/version'
+require_relative 'lens/helpers/constants'
+require_relative 'lens/helpers/lens'
+require_relative 'lens/helpers/lens_stack'
+require_relative 'lens/helpers/lens_engine'
+require_relative 'lens/runners/cognitive_lens'
+require_relative 'lens/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Lens
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Lighthouse
+          class Client
+            include Runners::CognitiveLighthouse
+
+            def initialize(engine: nil, **)
+              @engine = engine || Helpers::LighthouseEngine.new
+            end
+
+            private
+
+            def default_engine
+              @engine
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/lighthouse/helpers/beacon.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Lighthouse
+          module Helpers
+            class Beacon
+              attr_reader :id, :beacon_type, :domain, :content, :sweep_angle, :lit_at
+              attr_accessor :luminosity
+
+              def initialize(beacon_type:, domain:, content:, luminosity: nil, sweep_angle: nil)
+                validate_beacon_type!(beacon_type)
+                @id          = SecureRandom.uuid
+                @beacon_type = beacon_type.to_sym
+                @domain      = domain.to_s
+                @content     = content.to_s
+                @luminosity  = (luminosity || 0.7).to_f.clamp(0.0, 1.0).round(10)
+                @sweep_angle = (sweep_angle || 0.0).to_f.clamp(0.0, 360.0).round(10)
+                @lit_at      = Time.now.utc
+              end
+
+              def brighten!(rate: Constants::LUMINOSITY_RATE)
+                @luminosity = (@luminosity + rate).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def dim!(rate: Constants::LUMINOSITY_RATE)
+                @luminosity = (@luminosity - rate).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def extinguished?
+                @luminosity <= 0.0
+              end
+
+              def blazing?
+                @luminosity >= 0.9
+              end
+
+              def luminosity_label
+                Constants.label_for(Constants::LUMINOSITY_LABELS, @luminosity)
+              end
+
+              def to_h
+                {
+                  id:               @id,
+                  beacon_type:      @beacon_type,
+                  domain:           @domain,
+                  content:          @content,
+                  luminosity:       @luminosity,
+                  sweep_angle:      @sweep_angle,
+                  luminosity_label: luminosity_label,
+                  extinguished:     extinguished?,
+                  blazing:          blazing?,
+                  lit_at:           @lit_at
+                }
+              end
+
+              private
+
+              def validate_beacon_type!(type)
+                sym = type.to_sym
+                return if Constants::BEACON_TYPES.include?(sym)
+
+                raise ArgumentError,
+                      "unknown beacon_type: #{type.inspect}; must be one of #{Constants::BEACON_TYPES.inspect}"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Lighthouse
+          module Helpers
+            module Constants
+              BEACON_TYPES = %i[truth clarity warning guidance hope].freeze
+              FOG_TYPES    = %i[confusion uncertainty ambiguity doubt overwhelm].freeze
+
+              MAX_BEACONS   = 100
+              MAX_FOG_BANKS = 50
+
+              LUMINOSITY_RATE   = 0.1
+              FOG_DENSITY_RATE  = 0.05
+
+              # Visibility labels (fog density: high density = low visibility)
+              VISIBILITY_LABELS = [
+                [(0.0...0.1), :crystal_clear],
+                [(0.1...0.3), :clear],
+                [(0.3...0.5), :hazy],
+                [(0.5...0.7), :foggy],
+                [(0.7...0.9), :dense_fog],
+                [(0.9..),     :blind]
+              ].freeze
+
+              # Luminosity labels (beacon luminosity: high = bright)
+              LUMINOSITY_LABELS = [
+                [(0.9..),      :blazing],
+                [(0.7...0.9),  :bright],
+                [(0.5...0.7),  :steady],
+                [(0.3...0.5),  :dim],
+                [(0.1...0.3),  :faint],
+                [(..0.1),      :dark]
+              ].freeze
+
+              def self.label_for(table, value)
+                table.each { |range, label| return label if range.cover?(value) }
+                table.last.last
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/lighthouse/helpers/fog.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Lighthouse
+          module Helpers
+            class Fog
+              attr_reader :id, :fog_type, :domain, :extent, :formed_at
+              attr_accessor :density
+
+              def initialize(fog_type:, domain:, density: nil, extent: nil)
+                validate_fog_type!(fog_type)
+                @id       = SecureRandom.uuid
+                @fog_type = fog_type.to_sym
+                @domain   = domain.to_s
+                @density  = (density || 0.5).to_f.clamp(0.0, 1.0).round(10)
+                @extent   = (extent || 1.0).to_f.clamp(0.0, 1.0).round(10)
+                @formed_at = Time.now.utc
+              end
+
+              def thicken!(rate: Constants::FOG_DENSITY_RATE)
+                @density = (@density + rate).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def disperse!(rate: Constants::FOG_DENSITY_RATE)
+                @density = (@density - rate).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def impenetrable?
+                @density >= 1.0
+              end
+
+              def clearing?
+                @density < 0.2
+              end
+
+              def visibility_label
+                Constants.label_for(Constants::VISIBILITY_LABELS, @density)
+              end
+
+              def to_h
+                {
+                  id:               @id,
+                  fog_type:         @fog_type,
+                  domain:           @domain,
+                  density:          @density,
+                  extent:           @extent,
+                  visibility_label: visibility_label,
+                  impenetrable:     impenetrable?,
+                  clearing:         clearing?,
+                  formed_at:        @formed_at
+                }
+              end
+
+              private
+
+              def validate_fog_type!(type)
+                sym = type.to_sym
+                return if Constants::FOG_TYPES.include?(sym)
+
+                raise ArgumentError,
+                      "unknown fog_type: #{type.inspect}; must be one of #{Constants::FOG_TYPES.inspect}"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end