lex-emotion 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 25a14df7629126e71f7e0cb1eaa60da4237f055c074bfc1709093f7601c009c5
+  data.tar.gz: c3198212e5b853f06c04add9a5d3959caf90bb38acdab7d1f595bad9dd6f933e
+SHA512:
+  metadata.gz: 07db1bffdc454beec694dd1c75bebfe411a8b7ea122a3a7cd75e67e9760a2691da49ab32eb730190e9379fa16302787e4f10ef5ef1a8e48a073f9111171ea687
+  data.tar.gz: ccf9b2503bee116f27af9d0aa64a420c7a89991d4aedeac576663c3747e187ff6d516030f9cfc6d04d70d8b2da5d8aef6c389560675003c0093fc0a89cab0b02

data/Gemfile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+gemspec
+
+group :test do
+  gem 'rake'
+  gem 'rspec'
+  gem 'rspec_junit_formatter'
+  gem 'rubocop', require: false
+  gem 'rubocop-rspec', require: false
+  gem 'simplecov'
+end
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Iverson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,123 @@
+# lex-emotion
+
+Multi-dimensional emotional valence system for brain-modeled agentic AI. Models emotional state across four dimensions, computes arousal and gut instinct signals, and modulates attention.
+
+## Overview
+
+`lex-emotion` implements the agent's affective layer. Emotional state is not a single scalar — it is a four-dimensional valence vector. Valence influences memory decay rates, attention allocation, and gut instinct signals. Momentum (exponential moving average) smooths emotional state over time.
+
+## Valence Dimensions
+
+| Dimension | Description |
+|-----------|-------------|
+| `urgency` | Time pressure and immediacy |
+| `importance` | Impact scope and outcome severity |
+| `novelty` | Degree of unexpectedness |
+| `familiarity` | How well-known the domain/source is |
+
+All dimensions are clamped to `[0.0, 1.0]`.
+
+## Source Urgency Defaults
+
+| Source Type | Urgency Weight |
+|-------------|---------------|
+| `firmware_violation` | 1.0 |
+| `human_direct` | 0.9 |
+| `mesh_priority` | 0.7 |
+| `scheduled` | 0.4 |
+| `ambient` | 0.1 |
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'lex-emotion'
+```
+
+## Usage
+
+### Evaluating Valence
+
+```ruby
+require 'legion/extensions/emotion'
+
+# Evaluate a signal's emotional valence
+result = Legion::Extensions::Emotion::Runners::Valence.evaluate_valence(
+  signal: { urgency_hint: 0.8, domain_weight: 0.9, impact_scope: 0.6,
+            reversibility: 0.2, outcome_severity: 0.8 },
+  source_type: :human_direct,
+  deadline: Time.now.utc + 3600
+)
+
+result[:valence]            # => { urgency: 0.72, importance: 0.68, novelty: 0.5, familiarity: 0.0 }
+result[:magnitude]          # => 1.09 (Euclidean norm)
+result[:dominant_dimension] # => :urgency
+```
+
+### Aggregating Multiple Valences
+
+```ruby
+valences = [
+  { urgency: 0.8, importance: 0.7, novelty: 0.4, familiarity: 0.3 },
+  { urgency: 0.5, importance: 0.9, novelty: 0.2, familiarity: 0.6 }
+]
+
+Legion::Extensions::Emotion::Runners::Valence.aggregate_valences(valences: valences)
+# => { aggregate: {...}, arousal: 0.65, dominant: :importance, count: 2 }
+```
+
+### Gut Instinct
+
+```ruby
+# Compressed parallel query — returns a signal classification
+result = Legion::Extensions::Emotion::Runners::Gut.gut_instinct(
+  valences: valences,
+  memory_signals: [1, 2, 3],
+  confidence_threshold: 0.5
+)
+
+result[:signal]     # => :alarm | :heightened | :explore | :attend | :calm | :neutral
+result[:confidence] # => 0.0..1.0
+result[:reliable]   # => true/false
+```
+
+### Current Emotional State
+
+```ruby
+Legion::Extensions::Emotion::Runners::Gut.emotional_state
+# => { momentum: { valence_ema: {...}, arousal_ema: 0.4, stability: 0.9, history_size: 5 },
+#      baseline: { urgency: {...}, ... } }
+```
+
+### Attention Modulation
+
+```ruby
+Legion::Extensions::Emotion::Runners::Valence.modulate_attention(
+  base_salience: 0.5,
+  valence: { urgency: 0.8, importance: 0.7, novelty: 0.3, familiarity: 0.5 }
+)
+# => { original: 0.5, modulated: 0.72, boost: 0.22 }
+```
+
+## Momentum
+
+Emotional momentum is an exponential moving average (alpha = 0.3) over valence and arousal. It tracks `valence_ema`, `arousal_ema`, `stability`, and last 100 data points.
+
+## Actors
+
+| Actor | Interval | Description |
+|-------|----------|-------------|
+| `MomentumDecay` | Every 60s | Periodically drifts emotional momentum toward neutral valence via exponential decay, preventing permanent extreme states |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-emotion.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/emotion/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-emotion'
+  spec.version       = Legion::Extensions::Emotion::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Emotion'
+  spec.description   = 'Multi-dimensional emotional valence for brain-modeled agentic AI'
+  spec.homepage      = 'https://github.com/LegionIO/lex-emotion'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/LegionIO/lex-emotion'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-emotion'
+  spec.metadata['changelog_uri'] = 'https://github.com/LegionIO/lex-emotion'
+  spec.metadata['bug_tracker_uri'] = 'https://github.com/LegionIO/lex-emotion/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-emotion.gemspec Gemfile LICENSE README.md]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

data/lib/legion/extensions/emotion/actors/momentum_decay.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module Emotion
+      module Actor
+        class MomentumDecay < Legion::Extensions::Actors::Every
+          def runner_class
+            Legion::Extensions::Emotion::Runners::Gut
+          end
+
+          def runner_function
+            'decay_momentum'
+          end
+
+          def time
+            60
+          end
+
+          def run_now?
+            false
+          end
+
+          def use_runner?
+            false
+          end
+
+          def check_subtask?
+            false
+          end
+
+          def generate_task?
+            false
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/emotion/helpers/valence'
+require 'legion/extensions/emotion/helpers/baseline'
+require 'legion/extensions/emotion/helpers/momentum'
+require 'legion/extensions/emotion/runners/valence'
+require 'legion/extensions/emotion/runners/gut'
+
+module Legion
+  module Extensions
+    module Emotion
+      class Client
+        include Runners::Valence
+        include Runners::Gut
+
+        def initialize(**)
+          @emotion_baseline = Helpers::Baseline.new
+          @emotion_momentum = Helpers::Momentum.new
+          @domain_counts = Hash.new(0)
+        end
+
+        def track_domain(domain)
+          @domain_counts[domain] += 1
+        end
+
+        private
+
+        attr_reader :emotion_baseline, :emotion_momentum
+      end
+    end
+  end
+end

data/lib/legion/extensions/emotion/helpers/baseline.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Emotion
+      module Helpers
+        class Baseline
+          ALPHA = 0.05       # slow adaptation to prevent adversarial manipulation
+          MIN_STDDEV = 0.1   # prevents division issues when baseline is stable
+          INITIAL_MEAN = 0.5
+          INITIAL_STDDEV = 0.25
+
+          attr_reader :dimensions
+
+          def initialize
+            @dimensions = Valence::DIMENSIONS.to_h do |dim|
+              [dim, { mean: INITIAL_MEAN, stddev: INITIAL_STDDEV, count: 0 }]
+            end
+          end
+
+          def normalize(raw_score, dimension)
+            baseline = @dimensions[dimension]
+            return Valence.clamp(raw_score) unless baseline
+
+            normalized = (raw_score - baseline[:mean]) / [baseline[:stddev], MIN_STDDEV].max
+            Valence.clamp(normalized)
+          end
+
+          def update(dimension, raw_score)
+            baseline = @dimensions[dimension]
+            return unless baseline
+
+            baseline[:count] += 1
+            old_mean = baseline[:mean]
+            baseline[:mean] = (ALPHA * raw_score) + ((1.0 - ALPHA) * old_mean)
+            # Online stddev update (Welford-like with EMA)
+            deviation = (raw_score - baseline[:mean]).abs
+            baseline[:stddev] = (ALPHA * deviation) + ((1.0 - ALPHA) * baseline[:stddev])
+          end
+
+          def get(dimension)
+            @dimensions[dimension]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/emotion/helpers/momentum.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Emotion
+      module Helpers
+        class Momentum
+          attr_reader :valence_ema, :arousal_ema, :stability, :history
+
+          def initialize
+            @valence_ema = Valence.new_valence
+            @arousal_ema = 0.0
+            @stability = 1.0
+            @history = []
+          end
+
+          def update(current_valence, current_arousal)
+            alpha = Valence::MOMENTUM_ALPHA
+
+            previous_aggregate = Valence.magnitude(@valence_ema)
+            current_aggregate = Valence.magnitude(current_valence)
+
+            @valence_ema = Valence::DIMENSIONS.to_h do |dim|
+              [dim, (alpha * current_valence[dim]) + ((1.0 - alpha) * @valence_ema[dim])]
+            end
+
+            @arousal_ema = (alpha * current_arousal) + ((1.0 - alpha) * @arousal_ema)
+            @stability = Valence.clamp(1.0 - (current_aggregate - previous_aggregate).abs)
+
+            @history << { valence: current_valence, arousal: current_arousal, timestamp: Time.now.utc }
+            @history.shift while @history.size > 100
+
+            { valence_ema: @valence_ema, arousal_ema: @arousal_ema, stability: @stability }
+          end
+
+          def emotional_state
+            {
+              valence_ema:  @valence_ema,
+              arousal_ema:  @arousal_ema,
+              stability:    @stability,
+              history_size: @history.size
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/emotion/helpers/valence.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Emotion
+      module Helpers
+        module Valence
+          DIMENSIONS = %i[urgency importance novelty familiarity].freeze
+          MAX_MAGNITUDE = Math.sqrt(4.0) # all 4 dimensions at 1.0
+
+          # Attention modulation weights (from spec Section 6.1)
+          URGENCY_ATTENTION_WEIGHT    = 0.4
+          IMPORTANCE_ATTENTION_WEIGHT = 0.35
+          NOVELTY_ATTENTION_WEIGHT    = 0.25
+          ATTENTION_MULTIPLIER        = 0.3
+
+          # Momentum
+          MOMENTUM_ALPHA = 0.3
+
+          # Source urgency map (spec Section 3.2)
+          SOURCE_URGENCY = {
+            firmware_violation: 1.0,
+            human_direct:       0.9,
+            mesh_priority:      0.7,
+            scheduled:          0.4,
+            ambient:            0.1
+          }.freeze
+
+          # Familiarity saturation (spec Section 3.5)
+          FAMILIARITY_SATURATION = 100
+
+          module_function
+
+          def new_valence(urgency: 0.0, importance: 0.0, novelty: 0.0, familiarity: 0.0)
+            {
+              urgency:     clamp(urgency),
+              importance:  clamp(importance),
+              novelty:     clamp(novelty),
+              familiarity: clamp(familiarity)
+            }
+          end
+
+          def magnitude(valence)
+            Math.sqrt(
+              (valence[:urgency]**2) +
+              (valence[:importance]**2) +
+              (valence[:novelty]**2) +
+              (valence[:familiarity]**2)
+            )
+          end
+
+          def dominant_dimension(valence)
+            DIMENSIONS.max_by { |d| valence[d] }
+          end
+
+          def aggregate(valences)
+            return new_valence if valences.empty?
+
+            sums = Hash.new(0.0)
+            valences.each do |v|
+              DIMENSIONS.each { |d| sums[d] += v[d] }
+            end
+            n = valences.size.to_f
+            new_valence(**DIMENSIONS.to_h { |d| [d, sums[d] / n] })
+          end
+
+          def compute_arousal(valences)
+            return 0.0 if valences.empty?
+
+            total = valences.sum { |v| magnitude(v) }
+            clamp(total / (valences.size * MAX_MAGNITUDE))
+          end
+
+          def modulate_salience(base_salience, valence)
+            boost = ((valence[:urgency] * URGENCY_ATTENTION_WEIGHT) +
+                     (valence[:importance] * IMPORTANCE_ATTENTION_WEIGHT) +
+                     (valence[:novelty] * NOVELTY_ATTENTION_WEIGHT)) * ATTENTION_MULTIPLIER
+            clamp(base_salience + boost)
+          end
+
+          def clamp(value, min = 0.0, max = 1.0)
+            value.clamp(min, max)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/emotion/runners/gut.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Emotion
+      module Runners
+        module Gut
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def gut_instinct(valences:, memory_signals: [], confidence_threshold: 0.5, **)
+            return { signal: :neutral, confidence: 0.0, basis: :insufficient_data } if valences.empty?
+
+            arousal = Helpers::Valence.compute_arousal(valences)
+            aggregate = Helpers::Valence.aggregate(valences)
+            dominant = Helpers::Valence.dominant_dimension(aggregate)
+
+            signal = determine_signal(aggregate, arousal)
+            confidence = compute_confidence(valences, memory_signals)
+
+            Legion::Logging.debug "[emotion] gut instinct: signal=#{signal} confidence=#{confidence.round(2)} " \
+                                  "arousal=#{arousal.round(2)} dominant=#{dominant} reliable=#{confidence >= confidence_threshold}"
+
+            result = {
+              signal:     signal,
+              confidence: confidence,
+              arousal:    arousal,
+              dominant:   dominant,
+              aggregate:  aggregate,
+              reliable:   confidence >= confidence_threshold
+            }
+
+            # Update momentum if available
+            emotion_momentum.update(aggregate, arousal) if respond_to?(:emotion_momentum, true)
+
+            result
+          end
+
+          def decay_momentum(**)
+            neutral = { urgency: 0.5, importance: 0.5, novelty: 0.5, familiarity: 0.5 }
+            momentum = emotion_momentum
+            momentum.update(neutral, 0.5)
+            stability = momentum.stability
+
+            Legion::Logging.debug "[emotion] momentum decay: stability=#{stability.round(2)}"
+
+            { decayed: true, stability: stability }
+          end
+
+          def emotional_state(**)
+            momentum = emotion_momentum
+            state = momentum.emotional_state
+            Legion::Logging.debug "[emotion] state query: stability=#{state[:stability]&.round(2)}"
+            {
+              momentum: state,
+              baseline: emotion_baseline.dimensions
+            }
+          end
+
+          private
+
+          def emotion_momentum
+            @emotion_momentum ||= Helpers::Momentum.new
+          end
+
+          def determine_signal(aggregate, arousal)
+            if aggregate[:urgency] > 0.7 && aggregate[:importance] > 0.7
+              :alarm
+            elsif arousal > 0.7
+              :heightened
+            elsif aggregate[:novelty] > 0.7 && aggregate[:familiarity] < 0.3
+              :explore
+            elsif aggregate[:importance] > 0.6
+              :attend
+            elsif arousal < 0.2
+              :calm
+            else
+              :neutral
+            end
+          end
+
+          def compute_confidence(valences, memory_signals)
+            return 0.0 if valences.empty?
+
+            magnitudes = valences.map { |v| Helpers::Valence.magnitude(v) }
+            mean_mag = magnitudes.sum / magnitudes.size
+            variance = magnitudes.sum { |m| (m - mean_mag)**2 } / magnitudes.size
+
+            consensus = Helpers::Valence.clamp(1.0 - Math.sqrt(variance))
+            evidence = Helpers::Valence.clamp(memory_signals.size / 10.0)
+
+            (consensus * 0.6) + (evidence * 0.4)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/emotion/runners/valence.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Emotion
+      module Runners
+        module Valence
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def evaluate_valence(signal:, source_type: :ambient, deadline: nil, domain: nil, **)
+            baseline = emotion_baseline
+
+            urgency_raw = compute_urgency(signal, source_type, deadline)
+            importance_raw = compute_importance(signal, domain)
+            novelty_raw = compute_novelty(signal)
+            familiarity_raw = compute_familiarity(domain)
+
+            valence = Helpers::Valence.new_valence(
+              urgency:     baseline.normalize(urgency_raw, :urgency),
+              importance:  baseline.normalize(importance_raw, :importance),
+              novelty:     baseline.normalize(novelty_raw, :novelty),
+              familiarity: baseline.normalize(familiarity_raw, :familiarity)
+            )
+
+            # Update baselines with raw scores
+            Helpers::Valence::DIMENSIONS.each do |dim|
+              raw = { urgency: urgency_raw, importance: importance_raw,
+                      novelty: novelty_raw, familiarity: familiarity_raw }[dim]
+              baseline.update(dim, raw)
+            end
+
+            magnitude = Helpers::Valence.magnitude(valence)
+            dominant = Helpers::Valence.dominant_dimension(valence)
+            Legion::Logging.debug "[emotion] valence: source=#{source_type} magnitude=#{magnitude.round(2)} dominant=#{dominant} " \
+                                  "u=#{valence[:urgency].round(2)} i=#{valence[:importance].round(2)} " \
+                                  "n=#{valence[:novelty].round(2)} f=#{valence[:familiarity].round(2)}"
+
+            {
+              valence:            valence,
+              magnitude:          magnitude,
+              dominant_dimension: dominant
+            }
+          end
+
+          def aggregate_valences(valences:, **)
+            aggregated = Helpers::Valence.aggregate(valences)
+            arousal = Helpers::Valence.compute_arousal(valences)
+            dominant = Helpers::Valence.dominant_dimension(aggregated)
+
+            Legion::Logging.debug "[emotion] aggregate: count=#{valences.size} arousal=#{arousal.round(2)} dominant=#{dominant}"
+            {
+              aggregate: aggregated,
+              arousal:   arousal,
+              dominant:  dominant,
+              count:     valences.size
+            }
+          end
+
+          def modulate_attention(base_salience:, valence:, **)
+            modulated = Helpers::Valence.modulate_salience(base_salience, valence)
+            boost = modulated - base_salience
+            Legion::Logging.debug "[emotion] attention modulation: base=#{base_salience.round(2)} modulated=#{modulated.round(2)} boost=#{boost.round(2)}"
+            { original: base_salience, modulated: modulated, boost: boost }
+          end
+
+          def compute_arousal(valences:, **)
+            arousal = Helpers::Valence.compute_arousal(valences)
+            Legion::Logging.debug "[emotion] arousal=#{arousal.round(2)} from #{valences.size} valences"
+            { arousal: arousal }
+          end
+
+          private
+
+          def emotion_baseline
+            @emotion_baseline ||= Helpers::Baseline.new
+          end
+
+          def compute_urgency(signal, source_type, deadline)
+            deadline_urgency = 0.0
+            if deadline
+              remaining = [(deadline - Time.now.utc).to_f, 0.0].max
+              max_window = 86_400.0 # 24 hours
+              deadline_urgency = Helpers::Valence.clamp(1.0 - (remaining / max_window))
+            end
+
+            source_urgency = Helpers::Valence::SOURCE_URGENCY.fetch(source_type, 0.1)
+
+            pattern_urgency = signal.is_a?(Hash) ? (signal[:urgency_hint] || 0.0) : 0.0
+
+            (deadline_urgency * 0.5) + (source_urgency * 0.3) + (pattern_urgency * 0.2)
+          end
+
+          def compute_importance(signal, _domain)
+            domain_weight = signal.is_a?(Hash) ? (signal[:domain_weight] || 0.5) : 0.5
+            impact_scope = signal.is_a?(Hash) ? (signal[:impact_scope] || 0.3) : 0.3
+            reversibility = signal.is_a?(Hash) ? (signal[:reversibility] || 0.5) : 0.5
+            outcome_severity = signal.is_a?(Hash) ? (signal[:outcome_severity] || 0.3) : 0.3
+
+            (domain_weight * 0.3) + (impact_scope * 0.2) +
+              ((1.0 - reversibility) * 0.25) + (outcome_severity * 0.25)
+          end
+
+          def compute_novelty(signal)
+            signal.is_a?(Hash) ? (signal[:novelty_score] || 0.5) : 0.5
+          end
+
+          def compute_familiarity(domain)
+            signal_count = @domain_counts&.fetch(domain, 0) || 0
+            Helpers::Valence.clamp(signal_count.to_f / Helpers::Valence::FAMILIARITY_SATURATION)
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/emotion.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/emotion/version'
+require 'legion/extensions/emotion/helpers/valence'
+require 'legion/extensions/emotion/helpers/baseline'
+require 'legion/extensions/emotion/helpers/momentum'
+require 'legion/extensions/emotion/runners/valence'
+require 'legion/extensions/emotion/runners/gut'
+
+module Legion
+  module Extensions
+    module Emotion
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

data/spec/legion/extensions/emotion/actors/momentum_decay_spec.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Stub the base class before loading the actor
+module Legion
+  module Extensions
+    module Actors
+      class Every; end # rubocop:disable Lint/EmptyClass
+    end
+  end
+end
+
+$LOADED_FEATURES << 'legion/extensions/actors/every'
+
+require_relative '../../../../../lib/legion/extensions/emotion/actors/momentum_decay'
+
+RSpec.describe Legion::Extensions::Emotion::Actor::MomentumDecay do
+  subject(:actor) { described_class.new }
+
+  describe '#runner_class' do
+    it { expect(actor.runner_class).to eq Legion::Extensions::Emotion::Runners::Gut }
+  end
+
+  describe '#runner_function' do
+    it { expect(actor.runner_function).to eq 'decay_momentum' }
+  end
+
+  describe '#time' do
+    it { expect(actor.time).to eq 60 }
+  end
+
+  describe '#run_now?' do
+    it { expect(actor.run_now?).to be false }
+  end
+
+  describe '#use_runner?' do
+    it { expect(actor.use_runner?).to be false }
+  end
+
+  describe '#check_subtask?' do
+    it { expect(actor.check_subtask?).to be false }
+  end
+
+  describe '#generate_task?' do
+    it { expect(actor.generate_task?).to be false }
+  end
+end

data/spec/legion/extensions/emotion/client_spec.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/emotion/client'
+
+RSpec.describe Legion::Extensions::Emotion::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to valence runner methods' do
+    expect(client).to respond_to(:evaluate_valence)
+    expect(client).to respond_to(:aggregate_valences)
+    expect(client).to respond_to(:modulate_attention)
+    expect(client).to respond_to(:compute_arousal)
+  end
+
+  it 'responds to gut runner methods' do
+    expect(client).to respond_to(:gut_instinct)
+    expect(client).to respond_to(:emotional_state)
+  end
+
+  it 'tracks domain counts for familiarity' do
+    client.track_domain('work')
+    client.track_domain('work')
+    client.track_domain('personal')
+    # Domain tracking improves familiarity scoring
+    result = client.evaluate_valence(signal: {}, domain: 'work')
+    expect(result[:valence][:familiarity]).to be >= 0.0
+  end
+
+  it 'round-trips a full emotional evaluation cycle' do
+    # Evaluate multiple signals
+    v1 = client.evaluate_valence(signal: { urgency_hint: 0.8 }, source_type: :human_direct)
+    v2 = client.evaluate_valence(signal: { novelty_score: 0.9 }, source_type: :ambient)
+
+    # Aggregate
+    agg = client.aggregate_valences(valences: [v1[:valence], v2[:valence]])
+    expect(agg[:count]).to eq(2)
+
+    # Gut instinct
+    gut = client.gut_instinct(valences: [v1[:valence], v2[:valence]])
+    expect(gut[:signal]).to be_a(Symbol)
+
+    # State persists
+    state = client.emotional_state
+    expect(state[:momentum][:history_size]).to be >= 1
+  end
+end

data/spec/legion/extensions/emotion/helpers/baseline_spec.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Emotion::Helpers::Baseline do
+  let(:baseline) { described_class.new }
+
+  describe '#initialize' do
+    it 'sets initial values for all dimensions' do
+      Legion::Extensions::Emotion::Helpers::Valence::DIMENSIONS.each do |dim|
+        state = baseline.get(dim)
+        expect(state[:mean]).to eq(0.5)
+        expect(state[:stddev]).to eq(0.25)
+        expect(state[:count]).to eq(0)
+      end
+    end
+  end
+
+  describe '#normalize' do
+    it 'normalizes a raw score against baseline' do
+      result = baseline.normalize(0.5, :urgency)
+      expect(result).to be_between(0.0, 1.0)
+    end
+
+    it 'returns higher value for scores above mean' do
+      low = baseline.normalize(0.3, :urgency)
+      high = baseline.normalize(0.9, :urgency)
+      expect(high).to be > low
+    end
+  end
+
+  describe '#update' do
+    it 'shifts mean toward observed values' do
+      original_mean = baseline.get(:urgency)[:mean]
+      10.times { baseline.update(:urgency, 0.9) }
+      expect(baseline.get(:urgency)[:mean]).to be > original_mean
+    end
+
+    it 'increments count' do
+      3.times { baseline.update(:importance, 0.5) }
+      expect(baseline.get(:importance)[:count]).to eq(3)
+    end
+
+    it 'adapts slowly (alpha=0.05)' do
+      baseline.update(:urgency, 1.0)
+      # After one update, mean should barely move: 0.05*1.0 + 0.95*0.5 = 0.525
+      expect(baseline.get(:urgency)[:mean]).to be_within(0.001).of(0.525)
+    end
+  end
+end

data/spec/legion/extensions/emotion/helpers/momentum_spec.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Emotion::Helpers::Momentum do
+  let(:momentum) { described_class.new }
+  let(:valence_mod) { Legion::Extensions::Emotion::Helpers::Valence }
+
+  describe '#initialize' do
+    it 'starts with zero state' do
+      state = momentum.emotional_state
+      expect(state[:arousal_ema]).to eq(0.0)
+      expect(state[:stability]).to eq(1.0)
+      expect(state[:history_size]).to eq(0)
+    end
+  end
+
+  describe '#update' do
+    it 'updates EMA toward current values' do
+      v = valence_mod.new_valence(urgency: 0.8, importance: 0.7)
+      result = momentum.update(v, 0.6)
+      expect(result[:arousal_ema]).to be > 0.0
+      expect(result[:valence_ema][:urgency]).to be > 0.0
+    end
+
+    it 'tracks history' do
+      v = valence_mod.new_valence(urgency: 0.5)
+      3.times { momentum.update(v, 0.5) }
+      expect(momentum.emotional_state[:history_size]).to eq(3)
+    end
+
+    it 'caps history at 100' do
+      v = valence_mod.new_valence
+      105.times { momentum.update(v, 0.1) }
+      expect(momentum.emotional_state[:history_size]).to eq(100)
+    end
+
+    it 'computes stability as inverse of emotional change' do
+      v_calm = valence_mod.new_valence(urgency: 0.1)
+      v_alarm = valence_mod.new_valence(urgency: 1.0, importance: 1.0, novelty: 1.0, familiarity: 1.0)
+
+      momentum.update(v_calm, 0.1)
+      result = momentum.update(v_alarm, 0.9)
+      expect(result[:stability]).to be < 1.0
+    end
+  end
+end

data/spec/legion/extensions/emotion/helpers/valence_spec.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Emotion::Helpers::Valence do
+  describe '.new_valence' do
+    it 'creates a valence with defaults' do
+      v = described_class.new_valence
+      expect(v[:urgency]).to eq(0.0)
+      expect(v[:importance]).to eq(0.0)
+      expect(v[:novelty]).to eq(0.0)
+      expect(v[:familiarity]).to eq(0.0)
+    end
+
+    it 'creates a valence with custom values' do
+      v = described_class.new_valence(urgency: 0.8, importance: 0.6)
+      expect(v[:urgency]).to eq(0.8)
+      expect(v[:importance]).to eq(0.6)
+    end
+
+    it 'clamps values to [0, 1]' do
+      v = described_class.new_valence(urgency: 1.5, novelty: -0.3)
+      expect(v[:urgency]).to eq(1.0)
+      expect(v[:novelty]).to eq(0.0)
+    end
+  end
+
+  describe '.magnitude' do
+    it 'computes zero for zero valence' do
+      v = described_class.new_valence
+      expect(described_class.magnitude(v)).to eq(0.0)
+    end
+
+    it 'computes sqrt(4) for all-ones valence' do
+      v = described_class.new_valence(urgency: 1.0, importance: 1.0, novelty: 1.0, familiarity: 1.0)
+      expect(described_class.magnitude(v)).to be_within(0.001).of(2.0)
+    end
+  end
+
+  describe '.dominant_dimension' do
+    it 'returns the highest dimension' do
+      v = described_class.new_valence(urgency: 0.2, importance: 0.9, novelty: 0.1, familiarity: 0.3)
+      expect(described_class.dominant_dimension(v)).to eq(:importance)
+    end
+  end
+
+  describe '.aggregate' do
+    it 'returns zero valence for empty array' do
+      result = described_class.aggregate([])
+      expect(result[:urgency]).to eq(0.0)
+    end
+
+    it 'averages multiple valences' do
+      v1 = described_class.new_valence(urgency: 0.8, importance: 0.2)
+      v2 = described_class.new_valence(urgency: 0.4, importance: 0.6)
+      result = described_class.aggregate([v1, v2])
+      expect(result[:urgency]).to be_within(0.001).of(0.6)
+      expect(result[:importance]).to be_within(0.001).of(0.4)
+    end
+  end
+
+  describe '.compute_arousal' do
+    it 'returns 0 for empty valences' do
+      expect(described_class.compute_arousal([])).to eq(0.0)
+    end
+
+    it 'returns 1.0 for all-max valences' do
+      v = described_class.new_valence(urgency: 1.0, importance: 1.0, novelty: 1.0, familiarity: 1.0)
+      expect(described_class.compute_arousal([v])).to be_within(0.001).of(1.0)
+    end
+
+    it 'returns moderate arousal for mixed valences' do
+      v = described_class.new_valence(urgency: 0.5, importance: 0.5)
+      arousal = described_class.compute_arousal([v])
+      expect(arousal).to be > 0.0
+      expect(arousal).to be < 1.0
+    end
+  end
+
+  describe '.modulate_salience' do
+    it 'boosts salience based on valence' do
+      v = described_class.new_valence(urgency: 0.8, importance: 0.6, novelty: 0.4)
+      modulated = described_class.modulate_salience(0.5, v)
+      expect(modulated).to be > 0.5
+    end
+
+    it 'clamps at 1.0' do
+      v = described_class.new_valence(urgency: 1.0, importance: 1.0, novelty: 1.0)
+      modulated = described_class.modulate_salience(0.9, v)
+      expect(modulated).to eq(1.0)
+    end
+  end
+end

data/spec/legion/extensions/emotion/runners/gut_spec.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/emotion/client'
+
+RSpec.describe Legion::Extensions::Emotion::Runners::Gut do
+  let(:client) { Legion::Extensions::Emotion::Client.new }
+  let(:valence_mod) { Legion::Extensions::Emotion::Helpers::Valence }
+
+  describe '#gut_instinct' do
+    it 'returns neutral for empty valences' do
+      result = client.gut_instinct(valences: [])
+      expect(result[:signal]).to eq(:neutral)
+      expect(result[:confidence]).to eq(0.0)
+    end
+
+    it 'returns alarm for high urgency + importance' do
+      v = valence_mod.new_valence(urgency: 0.9, importance: 0.9, novelty: 0.5, familiarity: 0.5)
+      result = client.gut_instinct(valences: [v])
+      expect(result[:signal]).to eq(:alarm)
+    end
+
+    it 'returns explore for high novelty + low familiarity' do
+      v = valence_mod.new_valence(urgency: 0.2, importance: 0.2, novelty: 0.9, familiarity: 0.1)
+      result = client.gut_instinct(valences: [v])
+      expect(result[:signal]).to eq(:explore)
+    end
+
+    it 'returns calm for low arousal' do
+      v = valence_mod.new_valence(urgency: 0.05, importance: 0.05, novelty: 0.05, familiarity: 0.05)
+      result = client.gut_instinct(valences: [v])
+      expect(result[:signal]).to eq(:calm)
+    end
+
+    it 'includes confidence and reliability' do
+      v = valence_mod.new_valence(urgency: 0.5)
+      result = client.gut_instinct(valences: [v], memory_signals: [1, 2, 3])
+      expect(result).to have_key(:confidence)
+      expect(result).to have_key(:reliable)
+    end
+
+    it 'increases confidence with more memory evidence' do
+      v = valence_mod.new_valence(urgency: 0.5)
+      low_evidence = client.gut_instinct(valences: [v], memory_signals: [])
+      high_evidence = client.gut_instinct(valences: [v], memory_signals: Array.new(10, 1))
+      expect(high_evidence[:confidence]).to be >= low_evidence[:confidence]
+    end
+  end
+
+  describe '#emotional_state' do
+    it 'returns momentum and baseline state' do
+      state = client.emotional_state
+      expect(state).to have_key(:momentum)
+      expect(state).to have_key(:baseline)
+    end
+  end
+
+  describe '#decay_momentum' do
+    it 'returns decayed: true' do
+      result = client.decay_momentum
+      expect(result[:decayed]).to be true
+    end
+
+    it 'returns a Float stability value' do
+      result = client.decay_momentum
+      expect(result[:stability]).to be_a(Float)
+    end
+
+    it 'returns stability within [0.0, 1.0]' do
+      result = client.decay_momentum
+      expect(result[:stability]).to be_between(0.0, 1.0)
+    end
+  end
+end

data/spec/legion/extensions/emotion/runners/valence_spec.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/emotion/client'
+
+RSpec.describe Legion::Extensions::Emotion::Runners::Valence do
+  let(:client) { Legion::Extensions::Emotion::Client.new }
+
+  describe '#evaluate_valence' do
+    it 'returns a valence with 4 dimensions' do
+      result = client.evaluate_valence(signal: { urgency_hint: 0.5 })
+      expect(result[:valence].keys).to contain_exactly(:urgency, :importance, :novelty, :familiarity)
+    end
+
+    it 'returns magnitude' do
+      result = client.evaluate_valence(signal: {})
+      expect(result[:magnitude]).to be >= 0.0
+    end
+
+    it 'returns dominant dimension' do
+      result = client.evaluate_valence(signal: { domain_weight: 0.9, impact_scope: 0.8, outcome_severity: 0.9 })
+      expect(result[:dominant_dimension]).to be_a(Symbol)
+    end
+
+    it 'responds to source type urgency' do
+      ambient = client.evaluate_valence(signal: {}, source_type: :ambient)
+      human = client.evaluate_valence(signal: {}, source_type: :human_direct)
+      expect(human[:valence][:urgency]).to be >= ambient[:valence][:urgency]
+    end
+
+    it 'responds to deadlines' do
+      no_deadline = client.evaluate_valence(signal: {})
+      with_deadline = client.evaluate_valence(signal: {}, deadline: Time.now.utc + 60)
+      expect(with_deadline[:valence][:urgency]).to be >= no_deadline[:valence][:urgency]
+    end
+  end
+
+  describe '#aggregate_valences' do
+    it 'aggregates multiple valences' do
+      v = Legion::Extensions::Emotion::Helpers::Valence
+      valences = [
+        v.new_valence(urgency: 0.8, importance: 0.2),
+        v.new_valence(urgency: 0.4, importance: 0.6)
+      ]
+      result = client.aggregate_valences(valences: valences)
+      expect(result[:aggregate][:urgency]).to be_within(0.01).of(0.6)
+      expect(result[:count]).to eq(2)
+    end
+  end
+
+  describe '#modulate_attention' do
+    it 'boosts salience' do
+      v = Legion::Extensions::Emotion::Helpers::Valence.new_valence(urgency: 0.8, importance: 0.7)
+      result = client.modulate_attention(base_salience: 0.5, valence: v)
+      expect(result[:modulated]).to be > result[:original]
+      expect(result[:boost]).to be > 0
+    end
+  end
+
+  describe '#compute_arousal' do
+    it 'computes arousal from valences' do
+      v = Legion::Extensions::Emotion::Helpers::Valence
+      valences = [v.new_valence(urgency: 0.9, importance: 0.9)]
+      result = client.compute_arousal(valences: valences)
+      expect(result[:arousal]).to be > 0.0
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+module Legion
+  module Logging
+    def self.debug(_msg); end
+    def self.info(_msg); end
+    def self.warn(_msg); end
+    def self.error(_msg); end
+  end
+end
+
+require 'legion/extensions/emotion'
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = '.rspec_status'
+  config.disable_monkey_patching!
+  config.expect_with(:rspec) { |c| c.syntax = :expect }
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: lex-emotion
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+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: Multi-dimensional emotional valence for brain-modeled agentic AI
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE
+- README.md
+- lex-emotion.gemspec
+- lib/legion/extensions/emotion.rb
+- lib/legion/extensions/emotion/actors/momentum_decay.rb
+- lib/legion/extensions/emotion/client.rb
+- lib/legion/extensions/emotion/helpers/baseline.rb
+- lib/legion/extensions/emotion/helpers/momentum.rb
+- lib/legion/extensions/emotion/helpers/valence.rb
+- lib/legion/extensions/emotion/runners/gut.rb
+- lib/legion/extensions/emotion/runners/valence.rb
+- lib/legion/extensions/emotion/version.rb
+- spec/legion/extensions/emotion/actors/momentum_decay_spec.rb
+- spec/legion/extensions/emotion/client_spec.rb
+- spec/legion/extensions/emotion/helpers/baseline_spec.rb
+- spec/legion/extensions/emotion/helpers/momentum_spec.rb
+- spec/legion/extensions/emotion/helpers/valence_spec.rb
+- spec/legion/extensions/emotion/runners/gut_spec.rb
+- spec/legion/extensions/emotion/runners/valence_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-emotion
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-emotion
+  source_code_uri: https://github.com/LegionIO/lex-emotion
+  documentation_uri: https://github.com/LegionIO/lex-emotion
+  changelog_uri: https://github.com/LegionIO/lex-emotion
+  bug_tracker_uri: https://github.com/LegionIO/lex-emotion/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: LEX Emotion
+test_files: []