lex-expectation-violation 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 36d95c00c9874f88a704e09c66272d6c53d15f0ef0dba263d96bdb4c89aca09d
+  data.tar.gz: fe5b4796fb94a4f90b01cbb2568f6819ddf49f5e0cc0f1841473cf9f340c6c0d
+SHA512:
+  metadata.gz: 24e930f5b5beec88c7e8c6356f897c0444fc121dac4f84d6d714606e48de5869901222ca1b6125ec45a69206cd15c31e519a20615e4cde12cf3c3515a68bc758
+  data.tar.gz: 060b4374e7d6d3df5089bd01c6fd3fa0972c7d65edb26895d0040138a8e6a1b11fd4e854da1ad9049c8efaef85a7c2806d6da619116cf45379f44d68da5277de

data/README.md

@@ -0,0 +1,56 @@
+# lex-expectation-violation
+
+Expectation violation modeling for the LegionIO brain-modeled cognitive architecture.
+
+## What It Does
+
+Detects and processes mismatches between what the agent predicts and what actually happens. Computes violation magnitude, classifies violations as positive surprise, negative surprise, schema mismatch, or neutral, and selects adaptive responses: belief updating, heightened attention, or curiosity-driven exploration. The attention boost from significant violations ensures unexpected events receive more processing.
+
+Based on predictive processing theory (Clark, Friston) and violation of expectation research.
+
+## Usage
+
+```ruby
+client = Legion::Extensions::ExpectationViolation::Client.new
+
+# Register an expectation before acting
+client.register_expectation(
+  domain: :networking,
+  predicted: :success,
+  confidence: 0.85
+)
+# => { success: true, expectation_id: "...", domain: :networking }
+
+# Check the expectation after observing the outcome
+client.check_expectation(expectation_id: '...', actual: :timeout)
+# => { success: true, violation_detected: true, magnitude: 0.85,
+#      violation_type: :negative_surprise, response_mode: :update_belief,
+#      surprise_label: :surprising }
+
+# Process the violation (executes the response mode)
+client.process_violation(violation_id: '...')
+# => { processed: true, belief_updated: true, attention_boost: 0.25, exploration_triggered: false }
+
+# Check current attention level
+client.attention_level
+# => { attention: 0.7, attention_label: :alert, heightened: true }
+
+# Expectation accuracy over a domain
+client.expectation_accuracy(domain: :networking)
+# => { accuracy_rate: 0.72, total_checked: 25, violations_count: 7 }
+
+# Periodic maintenance
+client.update_expectation_violation
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lib/legion/extensions/expectation_violation/helpers/client.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module ExpectationViolation
+      module Helpers
+        class Client
+          include Runners::ExpectationViolation
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module ExpectationViolation
+      module Helpers
+        module Constants
+          VIOLATION_TYPES = %i[positive negative neutral].freeze
+
+          VIOLATION_LABELS = {
+            (0.8..)       => :extreme_positive,
+            (0.3...0.8)   => :positive,
+            (-0.3...0.3)  => :neutral,
+            (-0.8...-0.3) => :negative,
+            (..-0.8)      => :extreme_negative
+          }.freeze
+
+          AROUSAL_LABELS = {
+            (0.8..)     => :highly_aroused,
+            (0.6...0.8) => :aroused,
+            (0.4...0.6) => :moderate,
+            (0.2...0.4) => :calm,
+            (..0.2)     => :unaffected
+          }.freeze
+
+          MAX_EXPECTATIONS = 200
+          MAX_VIOLATIONS   = 500
+          MAX_HISTORY      = 500
+
+          DEFAULT_EXPECTATION = 0.5
+          EXPECTATION_FLOOR   = 0.0
+          EXPECTATION_CEILING = 1.0
+
+          AROUSAL_BASE = 0.3
+          AROUSAL_MULTIPLIER = 0.7
+
+          ADAPTATION_RATE = 0.1
+          DECAY_RATE      = 0.02
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/expectation_violation/helpers/expectation.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module ExpectationViolation
+      module Helpers
+        class Expectation
+          include Constants
+
+          attr_reader :id, :context, :domain, :expected_value, :tolerance,
+                      :violation_count, :adaptation_count, :created_at
+
+          def initialize(context:, domain:, expected_value: DEFAULT_EXPECTATION, tolerance: 0.2)
+            @id               = SecureRandom.uuid
+            @context          = context
+            @domain           = domain
+            @expected_value   = expected_value.clamp(EXPECTATION_FLOOR, EXPECTATION_CEILING)
+            @tolerance        = tolerance.clamp(0.01, 0.5)
+            @violation_count  = 0
+            @adaptation_count = 0
+            @created_at       = Time.now.utc
+          end
+
+          def evaluate(actual_value:)
+            deviation = actual_value - @expected_value
+            violated = deviation.abs > @tolerance
+
+            if violated
+              @violation_count += 1
+              arousal = compute_arousal(deviation)
+              violation_type = deviation.positive? ? :positive : :negative
+              { violated: true, deviation: deviation.round(3), type: violation_type,
+                arousal: arousal.round(3), arousal_label: arousal_label(arousal) }
+            else
+              { violated: false, deviation: deviation.round(3), type: :neutral,
+                arousal: 0.0, arousal_label: :unaffected }
+            end
+          end
+
+          def adapt!(actual_value:)
+            @expected_value += (actual_value - @expected_value) * ADAPTATION_RATE
+            @expected_value = @expected_value.clamp(EXPECTATION_FLOOR, EXPECTATION_CEILING)
+            @adaptation_count += 1
+          end
+
+          def violation_label(deviation)
+            VIOLATION_LABELS.find { |range, _| range.cover?(deviation) }&.last || :neutral
+          end
+
+          def to_h
+            {
+              id:               @id,
+              context:          @context,
+              domain:           @domain,
+              expected_value:   @expected_value.round(3),
+              tolerance:        @tolerance,
+              violation_count:  @violation_count,
+              adaptation_count: @adaptation_count,
+              created_at:       @created_at
+            }
+          end
+
+          private
+
+          def compute_arousal(deviation)
+            (AROUSAL_BASE + (deviation.abs * AROUSAL_MULTIPLIER)).clamp(0.0, 1.0)
+          end
+
+          def arousal_label(arousal)
+            AROUSAL_LABELS.find { |range, _| range.cover?(arousal) }&.last || :moderate
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/expectation_violation/helpers/violation_engine.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module ExpectationViolation
+      module Helpers
+        class ViolationEngine
+          include Constants
+
+          attr_reader :history
+
+          def initialize
+            @expectations = {}
+            @violations   = []
+            @history      = []
+          end
+
+          def create_expectation(context:, domain:, expected_value: DEFAULT_EXPECTATION, tolerance: 0.2)
+            evict_oldest if @expectations.size >= MAX_EXPECTATIONS
+
+            expectation = Expectation.new(
+              context:        context,
+              domain:         domain,
+              expected_value: expected_value,
+              tolerance:      tolerance
+            )
+            @expectations[expectation.id] = expectation
+            record_history(:created, expectation.id)
+            expectation
+          end
+
+          def evaluate_against(expectation_id:, actual_value:)
+            expectation = @expectations[expectation_id]
+            return { success: false, reason: :not_found } unless expectation
+
+            result = expectation.evaluate(actual_value: actual_value)
+
+            if result[:violated]
+              @violations << {
+                expectation_id: expectation_id,
+                type:           result[:type],
+                deviation:      result[:deviation],
+                arousal:        result[:arousal],
+                at:             Time.now.utc
+              }
+              trim_violations
+            end
+
+            record_history(:evaluated, expectation_id)
+            { success: true }.merge(result)
+          end
+
+          def adapt_expectation(expectation_id:, actual_value:)
+            expectation = @expectations[expectation_id]
+            return { success: false, reason: :not_found } unless expectation
+
+            expectation.adapt!(actual_value: actual_value)
+            record_history(:adapted, expectation_id)
+            { success: true, new_expected: expectation.expected_value.round(3) }
+          end
+
+          def recent_violations(limit: 10)
+            @violations.last(limit)
+          end
+
+          def violations_by_type(type:)
+            @violations.select { |vio| vio[:type] == type }
+          end
+
+          def expectations_by_domain(domain:)
+            @expectations.values.select { |exp| exp.domain == domain }
+          end
+
+          def most_violated(limit: 5)
+            @expectations.values.sort_by { |exp| -exp.violation_count }.first(limit)
+          end
+
+          def violation_rate
+            total = @expectations.values.sum(&:violation_count)
+            evals = @history.count { |entry| entry[:event] == :evaluated }
+            return 0.0 if evals.zero?
+
+            (total.to_f / evals).round(3)
+          end
+
+          def positive_violation_ratio
+            return 0.0 if @violations.empty?
+
+            positive = @violations.count { |vio| vio[:type] == :positive }
+            (positive.to_f / @violations.size).round(3)
+          end
+
+          def to_h
+            {
+              total_expectations: @expectations.size,
+              total_violations:   @violations.size,
+              violation_rate:     violation_rate,
+              positive_ratio:     positive_violation_ratio,
+              history_count:      @history.size
+            }
+          end
+
+          private
+
+          def evict_oldest
+            oldest_id = @expectations.min_by { |_id, exp| exp.created_at }&.first
+            @expectations.delete(oldest_id) if oldest_id
+          end
+
+          def trim_violations
+            @violations.shift while @violations.size > MAX_VIOLATIONS
+          end
+
+          def record_history(event, expectation_id)
+            @history << { event: event, expectation_id: expectation_id, at: Time.now.utc }
+            @history.shift while @history.size > MAX_HISTORY
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module ExpectationViolation
+      module Runners
+        module ExpectationViolation
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def create_expectation(context:, domain:, expected_value: nil, tolerance: 0.2, **)
+            exp = engine.create_expectation(
+              context:        context,
+              domain:         domain.to_sym,
+              expected_value: expected_value || Helpers::Constants::DEFAULT_EXPECTATION,
+              tolerance:      tolerance
+            )
+            Legion::Logging.debug "[expectation_violation] create id=#{exp.id[0..7]} " \
+                                  "ctx=#{context} expected=#{exp.expected_value}"
+            { success: true, expectation: exp.to_h }
+          end
+
+          def evaluate_expectation(expectation_id:, actual_value:, **)
+            result = engine.evaluate_against(expectation_id: expectation_id, actual_value: actual_value)
+            Legion::Logging.debug "[expectation_violation] evaluate id=#{expectation_id[0..7]} " \
+                                  "violated=#{result[:violated]} type=#{result[:type]}"
+            result
+          end
+
+          def adapt_expectation_value(expectation_id:, actual_value:, **)
+            result = engine.adapt_expectation(expectation_id: expectation_id, actual_value: actual_value)
+            Legion::Logging.debug "[expectation_violation] adapt id=#{expectation_id[0..7]} " \
+                                  "new=#{result[:new_expected]}"
+            result
+          end
+
+          def recent_violations_report(limit: 10, **)
+            violations = engine.recent_violations(limit: limit)
+            Legion::Logging.debug "[expectation_violation] recent count=#{violations.size}"
+            { success: true, violations: violations, count: violations.size }
+          end
+
+          def violations_by_type_report(type:, **)
+            violations = engine.violations_by_type(type: type.to_sym)
+            Legion::Logging.debug '[expectation_violation] by_type ' \
+                                  "type=#{type} count=#{violations.size}"
+            { success: true, violations: violations, count: violations.size }
+          end
+
+          def most_violated_expectations(limit: 5, **)
+            exps = engine.most_violated(limit: limit)
+            Legion::Logging.debug "[expectation_violation] most_violated count=#{exps.size}"
+            { success: true, expectations: exps.map(&:to_h), count: exps.size }
+          end
+
+          def expectation_violation_stats(**)
+            stats = engine.to_h
+            Legion::Logging.debug '[expectation_violation] stats ' \
+                                  "total=#{stats[:total_expectations]}"
+            { success: true }.merge(stats)
+          end
+
+          private
+
+          def engine
+            @engine ||= Helpers::ViolationEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/expectation_violation.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'expectation_violation/version'
+require_relative 'expectation_violation/helpers/constants'
+require_relative 'expectation_violation/helpers/expectation'
+require_relative 'expectation_violation/helpers/violation_engine'
+require_relative 'expectation_violation/runners/expectation_violation'
+require_relative 'expectation_violation/helpers/client'
+
+module Legion
+  module Extensions
+    module ExpectationViolation
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined?(:Core)
+    end
+  end
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: lex-expectation-violation
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Esity
+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: Models expectations with tolerance bands and detects violations. Positive
+  violations strengthen trust, negative violations damage it. Based on Burgoon (1978)
+  Expectancy Violations Theory.
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/legion/extensions/expectation_violation.rb
+- lib/legion/extensions/expectation_violation/helpers/client.rb
+- lib/legion/extensions/expectation_violation/helpers/constants.rb
+- lib/legion/extensions/expectation_violation/helpers/expectation.rb
+- lib/legion/extensions/expectation_violation/helpers/violation_engine.rb
+- lib/legion/extensions/expectation_violation/runners/expectation_violation.rb
+- lib/legion/extensions/expectation_violation/version.rb
+homepage: https://github.com/LegionIO/lex-expectation-violation
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-expectation-violation
+  source_code_uri: https://github.com/LegionIO/lex-expectation-violation
+  documentation_uri: https://github.com/LegionIO/lex-expectation-violation
+  changelog_uri: https://github.com/LegionIO/lex-expectation-violation/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/LegionIO/lex-expectation-violation/issues
+  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: Expectancy violation theory for LegionIO
+test_files: []