lex-agentic-attention 0.1.0

data/lib/legion/extensions/agentic/attention/subliminal/helpers/influence_event.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Subliminal
+          module Helpers
+            class InfluenceEvent
+              include Constants
+
+              attr_reader :id, :trace_id, :target, :magnitude, :domain, :created_at
+
+              def initialize(trace_id:, target:, magnitude:, domain: :general)
+                @id = SecureRandom.uuid
+                @trace_id = trace_id
+                @target = target.to_sym
+                @magnitude = magnitude.to_f.clamp(0.0, MAX_INFLUENCE_PER_DOMAIN).round(10)
+                @domain = domain.to_sym
+                @created_at = Time.now
+              end
+
+              def significant? = @magnitude >= 0.05
+              def subtle? = @magnitude < 0.05 && @magnitude > 0.0
+
+              def to_h
+                {
+                  id:         @id,
+                  trace_id:   @trace_id,
+                  target:     @target,
+                  magnitude:  @magnitude,
+                  domain:     @domain,
+                  created_at: @created_at.iso8601
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/subliminal/helpers/subliminal_engine.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Subliminal
+          module Helpers
+            class SubliminalEngine
+              include Constants
+
+              def initialize
+                @traces = {}
+                @influences = []
+              end
+
+              def create_trace(content:, trace_type: :associative, domain: :general, activation: DEFAULT_ACTIVATION,
+                               influence_target: :attention)
+                prune_extinct
+                trace = SubliminalTrace.new(content: content, trace_type: trace_type, domain: domain,
+                                            activation: activation, influence_target: influence_target)
+                @traces[trace.id] = trace
+                trace
+              end
+
+              def boost_trace(trace_id:, amount: ACTIVATION_BOOST)
+                trace = @traces[trace_id]
+                return nil unless trace
+
+                trace.boost!(amount: amount)
+                trace
+              end
+
+              def process_influences!
+                active = active_traces
+                events = []
+                active.each do |trace|
+                  mag = trace.exert_influence!
+                  next if mag <= 0.0
+
+                  event = InfluenceEvent.new(trace_id: trace.id, target: trace.influence_target,
+                                             magnitude: mag, domain: trace.domain)
+                  events << event
+                  @influences << event
+                end
+                prune_influences
+                { influences_generated: events.size, events: events.map(&:to_h) }
+              end
+
+              def decay_all!
+                @traces.each_value(&:decay!)
+                prune_extinct
+                { traces_remaining: @traces.size }
+              end
+
+              def active_traces = @traces.values.select(&:active?)
+              def near_threshold_traces = @traces.values.select(&:near_threshold?)
+              def potent_traces = @traces.values.select(&:potent?)
+              def extinct_traces = @traces.values.select(&:extinct?)
+
+              def traces_by_domain(domain:)
+                @traces.values.select { |t| t.domain == domain.to_sym }
+              end
+
+              def traces_by_type(trace_type:)
+                @traces.values.select { |t| t.trace_type == trace_type.to_sym }
+              end
+
+              def traces_by_target(target:)
+                @traces.values.select { |t| t.influence_target == target.to_sym }
+              end
+
+              def influence_on(target:)
+                recent = @influences.last(100).select { |e| e.target == target.to_sym }
+                return 0.0 if recent.empty?
+
+                recent.sum(&:magnitude).clamp(0.0, MAX_TOTAL_INFLUENCE).round(10)
+              end
+
+              def domain_saturation(domain:)
+                domain_traces = traces_by_domain(domain: domain)
+                return 0.0 if domain_traces.empty?
+
+                total_activation = domain_traces.sum(&:activation)
+                (total_activation / (domain_traces.size * SUBLIMINAL_CEILING)).clamp(0.0, 1.0).round(10)
+              end
+
+              def overall_subliminal_load
+                return 0.0 if @traces.empty?
+
+                active = active_traces
+                return 0.0 if active.empty?
+
+                (active.sum(&:activation) / (active.size * SUBLIMINAL_CEILING)).clamp(0.0, 1.0).round(10)
+              end
+
+              def saturation_label = Constants.label_for(SATURATION_LABELS, overall_subliminal_load)
+
+              def strongest_traces(limit: 5) = @traces.values.sort_by { |t| -t.activation }.first(limit)
+
+              def breached_traces
+                @traces.values.select(&:breached_threshold?)
+              end
+
+              def subliminal_report
+                {
+                  total_traces:     @traces.size,
+                  active_count:     active_traces.size,
+                  near_threshold:   near_threshold_traces.size,
+                  potent_count:     potent_traces.size,
+                  total_influences: @influences.size,
+                  subliminal_load:  overall_subliminal_load,
+                  saturation_label: saturation_label,
+                  breached_count:   breached_traces.size,
+                  strongest:        strongest_traces(limit: 3).map(&:to_h)
+                }
+              end
+
+              def to_h
+                {
+                  total_traces:     @traces.size,
+                  active:           active_traces.size,
+                  subliminal_load:  overall_subliminal_load,
+                  total_influences: @influences.size
+                }
+              end
+
+              private
+
+              def prune_extinct
+                return if @traces.size < MAX_TRACES
+
+                @traces.reject! { |_, t| t.extinct? }
+                return unless @traces.size >= MAX_TRACES
+
+                weakest = @traces.values.min_by(&:activation)
+                @traces.delete(weakest.id) if weakest
+              end
+
+              def prune_influences
+                @influences.shift while @influences.size > MAX_INFLUENCES
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/subliminal/helpers/subliminal_trace.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Subliminal
+          module Helpers
+            class SubliminalTrace
+              include Constants
+
+              attr_reader :id, :content, :trace_type, :domain, :original_activation,
+                          :influence_target, :created_at, :influence_count
+              attr_accessor :activation
+
+              def initialize(content:, trace_type: :associative, domain: :general, activation: DEFAULT_ACTIVATION,
+                             influence_target: :attention)
+                @id = SecureRandom.uuid
+                @content = content.to_s
+                @trace_type = valid_trace_type(trace_type)
+                @domain = domain.to_sym
+                @activation = activation.to_f.clamp(SUBLIMINAL_FLOOR, SUBLIMINAL_CEILING).round(10)
+                @original_activation = @activation
+                @influence_target = valid_influence_target(influence_target)
+                @influence_count = 0
+                @created_at = Time.now
+              end
+
+              def boost!(amount: ACTIVATION_BOOST)
+                @activation = (@activation + amount).clamp(0.0, SUBLIMINAL_CEILING).round(10)
+                self
+              end
+
+              def decay!
+                @activation = (@activation - ACTIVATION_DECAY).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def exert_influence!
+                @influence_count += 1
+                @activation = (@activation - (INFLUENCE_STRENGTH * 0.5)).clamp(0.0, 1.0).round(10)
+                influence_magnitude
+              end
+
+              def influence_magnitude
+                (@activation * INFLUENCE_STRENGTH).clamp(0.0, MAX_INFLUENCE_PER_DOMAIN).round(10)
+              end
+
+              def near_threshold? = @activation >= 0.3 && @activation < CONSCIOUS_THRESHOLD
+              def active? = @activation >= SUBLIMINAL_FLOOR
+              def extinct? = @activation < EXTINCTION_THRESHOLD
+              def potent? = @activation >= 0.2
+
+              def breached_threshold?
+                @activation >= CONSCIOUS_THRESHOLD
+              end
+
+              def persistence = (@activation / @original_activation).clamp(0.0, 1.0).round(10)
+              def activation_label = Constants.label_for(ACTIVATION_LABELS, @activation)
+              def influence_label = Constants.label_for(INFLUENCE_LABELS, influence_magnitude)
+
+              def to_h
+                {
+                  id:                  @id,
+                  content:             @content,
+                  trace_type:          @trace_type,
+                  domain:              @domain,
+                  activation:          @activation,
+                  original_activation: @original_activation,
+                  influence_target:    @influence_target,
+                  influence_count:     @influence_count,
+                  influence_magnitude: influence_magnitude,
+                  near_threshold:      near_threshold?,
+                  active:              active?,
+                  extinct:             extinct?,
+                  activation_label:    activation_label,
+                  persistence:         persistence,
+                  created_at:          @created_at.iso8601
+                }
+              end
+
+              private
+
+              def valid_trace_type(type)
+                sym = type.to_sym
+                TRACE_TYPES.include?(sym) ? sym : :associative
+              end
+
+              def valid_influence_target(target)
+                sym = target.to_sym
+                INFLUENCE_TARGETS.include?(sym) ? sym : :attention
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Subliminal
+          module Runners
+            module Subliminal
+              include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+              def create_subliminal_trace(content:, trace_type: :associative, domain: :general, activation: nil,
+                                          influence_target: :attention, engine: nil, **)
+                eng = engine || @default_engine
+                trace = eng.create_trace(content: content, trace_type: trace_type, domain: domain,
+                                         activation: activation || Helpers::Constants::DEFAULT_ACTIVATION,
+                                         influence_target: influence_target)
+                { success: true, trace: trace.to_h }
+              end
+
+              def boost_trace(trace_id:, amount: nil, engine: nil, **)
+                eng = engine || @default_engine
+                trace = eng.boost_trace(trace_id: trace_id, amount: amount || Helpers::Constants::ACTIVATION_BOOST)
+                return { success: false, error: 'trace not found' } unless trace
+
+                { success: true, trace: trace.to_h }
+              end
+
+              def process_influences(engine: nil, **)
+                eng = engine || @default_engine
+                result = eng.process_influences!
+                { success: true, **result }
+              end
+
+              def decay_all(engine: nil, **)
+                eng = engine || @default_engine
+                result = eng.decay_all!
+                { success: true, **result }
+              end
+
+              def active_traces(engine: nil, **)
+                eng = engine || @default_engine
+                traces = eng.active_traces
+                { success: true, count: traces.size, traces: traces.map(&:to_h) }
+              end
+
+              def near_threshold(engine: nil, **)
+                eng = engine || @default_engine
+                traces = eng.near_threshold_traces
+                { success: true, count: traces.size, traces: traces.map(&:to_h) }
+              end
+
+              def influence_on(target:, engine: nil, **)
+                eng = engine || @default_engine
+                level = eng.influence_on(target: target)
+                label = Helpers::Constants.label_for(Helpers::Constants::INFLUENCE_LABELS, level)
+                { success: true, target: target, influence: level, label: label }
+              end
+
+              def subliminal_status(engine: nil, **)
+                eng = engine || @default_engine
+                report = eng.subliminal_report
+                { success: true, **report }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'subliminal/version'
+require_relative 'subliminal/helpers/constants'
+require_relative 'subliminal/helpers/subliminal_trace'
+require_relative 'subliminal/helpers/influence_event'
+require_relative 'subliminal/helpers/subliminal_engine'
+require_relative 'subliminal/runners/subliminal'
+require_relative 'subliminal/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Subliminal
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Surprise
+          class Client
+            include Runners::Surprise
+
+            attr_reader :store, :habituation_model
+
+            def initialize(store: nil, habituation_model: nil, **)
+              @store             = store || Helpers::SurpriseStore.new
+              @habituation_model = habituation_model || Helpers::HabituationModel.new
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Surprise
+          module Helpers
+            module Constants
+              SURPRISE_THRESHOLD = 0.4
+
+              HABITUATION_RATE = 0.05
+
+              SENSITIZATION_RATE = 0.02
+
+              SURPRISE_DECAY = 0.1
+
+              MAX_SURPRISE_HISTORY = 200
+
+              SURPRISE_ALPHA = 0.15
+
+              VALENCE_WEIGHTS = { positive: 0.6, negative: 1.0, neutral: 0.3 }.freeze
+
+              DOMAIN_HABITUATION_FLOOR = 0.1
+
+              MAX_DOMAINS = 50
+
+              ORIENTING_COOLDOWN = 3
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/surprise/helpers/habituation_model.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Surprise
+          module Helpers
+            class HabituationModel
+              def initialize
+                @levels = {}
+              end
+
+              def sensitivity_for(domain)
+                @levels.fetch(domain, 1.0)
+              end
+
+              def habituate(domain)
+                current = sensitivity_for(domain)
+                floor   = Constants::DOMAIN_HABITUATION_FLOOR
+                updated = [current - Constants::HABITUATION_RATE, floor].max
+                @levels[domain] = updated
+                enforce_domain_limit
+                updated
+              end
+
+              def sensitize(domain)
+                current = sensitivity_for(domain)
+                updated = [current + Constants::SENSITIZATION_RATE, 1.0].min
+                @levels[domain] = updated
+                updated
+              end
+
+              def decay_all
+                @levels.each_key do |domain|
+                  current = @levels[domain]
+                  @levels[domain] = [current + (Constants::SENSITIZATION_RATE * 0.5), 1.0].min
+                end
+              end
+
+              def to_h
+                {
+                  domains:       @levels.size,
+                  sensitivities: @levels.transform_values { |v| v.round(4) }
+                }
+              end
+
+              private
+
+              def enforce_domain_limit
+                return unless @levels.size > Constants::MAX_DOMAINS
+
+                oldest_key = @levels.keys.first
+                @levels.delete(oldest_key)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/surprise/helpers/surprise_event.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Surprise
+          module Helpers
+            class SurpriseEvent
+              attr_reader :id, :domain, :predicted, :actual, :magnitude, :valence, :timestamp, :orienting
+
+              def initialize(domain:, predicted:, actual:, magnitude:, valence:, orienting: false)
+                @id        = SecureRandom.uuid
+                @domain    = domain
+                @predicted = predicted
+                @actual    = actual
+                @magnitude = magnitude.clamp(0.0, 1.0)
+                @valence   = valence
+                @orienting = orienting
+                @timestamp = Time.now.utc
+              end
+
+              def to_h
+                {
+                  id:        @id,
+                  domain:    @domain,
+                  predicted: @predicted,
+                  actual:    @actual,
+                  magnitude: @magnitude.round(4),
+                  valence:   @valence,
+                  orienting: @orienting,
+                  timestamp: @timestamp
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/surprise/helpers/surprise_store.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Surprise
+          module Helpers
+            class SurpriseStore
+              attr_reader :events
+
+              def initialize
+                @events    = []
+                @baselines = {}
+              end
+
+              def record(event)
+                @events << event
+                update_baseline(event.domain, event.magnitude)
+                trim
+                event
+              end
+
+              def recent(count = 10)
+                @events.last(count)
+              end
+
+              def by_domain(domain)
+                @events.select { |e| e.domain == domain }
+              end
+
+              def most_surprising(count = 5)
+                @events.sort_by { |e| -e.magnitude }.first(count)
+              end
+
+              def baseline_for(domain)
+                @baselines.fetch(domain, 0.0)
+              end
+
+              def to_h
+                total    = @events.size
+                domains  = @events.map(&:domain).uniq
+                avg_mag  = total.positive? ? (@events.sum(&:magnitude) / total).round(4) : 0.0
+                top      = most_surprising(1).first
+
+                {
+                  total_events:           total,
+                  domain_count:           domains.size,
+                  average_magnitude:      avg_mag,
+                  most_surprising_domain: top&.domain,
+                  baselines:              @baselines.transform_values { |v| v.round(4) }
+                }
+              end
+
+              private
+
+              def update_baseline(domain, magnitude)
+                prior = @baselines.fetch(domain, magnitude)
+                alpha = Constants::SURPRISE_ALPHA
+                @baselines[domain] = ((1 - alpha) * prior) + (alpha * magnitude)
+              end
+
+              def trim
+                return unless @events.size > Constants::MAX_SURPRISE_HISTORY
+
+                @events.shift(@events.size - Constants::MAX_SURPRISE_HISTORY)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end