lex-agentic-attention 0.1.0

data/lib/legion/extensions/agentic/attention/kaleidoscope/runners/cognitive_kaleidoscope.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Kaleidoscope
+          module Runners
+            module CognitiveKaleidoscope
+              extend self
+
+              def create_facet(facet_type:, domain:, content:,
+                               brilliance: nil, transparency: nil, angle: nil, engine: nil, **)
+                eng = resolve_engine(engine)
+                f   = eng.create_facet(facet_type: facet_type, domain: domain, content: content,
+                                       brilliance: brilliance, transparency: transparency, angle: angle)
+                { success: true, facet: f.to_h }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def create_pattern(symmetry: :radial, complexity: nil, stability: nil, engine: nil, **)
+                eng = resolve_engine(engine)
+                p   = eng.create_pattern(symmetry: symmetry, complexity: complexity, stability: stability)
+                { success: true, pattern: p.to_h }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def add_to_pattern(facet_id:, pattern_id:, engine: nil, **)
+                eng    = resolve_engine(engine)
+                status = eng.add_facet_to_pattern(facet_id: facet_id, pattern_id: pattern_id)
+                { success: true, status: status }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def rotate(facet_id: nil, pattern_id: nil, degrees: nil, engine: nil, **)
+                eng = resolve_engine(engine)
+                deg = degrees || (Helpers::Constants::ROTATION_STEP * 360)
+                if pattern_id
+                  p = eng.rotate_pattern(pattern_id: pattern_id, degrees: deg)
+                  { success: true, pattern: p.to_h }
+                elsif facet_id
+                  f = eng.rotate_facet(facet_id: facet_id, degrees: deg)
+                  { success: true, facet: f.to_h }
+                else
+                  { success: false, error: 'must provide facet_id or pattern_id' }
+                end
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def polish(facet_id:, rate: nil, engine: nil, **)
+                eng = resolve_engine(engine)
+                f   = eng.polish_facet(facet_id: facet_id, rate: rate || 0.1)
+                { success: true, facet: f.to_h }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def list_facets(engine: nil, facet_type: nil, **)
+                eng     = resolve_engine(engine)
+                results = eng.all_facets
+                results = results.select { |f| f.facet_type == facet_type.to_sym } if facet_type
+                { success: true, facets: results.map(&:to_h), count: results.size }
+              end
+
+              def kaleidoscope_status(engine: nil, **)
+                eng = resolve_engine(engine)
+                { success: true, report: eng.kaleidoscope_report }
+              end
+
+              include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+              private
+
+              def resolve_engine(engine)
+                engine || default_engine
+              end
+
+              def default_engine
+                @default_engine ||= Helpers::KaleidoscopeEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+require_relative 'kaleidoscope/version'
+require_relative 'kaleidoscope/helpers/constants'
+require_relative 'kaleidoscope/helpers/facet'
+require_relative 'kaleidoscope/helpers/pattern'
+require_relative 'kaleidoscope/helpers/kaleidoscope_engine'
+require_relative 'kaleidoscope/runners/cognitive_kaleidoscope'
+require_relative 'kaleidoscope/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Kaleidoscope
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/attention/latent_inhibition/helpers/constants'
+require 'legion/extensions/agentic/attention/latent_inhibition/helpers/stimulus_record'
+require 'legion/extensions/agentic/attention/latent_inhibition/helpers/inhibition_engine'
+require 'legion/extensions/agentic/attention/latent_inhibition/runners/latent_inhibition'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module LatentInhibition
+          class Client
+            include Runners::LatentInhibition
+
+            def initialize(**)
+              @default_engine = Helpers::InhibitionEngine.new
+            end
+
+            private
+
+            attr_reader :default_engine
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module LatentInhibition
+          module Helpers
+            module Constants
+              MAX_STIMULI          = 500
+              INHIBITION_RATE      = 0.03
+              DISINHIBITION_RATE   = 0.2
+              NOVELTY_THRESHOLD    = 3
+
+              INHIBITION_LABELS = {
+                (0.0..0.2) => :uninhibited,
+                (0.2..0.4) => :low,
+                (0.4..0.6) => :moderate,
+                (0.6..0.8) => :high,
+                (0.8..1.0) => :saturated
+              }.freeze
+
+              NOVELTY_LABELS = {
+                true  => :novel,
+                false => :familiar
+              }.freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/latent_inhibition/helpers/inhibition_engine.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module LatentInhibition
+          module Helpers
+            class InhibitionEngine
+              include Constants
+
+              def initialize
+                @stimuli = {}
+              end
+
+              def expose_stimulus(label:)
+                stimulus = find_or_create(label)
+                stimulus.expose!
+                prune_if_needed
+                stimulus.to_h
+              end
+
+              def attempt_association(label:, outcome:)
+                stimulus = find_or_create(label)
+                effectiveness = stimulus.associate!(outcome: outcome)
+                {
+                  label:            label,
+                  outcome:          outcome,
+                  effectiveness:    effectiveness,
+                  inhibition_score: stimulus.inhibition_score,
+                  inhibition_label: stimulus.inhibition_label,
+                  blocked:          effectiveness < 0.1
+                }
+              end
+
+              def disinhibit(label:, intensity:)
+                return { label: label, status: :not_found } unless @stimuli.key?(label)
+
+                stimulus = @stimuli[label]
+                prior_score = stimulus.inhibition_score
+                stimulus.disinhibit!(intensity: intensity)
+                {
+                  label:       label,
+                  prior_score: prior_score,
+                  new_score:   stimulus.inhibition_score,
+                  reduction:   (prior_score - stimulus.inhibition_score).round(10)
+                }
+              end
+
+              def novel_stimuli
+                @stimuli.values.select(&:novel?).map(&:to_h)
+              end
+
+              def most_inhibited(limit: 10)
+                @stimuli.values
+                        .sort_by { |s| -s.inhibition_score }
+                        .first(limit)
+                        .map(&:to_h)
+              end
+
+              def inhibition_report
+                stimuli = @stimuli.values
+                return empty_report if stimuli.empty?
+
+                {
+                  total_stimuli:   stimuli.size,
+                  novel_count:     stimuli.count(&:novel?),
+                  inhibited_count: stimuli.count { |s| s.inhibition_score > 0.0 },
+                  saturated_count: stimuli.count { |s| s.inhibition_label == :saturated },
+                  mean_inhibition: (stimuli.sum(&:inhibition_score) / stimuli.size).round(10),
+                  max_inhibition:  stimuli.map(&:inhibition_score).max.round(10),
+                  label_breakdown: label_breakdown(stimuli)
+                }
+              end
+
+              def prune_if_needed
+                return if @stimuli.size <= Constants::MAX_STIMULI
+
+                overflow = @stimuli.size - Constants::MAX_STIMULI
+                oldest = @stimuli.values.sort_by { |s| s.last_exposed_at || Time.at(0) }.first(overflow)
+                oldest.each { |s| @stimuli.delete(s.label) }
+              end
+
+              def to_h
+                {
+                  stimuli: @stimuli.transform_values(&:to_h),
+                  report:  inhibition_report
+                }
+              end
+
+              private
+
+              def find_or_create(label)
+                @stimuli[label] ||= StimulusRecord.new(label: label)
+              end
+
+              def empty_report
+                {
+                  total_stimuli:   0,
+                  novel_count:     0,
+                  inhibited_count: 0,
+                  saturated_count: 0,
+                  mean_inhibition: 0.0,
+                  max_inhibition:  0.0,
+                  label_breakdown: {}
+                }
+              end
+
+              def label_breakdown(stimuli)
+                stimuli.group_by(&:inhibition_label).transform_values(&:count)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/latent_inhibition/helpers/stimulus_record.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module LatentInhibition
+          module Helpers
+            class StimulusRecord
+              include Constants
+
+              attr_reader :id, :label, :exposure_count, :inhibition_score, :last_exposed_at, :associations
+
+              def initialize(label:)
+                @id              = SecureRandom.uuid
+                @label           = label
+                @exposure_count  = 0
+                @inhibition_score = 0.0
+                @last_exposed_at = nil
+                @associations    = []
+              end
+
+              def expose!
+                @exposure_count  += 1
+                @last_exposed_at  = Time.now.utc
+                @inhibition_score = (@inhibition_score + Constants::INHIBITION_RATE).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def associate!(outcome:)
+                effectiveness = (1.0 - @inhibition_score).clamp(0.0, 1.0).round(10)
+                @associations << { outcome: outcome, effectiveness: effectiveness, recorded_at: Time.now.utc }
+                effectiveness
+              end
+
+              def disinhibit!(intensity:)
+                reduction = (Constants::DISINHIBITION_RATE * intensity.clamp(0.0, 1.0)).round(10)
+                @inhibition_score = (@inhibition_score - reduction).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def novel?
+                @exposure_count < Constants::NOVELTY_THRESHOLD
+              end
+
+              def inhibition_label
+                Constants::INHIBITION_LABELS.find { |range, _| range.cover?(@inhibition_score) }&.last || :saturated
+              end
+
+              def to_h
+                {
+                  id:               @id,
+                  label:            @label,
+                  exposure_count:   @exposure_count,
+                  inhibition_score: @inhibition_score,
+                  inhibition_label: inhibition_label,
+                  novel:            novel?,
+                  last_exposed_at:  @last_exposed_at,
+                  associations:     @associations.dup
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module LatentInhibition
+          module Runners
+            module LatentInhibition
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def expose(label:, engine: nil, **)
+                eng = engine || default_engine
+                result = eng.expose_stimulus(label: label)
+
+                Legion::Logging.debug "[latent_inhibition] expose: label=#{label} " \
+                                      "exposure_count=#{result[:exposure_count]} " \
+                                      "inhibition=#{result[:inhibition_score].round(4)} " \
+                                      "label=#{result[:inhibition_label]} novel=#{result[:novel]}"
+                result
+              end
+
+              def associate(label:, outcome:, engine: nil, **)
+                eng = engine || default_engine
+                result = eng.attempt_association(label: label, outcome: outcome)
+
+                Legion::Logging.debug "[latent_inhibition] associate: label=#{label} outcome=#{outcome} " \
+                                      "effectiveness=#{result[:effectiveness].round(4)} blocked=#{result[:blocked]}"
+                result
+              end
+
+              def disinhibit(label:, intensity: 1.0, engine: nil, **)
+                eng = engine || default_engine
+                result = eng.disinhibit(label: label, intensity: intensity)
+
+                Legion::Logging.debug "[latent_inhibition] disinhibit: label=#{label} " \
+                                      "prior=#{result[:prior_score]&.round(4)} new=#{result[:new_score]&.round(4)}"
+                result
+              end
+
+              def novel_stimuli(engine: nil, **)
+                eng = engine || default_engine
+                stimuli = eng.novel_stimuli
+
+                Legion::Logging.debug "[latent_inhibition] novel_stimuli: count=#{stimuli.size}"
+                { stimuli: stimuli, count: stimuli.size }
+              end
+
+              def most_inhibited(limit: 10, engine: nil, **)
+                eng = engine || default_engine
+                stimuli = eng.most_inhibited(limit: limit)
+
+                Legion::Logging.debug "[latent_inhibition] most_inhibited: limit=#{limit} returned=#{stimuli.size}"
+                { stimuli: stimuli, count: stimuli.size }
+              end
+
+              def inhibition_report(engine: nil, **)
+                eng = engine || default_engine
+                report = eng.inhibition_report
+
+                Legion::Logging.debug "[latent_inhibition] report: total=#{report[:total_stimuli]} " \
+                                      "novel=#{report[:novel_count]} mean=#{report[:mean_inhibition]&.round(4)}"
+                report
+              end
+
+              private
+
+              def default_engine
+                @default_engine ||= Helpers::InhibitionEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/attention/latent_inhibition/version'
+require 'legion/extensions/agentic/attention/latent_inhibition/helpers/constants'
+require 'legion/extensions/agentic/attention/latent_inhibition/helpers/stimulus_record'
+require 'legion/extensions/agentic/attention/latent_inhibition/helpers/inhibition_engine'
+require 'legion/extensions/agentic/attention/latent_inhibition/runners/latent_inhibition'
+require 'legion/extensions/agentic/attention/latent_inhibition/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module LatentInhibition
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/attention/lens/helpers/constants'
+require 'legion/extensions/agentic/attention/lens/helpers/lens'
+require 'legion/extensions/agentic/attention/lens/helpers/lens_stack'
+require 'legion/extensions/agentic/attention/lens/helpers/lens_engine'
+require 'legion/extensions/agentic/attention/lens/runners/cognitive_lens'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Lens
+          class Client
+            include Runners::CognitiveLens
+
+            def initialize(**)
+              @lens_engine = Helpers::LensEngine.new
+            end
+
+            private
+
+            attr_reader :lens_engine
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Lens
+          module Helpers
+            module Constants
+              LENS_TYPES = %i[magnifying wide_angle fish_eye polarized telescopic microscopic].freeze
+
+              DISTORTION_TYPES = %i[none barrel pincushion mustache wave spiral].freeze
+
+              MAX_LENSES = 8
+
+              CLARITY_LABELS = [
+                [0.0..0.2,  :opaque],
+                [0.2..0.4,  :foggy],
+                [0.4..0.6,  :hazy],
+                [0.6..0.8,  :clear],
+                [0.8..1.0,  :crystal]
+              ].freeze
+
+              MAGNIFICATION_LABELS = [
+                [0.1..0.5,  :micro],
+                [0.5..1.0,  :normal],
+                [1.0..2.0,  :zoom],
+                [2.0..5.0,  :telephoto],
+                [5.0..10.0, :extreme]
+              ].freeze
+
+              # Default optical properties per lens type
+              LENS_DEFAULTS = {
+                magnifying:  { magnification: 2.0, aperture: 0.6, distortion: 0.1 },
+                wide_angle:  { magnification: 0.5, aperture: 0.9, distortion: 0.2 },
+                fish_eye:    { magnification: 0.3, aperture: 1.0, distortion: 0.8 },
+                polarized:   { magnification: 1.0, aperture: 0.4, distortion: 0.0 },
+                telescopic:  { magnification: 8.0, aperture: 0.3, distortion: 0.15 },
+                microscopic: { magnification: 9.0, aperture: 0.5, distortion: 0.05 }
+              }.freeze
+
+              # Smudge degrades clarity; clean restores it
+              SMUDGE_RATE_DEFAULT    = 0.05
+              CLEAN_BOOST_DEFAULT    = 0.1
+              CLARITY_SHARP_THRESHOLD = 0.7
+              CLARITY_BLURRY_THRESHOLD = 0.35
+
+              # Stack combination weights
+              STACK_MAGNIFICATION_EXPONENT = 0.8 # sub-linear compounding prevents extremes
+              STACK_DISTORTION_BLEND        = 0.6  # weight toward worst distortion
+              STACK_CLARITY_DECAY           = 0.9  # each additional lens costs 10% clarity
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Lens
+          module Helpers
+            class Lens
+              include Constants
+
+              attr_reader :id, :lens_type, :magnification, :clarity, :distortion, :aperture,
+                          :focus_target, :created_at
+
+              def initialize(lens_type:, magnification: nil, clarity: 1.0, distortion: nil, aperture: nil)
+                raise ArgumentError, "unknown lens_type: #{lens_type}" unless Constants::LENS_TYPES.include?(lens_type)
+
+                defaults = Constants::LENS_DEFAULTS.fetch(lens_type)
+
+                @id            = SecureRandom.uuid
+                @lens_type     = lens_type
+                @magnification = (magnification || defaults[:magnification]).clamp(0.1, 10.0).round(10)
+                @clarity       = clarity.clamp(0.0, 1.0).round(10)
+                @distortion    = (distortion || defaults[:distortion]).clamp(0.0, 1.0).round(10)
+                @aperture      = (aperture || defaults[:aperture]).clamp(0.0, 1.0).round(10)
+                @focus_target  = nil
+                @created_at    = Time.now.utc
+              end
+
+              def focus!(target)
+                @focus_target = target
+                self
+              end
+
+              def defocus!
+                @focus_target = nil
+                self
+              end
+
+              def smudge!(rate = Constants::SMUDGE_RATE_DEFAULT)
+                @clarity = (@clarity - rate.clamp(0.0, 1.0)).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def clean!(boost = Constants::CLEAN_BOOST_DEFAULT)
+                @clarity = (@clarity + boost.clamp(0.0, 1.0)).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def sharp?
+                @clarity >= Constants::CLARITY_SHARP_THRESHOLD
+              end
+
+              def blurry?
+                @clarity <= Constants::CLARITY_BLURRY_THRESHOLD
+              end
+
+              def clarity_label
+                Constants::CLARITY_LABELS.find { |range, _| range.cover?(@clarity) }&.last || :crystal
+              end
+
+              def magnification_label
+                Constants::MAGNIFICATION_LABELS.find { |range, _| range.cover?(@magnification) }&.last || :extreme
+              end
+
+              def focused?
+                !@focus_target.nil?
+              end
+
+              def depth_of_field
+                # Larger aperture = shallower depth of field; higher magnification = shallower
+                base = 1.0 - @aperture
+                mag_factor = 1.0 / [magnification, 0.1].max
+                ((base * 0.6) + (mag_factor * 0.4)).clamp(0.0, 1.0).round(10)
+              end
+
+              def to_h
+                {
+                  id:                  @id,
+                  lens_type:           @lens_type,
+                  magnification:       @magnification,
+                  clarity:             @clarity,
+                  distortion:          @distortion,
+                  aperture:            @aperture,
+                  focus_target:        @focus_target,
+                  sharp:               sharp?,
+                  blurry:              blurry?,
+                  clarity_label:       clarity_label,
+                  magnification_label: magnification_label,
+                  depth_of_field:      depth_of_field
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end