lex-agentic-attention 0.1.0

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

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Surprise
+          module Runners
+            module Surprise
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              # Evaluate a single prediction-outcome pair and compute surprise magnitude.
+              # magnitude = |predicted - actual| * sensitivity * valence_weight, clamped to [0,1]
+              def evaluate_surprise(domain:, predicted:, actual:, valence: :neutral, **)
+                sensitivity = habituation_model.sensitivity_for(domain)
+                valence_weight = Helpers::Constants::VALENCE_WEIGHTS.fetch(valence, 0.3)
+                raw_diff       = (predicted.to_f - actual.to_f).abs
+                magnitude      = (raw_diff * sensitivity * valence_weight).clamp(0.0, 1.0)
+
+                threshold    = Helpers::Constants::SURPRISE_THRESHOLD
+                orienting    = should_orient?(domain, magnitude, threshold)
+
+                event = Helpers::SurpriseEvent.new(
+                  domain:    domain,
+                  predicted: predicted,
+                  actual:    actual,
+                  magnitude: magnitude,
+                  valence:   valence,
+                  orienting: orienting
+                )
+
+                store.record(event)
+                habituation_model.habituate(domain)
+
+                if orienting
+                  record_cooldown(domain)
+                  Legion::Logging.debug "[surprise] orienting response triggered: domain=#{domain} magnitude=#{magnitude.round(3)}"
+                else
+                  Legion::Logging.debug "[surprise] surprise recorded: domain=#{domain} magnitude=#{magnitude.round(3)} orienting=false"
+                end
+
+                { success: true, surprise_event: event.to_h, orienting_triggered: orienting }
+              end
+
+              # Per-tick update: extract domain predictions from tick_result, compute surprise for each,
+              # decay the store's baseline tracking, and return a summary.
+              def update_surprise(tick_result: {}, **)
+                predictions = extract_predictions(tick_result)
+                events      = []
+
+                predictions.each do |pred|
+                  next unless pred[:domain] && !pred[:predicted].nil? && !pred[:actual].nil?
+
+                  result = evaluate_surprise(
+                    domain:    pred[:domain],
+                    predicted: pred[:predicted],
+                    actual:    pred[:actual],
+                    valence:   pred.fetch(:valence, :neutral)
+                  )
+                  events << result[:surprise_event] if result[:success]
+                end
+
+                habituation_model.decay_all
+                tick_cooldowns
+
+                orienting_count = events.count { |e| e[:orienting] }
+                Legion::Logging.debug "[surprise] tick update: evaluated=#{events.size} orienting=#{orienting_count}"
+
+                {
+                  success:         true,
+                  evaluated:       events.size,
+                  orienting_count: orienting_count,
+                  events:          events
+                }
+              end
+
+              def surprise_stats(**)
+                stats   = store.to_h
+                top     = store.most_surprising(1).first
+                avg_mag = stats[:average_magnitude]
+
+                Legion::Logging.debug "[surprise] stats: total=#{stats[:total_events]} domains=#{stats[:domain_count]}"
+
+                {
+                  success:                true,
+                  total_events:           stats[:total_events],
+                  domain_count:           stats[:domain_count],
+                  average_magnitude:      avg_mag,
+                  most_surprising_domain: stats[:most_surprising_domain],
+                  top_surprise_magnitude: top&.magnitude&.round(4)
+                }
+              end
+
+              def domain_sensitivity(domain:, **)
+                sensitivity = habituation_model.sensitivity_for(domain)
+                baseline    = store.baseline_for(domain)
+                domain_events = store.by_domain(domain)
+
+                Legion::Logging.debug "[surprise] domain_sensitivity: domain=#{domain} sensitivity=#{sensitivity.round(3)}"
+
+                {
+                  success:     true,
+                  domain:      domain,
+                  sensitivity: sensitivity.round(4),
+                  baseline:    baseline.round(4),
+                  event_count: domain_events.size
+                }
+              end
+
+              def recent_surprises(count: 10, **)
+                events = store.recent(count)
+                Legion::Logging.debug "[surprise] recent_surprises: count=#{events.size}"
+                { success: true, events: events.map(&:to_h), count: events.size }
+              end
+
+              def reset_habituation(domain:, **)
+                old_sensitivity = habituation_model.sensitivity_for(domain)
+                # Sensitize repeatedly to push back toward 1.0
+                steps = ((1.0 - old_sensitivity) / Helpers::Constants::SENSITIZATION_RATE).ceil
+                steps.times { habituation_model.sensitize(domain) }
+                new_sensitivity = habituation_model.sensitivity_for(domain)
+
+                Legion::Logging.debug "[surprise] reset_habituation: domain=#{domain} #{old_sensitivity.round(3)} -> #{new_sensitivity.round(3)}"
+
+                { success: true, domain: domain, old_sensitivity: old_sensitivity.round(4), new_sensitivity: new_sensitivity.round(4) }
+              end
+
+              private
+
+              def store
+                @store ||= Helpers::SurpriseStore.new
+              end
+
+              def habituation_model
+                @habituation_model ||= Helpers::HabituationModel.new
+              end
+
+              def cooldowns
+                @cooldowns ||= {}
+              end
+
+              def tick_cooldowns
+                cooldowns.each_key { |domain| cooldowns[domain] -= 1 }
+                cooldowns.reject! { |_, ticks_left| ticks_left <= 0 }
+              end
+
+              def record_cooldown(domain)
+                cooldowns[domain] = Helpers::Constants::ORIENTING_COOLDOWN
+              end
+
+              def on_cooldown?(domain)
+                (cooldowns[domain] || 0).positive?
+              end
+
+              def should_orient?(domain, magnitude, threshold)
+                return false if magnitude < threshold
+                return false if on_cooldown?(domain)
+
+                true
+              end
+
+              def extract_predictions(tick_result)
+                return [] unless tick_result.is_a?(Hash)
+
+                tick_result.fetch(:predictions, [])
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'surprise/version'
+require_relative 'surprise/helpers/constants'
+require_relative 'surprise/helpers/surprise_event'
+require_relative 'surprise/helpers/habituation_model'
+require_relative 'surprise/helpers/surprise_store'
+require_relative 'surprise/runners/surprise'
+require_relative 'surprise/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Surprise
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Switching
+          class Client
+            include Runners::AttentionSwitching
+
+            def initialize(engine: nil)
+              @default_engine = engine || Helpers::SwitchingEngine.new
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Switching
+          module Helpers
+            module Constants
+              # Limits
+              MAX_TASK_SETS = 100
+              MAX_SWITCH_EVENTS = 500
+
+              # Switch dynamics
+              DEFAULT_SWITCH_COST = 0.3
+              RESIDUAL_DECAY_RATE = 0.1
+              WARMUP_RATE = 0.15
+              CONTEXT_RESTORATION_COST = 0.2
+              PRACTICE_REDUCTION = 0.01
+
+              # Thresholds
+              HIGH_COST_THRESHOLD = 0.6
+              LOW_COST_THRESHOLD = 0.2
+              READY_THRESHOLD = 0.8
+
+              # Task set types
+              TASK_SET_TYPES = %i[
+                analytical creative social procedural
+                perceptual linguistic spatial emotional
+              ].freeze
+
+              # Switch cost labels
+              COST_LABELS = {
+                (0.8..)     => :prohibitive,
+                (0.6...0.8) => :high,
+                (0.4...0.6) => :moderate,
+                (0.2...0.4) => :low,
+                (..0.2)     => :negligible
+              }.freeze
+
+              # Readiness labels
+              READINESS_LABELS = {
+                (0.8..)     => :fully_ready,
+                (0.6...0.8) => :mostly_ready,
+                (0.4...0.6) => :warming_up,
+                (0.2...0.4) => :loading,
+                (..0.2)     => :unprepared
+              }.freeze
+
+              # Residual activation labels
+              RESIDUAL_LABELS = {
+                (0.8..)     => :overwhelming,
+                (0.6...0.8) => :strong,
+                (0.4...0.6) => :moderate,
+                (0.2...0.4) => :fading,
+                (..0.2)     => :negligible
+              }.freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/switching/helpers/switch_event.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Switching
+          module Helpers
+            class SwitchEvent
+              include Constants
+
+              attr_reader :id, :from_task_id, :to_task_id, :switch_cost,
+                          :residual_interference, :warmup_needed, :created_at
+
+              def initialize(from_task_id:, to_task_id:, switch_cost:, residual_interference:, warmup_needed:)
+                @id                    = SecureRandom.uuid
+                @from_task_id          = from_task_id
+                @to_task_id            = to_task_id
+                @switch_cost           = switch_cost.to_f.clamp(0.0, 1.0).round(10)
+                @residual_interference = residual_interference.to_f.clamp(0.0, 1.0).round(10)
+                @warmup_needed         = warmup_needed.to_f.clamp(0.0, 1.0).round(10)
+                @created_at            = Time.now.utc
+              end
+
+              def costly?
+                @switch_cost >= HIGH_COST_THRESHOLD
+              end
+
+              def cheap?
+                @switch_cost <= LOW_COST_THRESHOLD
+              end
+
+              def cost_label
+                match = COST_LABELS.find { |range, _| range.cover?(@switch_cost) }
+                match ? match.last : :negligible
+              end
+
+              def to_h
+                {
+                  id:                    @id,
+                  from_task_id:          @from_task_id,
+                  to_task_id:            @to_task_id,
+                  switch_cost:           @switch_cost,
+                  cost_label:            cost_label,
+                  costly:                costly?,
+                  cheap:                 cheap?,
+                  residual_interference: @residual_interference,
+                  warmup_needed:         @warmup_needed,
+                  created_at:            @created_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/switching/helpers/switching_engine.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Switching
+          module Helpers
+            class SwitchingEngine
+              include Constants
+
+              def initialize
+                @task_sets      = {}
+                @switch_events  = []
+                @active_task_id = nil
+              end
+
+              def register_task(name:, task_type: :analytical, complexity: 0.5)
+                prune_tasks_if_needed
+                task = TaskSet.new(name: name, task_type: task_type, complexity: complexity)
+                @task_sets[task.id] = task
+                task
+              end
+
+              def activate_task(task_id:)
+                task = @task_sets[task_id]
+                return nil unless task
+
+                task.activate!
+                @active_task_id = task_id
+                task
+              end
+
+              def switch_to(task_id:)
+                target = @task_sets[task_id]
+                return nil unless target
+
+                current = @task_sets[@active_task_id]
+                event = if current && @active_task_id != task_id
+                          perform_switch(current, target)
+                        else
+                          activate_task(task_id: task_id)
+                          nil
+                        end
+
+                @active_task_id = task_id
+                { task: target.to_h, switch_event: event&.to_h }
+              end
+
+              def warmup_active
+                task = @task_sets[@active_task_id]
+                return nil unless task
+
+                task.warmup!
+              end
+
+              def decay_all_residuals!
+                @task_sets.each_value(&:decay_residual!)
+                { tasks_decayed: @task_sets.size }
+              end
+
+              def active_task
+                @task_sets[@active_task_id]
+              end
+
+              def tasks_with_residual
+                @task_sets.values.select(&:residual?)
+              end
+
+              def recent_switches(limit: 10)
+                @switch_events.last(limit)
+              end
+
+              def average_switch_cost
+                return DEFAULT_SWITCH_COST if @switch_events.empty?
+
+                costs = @switch_events.map(&:switch_cost)
+                (costs.sum / costs.size).round(10)
+              end
+
+              def costly_switches
+                @switch_events.select(&:costly?)
+              end
+
+              def cheap_switches
+                @switch_events.select(&:cheap?)
+              end
+
+              def switch_cost_between(from_id:, to_id:)
+                relevant = @switch_events.select { |e| e.from_task_id == from_id && e.to_task_id == to_id }
+                return nil if relevant.empty?
+
+                costs = relevant.map(&:switch_cost)
+                (costs.sum / costs.size).round(10)
+              end
+
+              def most_costly_pair
+                return nil if @switch_events.empty?
+
+                @switch_events.max_by(&:switch_cost)
+              end
+
+              def switching_report
+                {
+                  total_tasks:         @task_sets.size,
+                  total_switches:      @switch_events.size,
+                  active_task:         active_task&.to_h,
+                  average_switch_cost: average_switch_cost,
+                  costly_count:        costly_switches.size,
+                  cheap_count:         cheap_switches.size,
+                  residual_count:      tasks_with_residual.size,
+                  recent_switches:     recent_switches(limit: 5).map(&:to_h)
+                }
+              end
+
+              def to_h
+                {
+                  total_tasks:         @task_sets.size,
+                  total_switches:      @switch_events.size,
+                  active_task_id:      @active_task_id,
+                  average_switch_cost: average_switch_cost,
+                  residual_count:      tasks_with_residual.size
+                }
+              end
+
+              private
+
+              def perform_switch(current, target)
+                current.deactivate!
+                cost = compute_switch_cost(current, target)
+                warmup = ((1.0 - target.readiness) * target.complexity).round(10)
+                target.activate!
+
+                event = SwitchEvent.new(
+                  from_task_id:          current.id,
+                  to_task_id:            target.id,
+                  switch_cost:           cost,
+                  residual_interference: current.residual_activation,
+                  warmup_needed:         warmup
+                )
+                prune_events_if_needed
+                @switch_events << event
+                event
+              end
+
+              def compute_switch_cost(current, target)
+                type_cost = current.task_type == target.task_type ? 0.0 : 0.15
+                complexity_cost = ((current.complexity - target.complexity).abs * 0.3).round(10)
+                context_cost = CONTEXT_RESTORATION_COST * target.complexity
+                practice_bonus = [target.activation_count * PRACTICE_REDUCTION, 0.2].min
+
+                (DEFAULT_SWITCH_COST + type_cost + complexity_cost +
+                 (current.residual_activation * 0.2) + context_cost - practice_bonus).clamp(0.0, 1.0).round(10)
+              end
+
+              def prune_tasks_if_needed
+                return if @task_sets.size < MAX_TASK_SETS
+
+                least_used = @task_sets.values.min_by(&:activation_count)
+                @task_sets.delete(least_used.id) if least_used
+              end
+
+              def prune_events_if_needed
+                @switch_events.shift while @switch_events.size >= MAX_SWITCH_EVENTS
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/switching/helpers/task_set.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Switching
+          module Helpers
+            class TaskSet
+              include Constants
+
+              attr_reader :id, :name, :task_type, :complexity, :readiness,
+                          :residual_activation, :activation_count, :created_at
+
+              def initialize(name:, task_type: :analytical, complexity: 0.5)
+                @id                  = SecureRandom.uuid
+                @name                = name.to_s
+                @task_type           = task_type.to_sym
+                @complexity          = complexity.to_f.clamp(0.0, 1.0).round(10)
+                @readiness           = 0.0
+                @residual_activation = 0.0
+                @activation_count    = 0
+                @created_at          = Time.now.utc
+              end
+
+              def activate!
+                @readiness = 1.0
+                @residual_activation = 0.0
+                @activation_count += 1
+                self
+              end
+
+              def deactivate!
+                @residual_activation = @readiness
+                @readiness = 0.0
+                self
+              end
+
+              def warmup!(amount: WARMUP_RATE)
+                @readiness = (@readiness + amount).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def decay_residual!
+                @residual_activation = (@residual_activation - RESIDUAL_DECAY_RATE).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def ready?
+                @readiness >= READY_THRESHOLD
+              end
+
+              def residual?
+                @residual_activation > 0.1
+              end
+
+              def readiness_label
+                match = READINESS_LABELS.find { |range, _| range.cover?(@readiness) }
+                match ? match.last : :unprepared
+              end
+
+              def residual_label
+                match = RESIDUAL_LABELS.find { |range, _| range.cover?(@residual_activation) }
+                match ? match.last : :negligible
+              end
+
+              def to_h
+                {
+                  id:                  @id,
+                  name:                @name,
+                  task_type:           @task_type,
+                  complexity:          @complexity,
+                  readiness:           @readiness,
+                  readiness_label:     readiness_label,
+                  residual_activation: @residual_activation,
+                  residual_label:      residual_label,
+                  ready:               ready?,
+                  has_residual:        residual?,
+                  activation_count:    @activation_count,
+                  created_at:          @created_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end