lex-agentic-attention 0.1.0

data/lib/legion/extensions/agentic/attention/focus/helpers/habituation.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Focus
+          module Helpers
+            class Habituation
+              def initialize
+                @domain_exposure = Hash.new(0.0)
+                @domain_last_seen = {}
+              end
+
+              def record(domain)
+                domain = domain.to_sym
+                @domain_exposure[domain] = [
+                  @domain_exposure[domain] + Constants::HABITUATION_RATE,
+                  Constants::HABITUATION_CEILING
+                ].min
+                @domain_last_seen[domain] = Time.now.utc
+              end
+
+              def level(domain)
+                domain = domain.to_sym
+                @domain_exposure[domain]
+              end
+
+              def apply_novelty_reset(domain, novelty: 0.5)
+                domain = domain.to_sym
+                return unless novelty > 0.5
+
+                reduction = (novelty - 0.5) * Constants::NOVELTY_RESET_FACTOR
+                @domain_exposure[domain] = [@domain_exposure[domain] - reduction, 0.0].max
+              end
+
+              def decay_all
+                @domain_exposure.each_key do |domain|
+                  @domain_exposure[domain] = [
+                    @domain_exposure[domain] - Constants::HABITUATION_DECAY,
+                    0.0
+                  ].max
+                end
+
+                @domain_exposure.delete_if { |_, v| v <= 0.0 }
+              end
+
+              def stats
+                @domain_exposure.transform_values { |v| v.round(3) }
+              end
+
+              def habituated_domains(threshold: 0.5)
+                @domain_exposure.select { |_, v| v >= threshold }.keys
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Focus
+          module Runners
+            module Attention
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def filter_signals(signals: [], active_wonders: [], **)
+                return { filtered: [], spotlight: 0, peripheral: 0, background: 0, dropped: 0 } if signals.empty?
+
+                unique = Helpers::Focus.deduplicate(signals)
+                scored = score_all(unique, active_wonders)
+                categorized = categorize(scored)
+
+                habituation_model.decay_all
+
+                Legion::Logging.debug "[attention] filtered #{signals.size}->#{categorized[:spotlight].size + categorized[:peripheral].size} " \
+                                      "(spotlight=#{categorized[:spotlight].size} peripheral=#{categorized[:peripheral].size} " \
+                                      "background=#{categorized[:background].size} dropped=#{categorized[:dropped]})"
+
+                {
+                  filtered:   categorized[:spotlight] + categorized[:peripheral],
+                  spotlight:  categorized[:spotlight].size,
+                  peripheral: categorized[:peripheral].size,
+                  background: categorized[:background].size,
+                  dropped:    categorized[:dropped]
+                }
+              end
+
+              def attention_status(**)
+                {
+                  manual_focus:       focus_manager.manual_focus,
+                  habituated_domains: habituation_model.habituated_domains,
+                  habituation_stats:  habituation_model.stats,
+                  capacity:           Helpers::Constants::ATTENTIONAL_CAPACITY,
+                  focus_count:        focus_manager.manual_focus.size
+                }
+              end
+
+              def focus_on(domain:, reason: nil, **)
+                result = focus_manager.focus_on(domain, reason: reason)
+                Legion::Logging.info "[attention] focus_on #{domain}: #{result}"
+                { status: result, domain: domain }
+              end
+
+              def release_focus(domain:, **)
+                result = focus_manager.release(domain)
+                Legion::Logging.info "[attention] release_focus #{domain}: #{result}"
+                { status: result, domain: domain }
+              end
+
+              def habituation_stats(**)
+                { domains: habituation_model.stats, habituated: habituation_model.habituated_domains }
+              end
+
+              private
+
+              def focus_manager
+                @focus_manager ||= Helpers::FocusManager.new
+              end
+
+              def habituation_model
+                @habituation_model ||= Helpers::Habituation.new
+              end
+
+              def score_all(signals, active_wonders)
+                signals.map do |signal|
+                  domain = Helpers::Focus.extract_domain(signal)
+                  habituation_model.record(domain)
+
+                  novelty = Helpers::Focus.extract_novelty(signal)
+                  habituation_model.apply_novelty_reset(domain, novelty: novelty)
+
+                  goal_rel = focus_manager.goal_relevance(signal, active_wonders: active_wonders)
+                  hab_level = habituation_model.level(domain)
+                  score = Helpers::Focus.score_signal(signal, habituation_level: hab_level, goal_relevance: goal_rel)
+                  tier = Helpers::Focus.attention_tier(score)
+
+                  Helpers::Focus.tag_signal(signal, attention_score: score, attention_tier: tier)
+                end
+              end
+
+              def categorize(scored_signals)
+                result = { spotlight: [], peripheral: [], background: [], dropped: 0 }
+
+                scored_signals.each do |signal|
+                  case signal[:attention_tier]
+                  when :spotlight  then result[:spotlight] << signal
+                  when :peripheral then result[:peripheral] << signal
+                  when :background then result[:background] << signal
+                  else result[:dropped] += 1
+                  end
+                end
+
+                enforce_capacity(result)
+              end
+
+              def enforce_capacity(categorized)
+                capacity = Helpers::Constants::ATTENTIONAL_CAPACITY
+                spotlight = categorized[:spotlight].sort_by { |s| -(s[:attention_score] || 0) }
+
+                if spotlight.size > capacity
+                  overflow = spotlight[capacity..]
+                  categorized[:spotlight] = spotlight.first(capacity)
+                  categorized[:peripheral].concat(overflow)
+                end
+
+                categorized
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/attention/focus/version'
+require 'legion/extensions/agentic/attention/focus/helpers/constants'
+require 'legion/extensions/agentic/attention/focus/helpers/focus'
+require 'legion/extensions/agentic/attention/focus/helpers/focus_manager'
+require 'legion/extensions/agentic/attention/focus/helpers/habituation'
+require 'legion/extensions/agentic/attention/focus/runners/attention'
+require 'legion/extensions/agentic/attention/focus/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Focus
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Kaleidoscope
+          class Client
+            include Runners::CognitiveKaleidoscope
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Kaleidoscope
+          module Helpers
+            module Constants
+              FACET_TYPES = %i[belief experience emotion memory intuition].freeze
+
+              ROTATION_MODES = %i[slow steady rapid chaotic].freeze
+
+              SYMMETRY_TYPES = %i[bilateral radial rotational asymmetric].freeze
+
+              MAX_FACETS   = 500
+              MAX_PATTERNS = 100
+              ROTATION_STEP = 0.1
+              DECAY_RATE    = 0.02
+              BRILLIANCE_THRESHOLD = 0.8
+
+              BRILLIANCE_LABELS = [
+                [(0.8..),      :dazzling],
+                [(0.6...0.8),  :vivid],
+                [(0.4...0.6),  :moderate],
+                [(0.2...0.4),  :dim],
+                [(..0.2),      :dark]
+              ].freeze
+
+              COMPLEXITY_LABELS = [
+                [(0.8..),      :fractal],
+                [(0.6...0.8),  :intricate],
+                [(0.4...0.6),  :balanced],
+                [(0.2...0.4),  :simple],
+                [(..0.2),      :minimal]
+              ].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/kaleidoscope/helpers/facet.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Kaleidoscope
+          module Helpers
+            class Facet
+              attr_reader :id, :facet_type, :domain, :content,
+                          :angle, :created_at
+              attr_accessor :brilliance, :transparency
+
+              def initialize(facet_type:, domain:, content:,
+                             brilliance: nil, transparency: nil, angle: nil)
+                validate_facet_type!(facet_type)
+                @id           = SecureRandom.uuid
+                @facet_type   = facet_type.to_sym
+                @domain       = domain.to_sym
+                @content      = content.to_s
+                @brilliance   = (brilliance || 0.7).to_f.clamp(0.0, 1.0).round(10)
+                @transparency = (transparency || 0.5).to_f.clamp(0.0, 1.0).round(10)
+                @angle        = (angle || 0.0).to_f.clamp(0.0, 360.0).round(10)
+                @created_at   = Time.now.utc
+              end
+
+              def rotate!(degrees: Constants::ROTATION_STEP * 360)
+                @angle = ((@angle + degrees.abs) % 360.0).round(10)
+              end
+
+              def polish!(rate: 0.1)
+                @brilliance = (@brilliance + rate.abs).clamp(0.0, 1.0).round(10)
+              end
+
+              def tarnish!(rate: Constants::DECAY_RATE)
+                @brilliance = (@brilliance - rate.abs).clamp(0.0, 1.0).round(10)
+              end
+
+              def dazzling?
+                @brilliance >= Constants::BRILLIANCE_THRESHOLD
+              end
+
+              def dark?
+                @brilliance < 0.2
+              end
+
+              def opaque?
+                @transparency < 0.2
+              end
+
+              def clear?
+                @transparency >= 0.8
+              end
+
+              def brilliance_label
+                Constants.label_for(Constants::BRILLIANCE_LABELS, @brilliance)
+              end
+
+              def to_h
+                {
+                  id:               @id,
+                  facet_type:       @facet_type,
+                  domain:           @domain,
+                  content:          @content,
+                  brilliance:       @brilliance,
+                  transparency:     @transparency,
+                  angle:            @angle,
+                  brilliance_label: brilliance_label,
+                  dazzling:         dazzling?,
+                  dark:             dark?,
+                  created_at:       @created_at
+                }
+              end
+
+              private
+
+              def validate_facet_type!(val)
+                return if Constants::FACET_TYPES.include?(val.to_sym)
+
+                raise ArgumentError,
+                      "unknown facet type: #{val.inspect}; " \
+                      "must be one of #{Constants::FACET_TYPES.inspect}"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Kaleidoscope
+          module Helpers
+            class KaleidoscopeEngine
+              def initialize
+                @facets   = {}
+                @patterns = {}
+              end
+
+              def create_facet(facet_type:, domain:, content:, brilliance: nil, transparency: nil, angle: nil)
+                raise ArgumentError, 'facet limit reached' if @facets.size >= Constants::MAX_FACETS
+
+                f = Facet.new(facet_type: facet_type, domain: domain, content: content,
+                              brilliance: brilliance, transparency: transparency, angle: angle)
+                @facets[f.id] = f
+                f
+              end
+
+              def create_pattern(symmetry: :radial, complexity: nil, stability: nil)
+                raise ArgumentError, 'pattern limit reached' if @patterns.size >= Constants::MAX_PATTERNS
+
+                p = Pattern.new(symmetry: symmetry, complexity: complexity, stability: stability)
+                @patterns[p.id] = p
+                p
+              end
+
+              def add_facet_to_pattern(facet_id:, pattern_id:)
+                fetch_facet(facet_id)
+                pattern = fetch_pattern(pattern_id)
+                pattern.add_facet(facet_id)
+              end
+
+              def rotate_facet(facet_id:, degrees: Constants::ROTATION_STEP * 360)
+                facet = fetch_facet(facet_id)
+                facet.rotate!(degrees: degrees)
+                facet
+              end
+
+              def polish_facet(facet_id:, rate: 0.1)
+                facet = fetch_facet(facet_id)
+                facet.polish!(rate: rate)
+                facet
+              end
+
+              def rotate_pattern(pattern_id:, degrees: Constants::ROTATION_STEP * 360)
+                pattern = fetch_pattern(pattern_id)
+                pattern.rotate_all!(degrees: degrees)
+                resolve_facets(pattern).each { |f| f.rotate!(degrees: degrees) }
+                pattern
+              end
+
+              def tarnish_all!
+                @facets.each_value(&:tarnish!)
+              end
+
+              def facets_by_type
+                counts = Constants::FACET_TYPES.to_h { |t| [t, 0] }
+                @facets.each_value { |f| counts[f.facet_type] += 1 }
+                counts
+              end
+
+              def brightest(limit: 5)
+                @facets.values.sort_by { |f| -f.brilliance }.first(limit)
+              end
+
+              def dimmest(limit: 5)
+                @facets.values.sort_by(&:brilliance).first(limit)
+              end
+
+              def most_complex_patterns(limit: 5)
+                @patterns.values.sort_by { |p| -p.complexity }.first(limit)
+              end
+
+              def most_stable_patterns(limit: 5)
+                @patterns.values.sort_by { |p| -p.stability }.first(limit)
+              end
+
+              def dazzling_facets
+                @facets.values.select(&:dazzling?)
+              end
+
+              def dark_facets
+                @facets.values.select(&:dark?)
+              end
+
+              def avg_brilliance
+                return 0.0 if @facets.empty?
+
+                (@facets.values.sum(&:brilliance) / @facets.size).round(10)
+              end
+
+              def avg_complexity
+                return 0.0 if @patterns.empty?
+
+                (@patterns.values.sum(&:complexity) / @patterns.size).round(10)
+              end
+
+              def kaleidoscope_report
+                {
+                  total_facets:   @facets.size,
+                  total_patterns: @patterns.size,
+                  by_type:        facets_by_type,
+                  dazzling_count: dazzling_facets.size,
+                  dark_count:     dark_facets.size,
+                  avg_brilliance: avg_brilliance,
+                  avg_complexity: avg_complexity
+                }
+              end
+
+              def all_facets
+                @facets.values
+              end
+
+              def all_patterns
+                @patterns.values
+              end
+
+              private
+
+              def fetch_facet(id)
+                @facets.fetch(id) { raise ArgumentError, "facet not found: #{id}" }
+              end
+
+              def fetch_pattern(id)
+                @patterns.fetch(id) { raise ArgumentError, "pattern not found: #{id}" }
+              end
+
+              def resolve_facets(pattern)
+                pattern.facet_ids.filter_map { |fid| @facets[fid] }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Kaleidoscope
+          module Helpers
+            class Pattern
+              attr_reader :id, :symmetry, :facet_ids, :created_at
+              attr_accessor :complexity, :stability
+
+              def initialize(symmetry: :radial, complexity: nil, stability: nil)
+                validate_symmetry!(symmetry)
+                @id         = SecureRandom.uuid
+                @symmetry   = symmetry.to_sym
+                @complexity = (complexity || 0.5).to_f.clamp(0.0, 1.0).round(10)
+                @stability  = (stability || 0.7).to_f.clamp(0.0, 1.0).round(10)
+                @facet_ids  = []
+                @created_at = Time.now.utc
+              end
+
+              def add_facet(facet_id)
+                return :already_present if @facet_ids.include?(facet_id)
+
+                @facet_ids << facet_id
+                recalculate_complexity!
+                :added
+              end
+
+              def remove_facet(facet_id)
+                return :not_found unless @facet_ids.include?(facet_id)
+
+                @facet_ids.delete(facet_id)
+                recalculate_complexity!
+                :removed
+              end
+
+              def rotate_all!(degrees: Constants::ROTATION_STEP * 360)
+                @stability = (@stability - (degrees.abs / 3600.0)).clamp(0.0, 1.0).round(10)
+                degrees
+              end
+
+              def stabilize!(rate: 0.1)
+                @stability = (@stability + rate.abs).clamp(0.0, 1.0).round(10)
+              end
+
+              def destabilize!(rate: 0.05)
+                @stability = (@stability - rate.abs).clamp(0.0, 1.0).round(10)
+              end
+
+              def fractal?
+                @complexity >= 0.8
+              end
+
+              def minimal?
+                @complexity < 0.2
+              end
+
+              def stable?
+                @stability >= 0.7
+              end
+
+              def chaotic?
+                @stability < 0.3
+              end
+
+              def complexity_label
+                Constants.label_for(Constants::COMPLEXITY_LABELS, @complexity)
+              end
+
+              def facet_count
+                @facet_ids.size
+              end
+
+              def to_h
+                {
+                  id:               @id,
+                  symmetry:         @symmetry,
+                  complexity:       @complexity,
+                  stability:        @stability,
+                  complexity_label: complexity_label,
+                  facet_count:      facet_count,
+                  fractal:          fractal?,
+                  chaotic:          chaotic?,
+                  created_at:       @created_at
+                }
+              end
+
+              private
+
+              def validate_symmetry!(val)
+                return if Constants::SYMMETRY_TYPES.include?(val.to_sym)
+
+                raise ArgumentError,
+                      "unknown symmetry: #{val.inspect}; " \
+                      "must be one of #{Constants::SYMMETRY_TYPES.inspect}"
+              end
+
+              def recalculate_complexity!
+                base = (@facet_ids.size / 20.0).clamp(0.0, 1.0)
+                @complexity = base.round(10)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end