lex-surprise 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 22083a1c0263ca15e137e1df847e5c4f7619a6148116adb37a3f587c9ad4a379
+  data.tar.gz: b0d6ae0f77e5574d2ea4d400c1df123e5a64f1af9e12e35b88f532b6b0658d0b
+SHA512:
+  metadata.gz: 9477cfc33f2e546dd75d6ab8bceb71f52a1c468d4555a0f914922185909a03de7fb16fe95c46ef06413aeaaac9191b67f661dd74a6b26af5e7909814380b44a1
+  data.tar.gz: 981d88fe05c424d1a2ee6fa21afd09fbf7b1a770fc93fb5f2175c33f9ca4f32ba5ccfceff918a6eef69b87bbc048ee07afd82e3869e288dfa6948057769b8c3a

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    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

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    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

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    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

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    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) # rubocop:disable Metrics/ParameterLists
+            @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

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

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    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

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

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    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

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

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

data/lib/legion/extensions/surprise.rb

@@ -0,0 +1,17 @@
+# 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 Surprise
+      extend Legion::Extensions::Core if defined?(Legion::Extensions::Core)
+    end
+  end
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: lex-surprise
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Matthew Iverson
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: legion-gaia
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Detects when reality deviates from expectations using Bayesian surprise
+  (KL divergence). Tracks habituation, generates orienting signals, and adapts sensitivity
+  per domain.
+email:
+- matt@legionIO.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/legion/extensions/surprise.rb
+- lib/legion/extensions/surprise/client.rb
+- lib/legion/extensions/surprise/helpers/constants.rb
+- lib/legion/extensions/surprise/helpers/habituation_model.rb
+- lib/legion/extensions/surprise/helpers/surprise_event.rb
+- lib/legion/extensions/surprise/helpers/surprise_store.rb
+- lib/legion/extensions/surprise/runners/surprise.rb
+- lib/legion/extensions/surprise/version.rb
+homepage: https://github.com/LegionIO/lex-surprise
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Orienting response and surprise detection for LegionIO cognitive agents
+test_files: []