lex-appraisal 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 52c53808a09c9610ddad5a0ac61a10580160c2c0c1f45dcffaaeafc88e0a3e15
+  data.tar.gz: 805206fecd29f46906a9b9ff6ae7c62910f506ac8a6c0dddf161856ce0bd2613
+SHA512:
+  metadata.gz: 9413416882b9fa097d1f70cab841849924e0e84055aa2533b601f9144cc41b3d16585803687f8aea9fe556c58723ce0d38ca7c49a40637053d63a57611164625
+  data.tar.gz: 5efcd44babd9b35f8b8a914207a40bab734a9bae3a5fd66cca7aa8985e86f543e0ad9243ec9d88a1fa70a6f6123712e65539acaf5a29b4c5cf0fbd1bf96e6035

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,65 @@
+# lex-appraisal
+
+Lazarus's Cognitive Appraisal Theory for brain-modeled agentic AI.
+
+## What It Does
+
+Models how the agent evaluates events to determine their emotional significance. Based on Lazarus's two-stage appraisal process: primary appraisal assesses relevance, goal alignment, and importance; secondary appraisal assesses coping capacity, control, and future expectancy. The combination determines the emotional response (anxiety, joy, anger, challenge, etc.) and guides coping strategy selection.
+
+## Core Concept: Two-Stage Appraisal
+
+```ruby
+# Stage 1: Primary appraisal (how relevant is this event to my goals?)
+# Stage 2: Secondary appraisal (can I handle it?)
+# Combined -> emotional response
+
+result = client.appraise_event(
+  event: 'service outage in production',
+  primary:   { relevance: 0.95, goal_congruence: -0.8, goal_importance: 0.9 },
+  secondary: { coping_potential: 0.3, control_expectation: 0.4, future_expectancy: 0.5 },
+  domain: :infrastructure
+)
+# => { appraisal: { emotion: :anxiety, intensity: 0.8, ... } }
+```
+
+## Usage
+
+```ruby
+client = Legion::Extensions::Appraisal::Client.new
+
+# Register a coping strategy
+client.add_coping_strategy(name: :incident_playbook, coping_type: :problem_focused, effectiveness: 0.85)
+
+# Appraise an event
+result = client.appraise_event(event: 'deployment failed', primary: {...}, secondary: {...})
+
+# Reappraise with new information (reduces intensity by 30%)
+client.reappraise_event(
+  appraisal_id: result[:appraisal][:id],
+  new_primary: { relevance: 0.5, goal_congruence: 0.2, goal_importance: 0.6 },
+  new_secondary: { coping_potential: 0.8, control_expectation: 0.7, future_expectancy: 0.8 }
+)
+
+# Select a coping strategy
+client.select_coping_strategy(appraisal_id: id, coping_type: :problem_focused)
+
+# View emotional patterns
+client.emotional_pattern
+# => { anxiety: 3, challenge: 2, joy: 1 }
+```
+
+## Integration
+
+Feeds into lex-emotion: derived emotions provide typed signals for valence evaluation. Reappraisal models cognitive emotion regulation. `emotional_pattern` informs lex-dream's agenda formation about recurring stressors.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-appraisal.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/appraisal/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-appraisal'
+  spec.version       = Legion::Extensions::Appraisal::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Appraisal'
+  spec.description   = "Lazarus's Cognitive Appraisal Theory for brain-modeled agentic AI"
+  spec.homepage      = 'https://github.com/LegionIO/lex-appraisal'
+  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-appraisal'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-appraisal'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-appraisal'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-appraisal/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-appraisal.gemspec Gemfile LICENSE README.md]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/appraisal/helpers/constants'
+require 'legion/extensions/appraisal/helpers/appraisal'
+require 'legion/extensions/appraisal/helpers/appraisal_engine'
+require 'legion/extensions/appraisal/runners/appraisal'
+
+module Legion
+  module Extensions
+    module Appraisal
+      class Client
+        include Runners::Appraisal
+      end
+    end
+  end
+end

data/lib/legion/extensions/appraisal/helpers/appraisal.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Appraisal
+      module Helpers
+        class Appraisal
+          include Constants
+
+          attr_reader :id, :event, :domain, :primary, :secondary,
+                      :emotional_outcome, :intensity, :coping_strategy,
+                      :reappraised, :created_at, :reappraised_at
+
+          def initialize(event:, primary:, secondary:, domain: nil)
+            @id               = SecureRandom.uuid
+            @event            = event
+            @domain           = domain
+            @primary          = normalize_dimensions(primary, PRIMARY_DIMENSIONS)
+            @secondary        = normalize_dimensions(secondary, SECONDARY_DIMENSIONS)
+            @intensity        = DEFAULT_INTENSITY
+            @coping_strategy  = nil
+            @reappraised      = false
+            @created_at       = Time.now.utc
+            @reappraised_at   = nil
+            @emotional_outcome = compute_emotion
+          end
+
+          def reappraise(new_primary:, new_secondary:)
+            @primary          = normalize_dimensions(new_primary, PRIMARY_DIMENSIONS)
+            @secondary        = normalize_dimensions(new_secondary, SECONDARY_DIMENSIONS)
+            @emotional_outcome = compute_emotion
+            @intensity        = (@intensity * (1 - REAPPRAISAL_DISCOUNT)).clamp(INTENSITY_FLOOR, INTENSITY_CEILING)
+            @reappraised      = true
+            @reappraised_at   = Time.now.utc
+            self
+          end
+
+          def compute_emotion
+            relevance        = @primary[:relevance]
+            goal_congruence  = @primary[:goal_congruence]
+            coping_potential = @secondary[:coping_potential]
+
+            return :indifference if relevance < 0.3
+
+            classify_emotion(goal_congruence, coping_potential)
+          end
+
+          def to_h
+            {
+              id:                @id,
+              event:             @event,
+              domain:            @domain,
+              primary:           @primary,
+              secondary:         @secondary,
+              emotional_outcome: @emotional_outcome,
+              intensity:         @intensity,
+              coping_strategy:   @coping_strategy,
+              reappraised:       @reappraised,
+              created_at:        @created_at,
+              reappraised_at:    @reappraised_at
+            }
+          end
+
+          def assign_coping(strategy_name)
+            @coping_strategy = strategy_name
+          end
+
+          def decay!
+            @intensity = (@intensity - DECAY_RATE).clamp(INTENSITY_FLOOR, INTENSITY_CEILING)
+          end
+
+          private
+
+          def classify_emotion(goal_congruence, coping_potential)
+            if goal_congruence < 0.4
+              low_congruence_emotion(goal_congruence, coping_potential)
+            elsif goal_congruence > 0.7
+              :joy
+            else
+              :sadness
+            end
+          end
+
+          def low_congruence_emotion(goal_congruence, coping_potential)
+            if goal_congruence < 0.3
+              :anger
+            elsif coping_potential < 0.4
+              :anxiety
+            elsif coping_potential >= 0.6
+              :challenge
+            else
+              :sadness
+            end
+          end
+
+          def normalize_dimensions(raw, dimensions)
+            dimensions.to_h do |dim|
+              val = raw.fetch(dim, 0.0).to_f
+              [dim, val.clamp(INTENSITY_FLOOR, INTENSITY_CEILING)]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/appraisal/helpers/appraisal_engine.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Appraisal
+      module Helpers
+        class AppraisalEngine
+          include Constants
+
+          def initialize
+            @appraisals        = {}
+            @coping_strategies = {}
+            @history           = []
+          end
+
+          def appraise(event:, primary:, secondary:, domain: nil)
+            record = Appraisal.new(event: event, primary: primary, secondary: secondary, domain: domain)
+            prune_appraisals if @appraisals.size >= MAX_APPRAISALS
+            @appraisals[record.id] = record
+            archive(record)
+            record
+          end
+
+          def reappraise(appraisal_id:, new_primary:, new_secondary:)
+            record = @appraisals[appraisal_id]
+            return nil unless record
+
+            record.reappraise(new_primary: new_primary, new_secondary: new_secondary)
+            archive(record)
+            record
+          end
+
+          def select_coping(appraisal_id:, coping_type:)
+            record = @appraisals[appraisal_id]
+            return nil unless record
+
+            strategy = find_best_strategy(coping_type)
+            name = strategy ? strategy[:name] : coping_type.to_s
+            record.assign_coping(name)
+            record
+          end
+
+          def add_coping_strategy(name:, coping_type:, effectiveness:)
+            return false if @coping_strategies.size >= MAX_COPING_STRATEGIES
+
+            @coping_strategies[name] = {
+              name:          name,
+              coping_type:   coping_type,
+              effectiveness: effectiveness.to_f.clamp(INTENSITY_FLOOR, INTENSITY_CEILING)
+            }
+            true
+          end
+
+          def evaluate_coping(appraisal_id:)
+            record = @appraisals[appraisal_id]
+            return { effectiveness: 0.0, resolved: false } unless record
+            return { effectiveness: 0.0, resolved: false } unless record.coping_strategy
+
+            strategy    = @coping_strategies[record.coping_strategy]
+            base        = strategy ? strategy[:effectiveness] : DEFAULT_INTENSITY
+            resolved    = record.intensity < 0.3
+            {
+              appraisal_id:  appraisal_id,
+              coping:        record.coping_strategy,
+              effectiveness: base,
+              intensity:     record.intensity,
+              resolved:      resolved
+            }
+          end
+
+          def by_emotion(emotion:)
+            @appraisals.values.select { |rec| rec.emotional_outcome == emotion }
+          end
+
+          def by_domain(domain:)
+            @appraisals.values.select { |rec| rec.domain == domain }
+          end
+
+          def unresolved
+            @appraisals.values.select { |rec| rec.coping_strategy.nil? }
+          end
+
+          def emotional_pattern
+            counts = Hash.new(0)
+            recent_appraisals.each { |rec| counts[rec.emotional_outcome] += 1 }
+            counts.sort_by { |_, cnt| -cnt }.to_h
+          end
+
+          def decay_all
+            @appraisals.each_value(&:decay!)
+          end
+
+          def to_h
+            {
+              appraisals:        @appraisals.transform_values(&:to_h),
+              coping_strategies: @coping_strategies,
+              history_size:      @history.size
+            }
+          end
+
+          private
+
+          def archive(record)
+            @history << { id: record.id, emotion: record.emotional_outcome, at: Time.now.utc }
+            @history.shift while @history.size > MAX_HISTORY
+          end
+
+          def prune_appraisals
+            oldest_key = @appraisals.min_by { |_, rec| rec.created_at }&.first
+            @appraisals.delete(oldest_key) if oldest_key
+          end
+
+          def find_best_strategy(coping_type)
+            matches = @coping_strategies.values.select { |str| str[:coping_type] == coping_type }
+            matches.max_by { |str| str[:effectiveness] }
+          end
+
+          def recent_appraisals
+            @appraisals.values.last(50)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Appraisal
+      module Helpers
+        module Constants
+          MAX_APPRAISALS = 200
+          MAX_COPING_STRATEGIES = 50
+          MAX_HISTORY         = 300
+
+          DEFAULT_INTENSITY   = 0.5
+          INTENSITY_FLOOR     = 0.0
+          INTENSITY_CEILING   = 1.0
+
+          DECAY_RATE = 0.02
+          REAPPRAISAL_DISCOUNT = 0.3
+
+          PRIMARY_DIMENSIONS = %i[relevance goal_congruence goal_importance].freeze
+
+          SECONDARY_DIMENSIONS = %i[coping_potential control_expectation future_expectancy].freeze
+
+          APPRAISAL_EMOTIONS = {
+            threat_low_coping:   :anxiety,
+            threat_high_coping:  :challenge,
+            loss:                :sadness,
+            goal_incongruent:    :anger,
+            goal_congruent:      :joy,
+            irrelevant:          :indifference,
+            unexpected_positive: :surprise,
+            moral_violation:     :disgust
+          }.freeze
+
+          COPING_TYPES = %i[problem_focused emotion_focused meaning_focused avoidant social_support].freeze
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Appraisal
+      module Runners
+        module Appraisal
+          def appraise_event(event:, primary:, secondary:, domain: nil, **)
+            Legion::Logging.debug("[lex-appraisal] appraise_event event=#{event} domain=#{domain}")
+            record = engine.appraise(event: event, primary: primary, secondary: secondary, domain: domain)
+            { success: true, appraisal: record.to_h }
+          rescue StandardError => e
+            Legion::Logging.error("[lex-appraisal] appraise_event error: #{e.message}")
+            { success: false, error: e.message }
+          end
+
+          def reappraise_event(appraisal_id:, new_primary:, new_secondary:, **)
+            Legion::Logging.debug("[lex-appraisal] reappraise_event id=#{appraisal_id}")
+            record = engine.reappraise(appraisal_id: appraisal_id, new_primary: new_primary,
+                                       new_secondary: new_secondary)
+            return { success: false, error: 'appraisal not found' } unless record
+
+            { success: true, appraisal: record.to_h }
+          rescue StandardError => e
+            Legion::Logging.error("[lex-appraisal] reappraise_event error: #{e.message}")
+            { success: false, error: e.message }
+          end
+
+          def select_coping_strategy(appraisal_id:, coping_type:, **)
+            Legion::Logging.debug("[lex-appraisal] select_coping appraisal_id=#{appraisal_id}")
+            record = engine.select_coping(appraisal_id: appraisal_id, coping_type: coping_type)
+            return { success: false, error: 'appraisal not found' } unless record
+
+            { success: true, appraisal: record.to_h }
+          rescue StandardError => e
+            Legion::Logging.error("[lex-appraisal] select_coping error: #{e.message}")
+            { success: false, error: e.message }
+          end
+
+          def add_coping_strategy(name:, coping_type:, effectiveness:, **)
+            Legion::Logging.debug("[lex-appraisal] add_coping_strategy name=#{name}")
+            added = engine.add_coping_strategy(name: name, coping_type: coping_type, effectiveness: effectiveness)
+            { success: added, name: name, coping_type: coping_type }
+          rescue StandardError => e
+            Legion::Logging.error("[lex-appraisal] add_coping_strategy error: #{e.message}")
+            { success: false, error: e.message }
+          end
+
+          def evaluate_coping(appraisal_id:, **)
+            Legion::Logging.debug("[lex-appraisal] evaluate_coping id=#{appraisal_id}")
+            result = engine.evaluate_coping(appraisal_id: appraisal_id)
+            { success: true }.merge(result)
+          rescue StandardError => e
+            Legion::Logging.error("[lex-appraisal] evaluate_coping error: #{e.message}")
+            { success: false, error: e.message }
+          end
+
+          def emotional_pattern(**)
+            Legion::Logging.debug('[lex-appraisal] emotional_pattern')
+            pattern = engine.emotional_pattern
+            { success: true, pattern: pattern }
+          rescue StandardError => e
+            Legion::Logging.error("[lex-appraisal] emotional_pattern error: #{e.message}")
+            { success: false, error: e.message }
+          end
+
+          def update_appraisal(**)
+            Legion::Logging.debug('[lex-appraisal] update_appraisal (decay cycle)')
+            engine.decay_all
+            { success: true }
+          rescue StandardError => e
+            Legion::Logging.error("[lex-appraisal] update_appraisal error: #{e.message}")
+            { success: false, error: e.message }
+          end
+
+          def appraisal_stats(**)
+            Legion::Logging.debug('[lex-appraisal] appraisal_stats')
+            data = engine.to_h
+            unresolved = engine.unresolved.size
+            {
+              success:      true,
+              total:        data[:appraisals].size,
+              unresolved:   unresolved,
+              history_size: data[:history_size],
+              pattern:      engine.emotional_pattern
+            }
+          rescue StandardError => e
+            Legion::Logging.error("[lex-appraisal] appraisal_stats error: #{e.message}")
+            { success: false, error: e.message }
+          end
+
+          private
+
+          def engine
+            @engine ||= Helpers::AppraisalEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/appraisal.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/appraisal/version'
+require 'legion/extensions/appraisal/helpers/constants'
+require 'legion/extensions/appraisal/helpers/appraisal'
+require 'legion/extensions/appraisal/helpers/appraisal_engine'
+require 'legion/extensions/appraisal/runners/appraisal'
+
+module Legion
+  module Extensions
+    module Appraisal
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/appraisal/client'
+
+RSpec.describe Legion::Extensions::Appraisal::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to all runner methods' do
+    expect(client).to respond_to(:appraise_event)
+    expect(client).to respond_to(:reappraise_event)
+    expect(client).to respond_to(:select_coping_strategy)
+    expect(client).to respond_to(:add_coping_strategy)
+    expect(client).to respond_to(:evaluate_coping)
+    expect(client).to respond_to(:emotional_pattern)
+    expect(client).to respond_to(:update_appraisal)
+    expect(client).to respond_to(:appraisal_stats)
+  end
+
+  it 'maintains isolated engine state per client instance' do
+    client2 = described_class.new
+    client.appraise_event(
+      event:     'only in client1',
+      primary:   { relevance: 0.9, goal_congruence: 0.9, goal_importance: 0.8 },
+      secondary: { coping_potential: 0.8, control_expectation: 0.7, future_expectancy: 0.6 }
+    )
+    expect(client.appraisal_stats[:total]).to eq(1)
+    expect(client2.appraisal_stats[:total]).to eq(0)
+  end
+
+  it 'runs a full appraisal cycle' do
+    primary   = { relevance: 0.9, goal_congruence: 0.3, goal_importance: 0.8 }
+    secondary = { coping_potential: 0.2, control_expectation: 0.3, future_expectancy: 0.4 }
+
+    appraisal_id = client.appraise_event(event: 'crisis', primary: primary,
+                                         secondary: secondary)[:appraisal][:id]
+    client.add_coping_strategy(name: 'deep_breathing', coping_type: :emotion_focused, effectiveness: 0.7)
+    client.select_coping_strategy(appraisal_id: appraisal_id, coping_type: :emotion_focused)
+    eval_result = client.evaluate_coping(appraisal_id: appraisal_id)
+    expect(eval_result[:success]).to be(true)
+    expect(eval_result[:coping]).to eq('deep_breathing')
+
+    client.reappraise_event(
+      appraisal_id:  appraisal_id,
+      new_primary:   { relevance: 0.9, goal_congruence: 0.9, goal_importance: 0.8 },
+      new_secondary: { coping_potential: 0.8, control_expectation: 0.7, future_expectancy: 0.6 }
+    )
+    client.update_appraisal
+    stats = client.appraisal_stats
+    expect(stats[:total]).to eq(1)
+    expect(stats[:pattern]).to be_a(Hash)
+  end
+end

data/spec/legion/extensions/appraisal/helpers/appraisal_engine_spec.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Appraisal::Helpers::AppraisalEngine do
+  let(:engine) { described_class.new }
+
+  let(:primary_joy)    { { relevance: 0.9, goal_congruence: 0.9, goal_importance: 0.8 } }
+  let(:primary_threat) { { relevance: 0.9, goal_congruence: 0.3, goal_importance: 0.8 } }
+  let(:secondary_low)  { { coping_potential: 0.2, control_expectation: 0.3, future_expectancy: 0.4 } }
+  let(:secondary_high) { { coping_potential: 0.8, control_expectation: 0.7, future_expectancy: 0.6 } }
+
+  describe '#appraise' do
+    it 'creates and returns an appraisal' do
+      record = engine.appraise(event: 'test', primary: primary_joy, secondary: secondary_high)
+      expect(record).to be_a(Legion::Extensions::Appraisal::Helpers::Appraisal)
+      expect(record.event).to eq('test')
+    end
+
+    it 'stores appraisals by id' do
+      record = engine.appraise(event: 'test', primary: primary_joy, secondary: secondary_high)
+      expect(engine.to_h[:appraisals]).to have_key(record.id)
+    end
+
+    it 'computes emotional_outcome' do
+      record = engine.appraise(event: 'test', primary: primary_joy, secondary: secondary_high)
+      expect(record.emotional_outcome).to eq(:joy)
+    end
+  end
+
+  describe '#reappraise' do
+    it 'updates an existing appraisal' do
+      record = engine.appraise(event: 'test', primary: primary_threat, secondary: secondary_low)
+      expect(record.emotional_outcome).to eq(:anxiety)
+      updated = engine.reappraise(appraisal_id: record.id, new_primary: primary_joy, new_secondary: secondary_high)
+      expect(updated.emotional_outcome).to eq(:joy)
+      expect(updated.reappraised).to be(true)
+    end
+
+    it 'returns nil for unknown id' do
+      result = engine.reappraise(appraisal_id: 'unknown', new_primary: primary_joy, new_secondary: secondary_high)
+      expect(result).to be_nil
+    end
+  end
+
+  describe '#select_coping' do
+    it 'assigns coping to appraisal' do
+      record = engine.appraise(event: 'test', primary: primary_threat, secondary: secondary_low)
+      updated = engine.select_coping(appraisal_id: record.id, coping_type: :problem_focused)
+      expect(updated.coping_strategy).not_to be_nil
+    end
+
+    it 'prefers registered strategies for the coping type' do
+      engine.add_coping_strategy(name: 'action_plan', coping_type: :problem_focused, effectiveness: 0.9)
+      record = engine.appraise(event: 'test', primary: primary_threat, secondary: secondary_low)
+      updated = engine.select_coping(appraisal_id: record.id, coping_type: :problem_focused)
+      expect(updated.coping_strategy).to eq('action_plan')
+    end
+
+    it 'returns nil for unknown appraisal' do
+      result = engine.select_coping(appraisal_id: 'unknown', coping_type: :problem_focused)
+      expect(result).to be_nil
+    end
+  end
+
+  describe '#add_coping_strategy' do
+    it 'registers a strategy and returns true' do
+      result = engine.add_coping_strategy(name: 'reframing', coping_type: :emotion_focused, effectiveness: 0.7)
+      expect(result).to be(true)
+    end
+
+    it 'clamps effectiveness to [0, 1]' do
+      engine.add_coping_strategy(name: 'over', coping_type: :problem_focused, effectiveness: 1.5)
+      data = engine.to_h
+      # Strategy stored (engine is internal, test via evaluate_coping behavior)
+      expect(data).to be_a(Hash)
+    end
+  end
+
+  describe '#evaluate_coping' do
+    it 'returns effectiveness 0.0 when no coping assigned' do
+      record = engine.appraise(event: 'test', primary: primary_threat, secondary: secondary_low)
+      result = engine.evaluate_coping(appraisal_id: record.id)
+      expect(result[:effectiveness]).to eq(0.0)
+      expect(result[:resolved]).to be(false)
+    end
+
+    it 'uses registered strategy effectiveness' do
+      engine.add_coping_strategy(name: 'mindfulness', coping_type: :emotion_focused, effectiveness: 0.85)
+      record = engine.appraise(event: 'test', primary: primary_threat, secondary: secondary_low)
+      engine.select_coping(appraisal_id: record.id, coping_type: :emotion_focused)
+      result = engine.evaluate_coping(appraisal_id: record.id)
+      expect(result[:effectiveness]).to be_within(0.01).of(0.85)
+    end
+
+    it 'returns defaults for unknown appraisal' do
+      result = engine.evaluate_coping(appraisal_id: 'unknown')
+      expect(result[:effectiveness]).to eq(0.0)
+    end
+  end
+
+  describe '#by_emotion' do
+    it 'filters appraisals by emotional outcome' do
+      engine.appraise(event: 'a', primary: primary_joy,    secondary: secondary_high)
+      engine.appraise(event: 'b', primary: primary_threat, secondary: secondary_low)
+      joy_list = engine.by_emotion(emotion: :joy)
+      expect(joy_list.size).to eq(1)
+      expect(joy_list.first.event).to eq('a')
+    end
+  end
+
+  describe '#by_domain' do
+    it 'filters appraisals by domain' do
+      engine.appraise(event: 'a', primary: primary_joy, secondary: secondary_high, domain: 'work')
+      engine.appraise(event: 'b', primary: primary_joy, secondary: secondary_high, domain: 'personal')
+      work_list = engine.by_domain(domain: 'work')
+      expect(work_list.size).to eq(1)
+      expect(work_list.first.event).to eq('a')
+    end
+  end
+
+  describe '#unresolved' do
+    it 'returns appraisals without coping strategy' do
+      rec1 = engine.appraise(event: 'a', primary: primary_joy, secondary: secondary_high)
+      rec2 = engine.appraise(event: 'b', primary: primary_joy, secondary: secondary_high)
+      engine.select_coping(appraisal_id: rec1.id, coping_type: :problem_focused)
+      unresolved = engine.unresolved
+      expect(unresolved.map(&:id)).to include(rec2.id)
+      expect(unresolved.map(&:id)).not_to include(rec1.id)
+    end
+  end
+
+  describe '#emotional_pattern' do
+    it 'returns emotion counts sorted by frequency' do
+      3.times { engine.appraise(event: 'a', primary: primary_joy, secondary: secondary_high) }
+      engine.appraise(event: 'b', primary: primary_threat, secondary: secondary_low)
+      pattern = engine.emotional_pattern
+      expect(pattern.first.first).to eq(:joy)
+    end
+
+    it 'returns empty hash when no appraisals' do
+      expect(engine.emotional_pattern).to eq({})
+    end
+  end
+
+  describe '#decay_all' do
+    it 'reduces intensity for all appraisals' do
+      rec = engine.appraise(event: 'test', primary: primary_joy, secondary: secondary_high)
+      engine.decay_all
+      expect(rec.intensity).to be < 0.5
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns hash with appraisals, coping_strategies, history_size' do
+      engine.appraise(event: 'test', primary: primary_joy, secondary: secondary_high)
+      result = engine.to_h
+      expect(result).to have_key(:appraisals)
+      expect(result).to have_key(:coping_strategies)
+      expect(result).to have_key(:history_size)
+    end
+  end
+end

data/spec/legion/extensions/appraisal/helpers/appraisal_spec.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Appraisal::Helpers::Appraisal do
+  let(:primary_low)  { { relevance: 0.2, goal_congruence: 0.2, goal_importance: 0.5 } }
+  let(:primary_high) { { relevance: 0.8, goal_congruence: 0.8, goal_importance: 0.9 } }
+  let(:secondary_low)  { { coping_potential: 0.2, control_expectation: 0.3, future_expectancy: 0.4 } }
+  let(:secondary_high) { { coping_potential: 0.8, control_expectation: 0.7, future_expectancy: 0.6 } }
+
+  def build(primary: primary_high, secondary: secondary_high, domain: 'work')
+    described_class.new(event: 'test event', primary: primary, secondary: secondary, domain: domain)
+  end
+
+  describe '#initialize' do
+    it 'sets id, event, domain' do
+      appraisal = build
+      expect(appraisal.id).to be_a(String)
+      expect(appraisal.event).to eq('test event')
+      expect(appraisal.domain).to eq('work')
+    end
+
+    it 'normalizes primary dimensions' do
+      appraisal = build
+      expect(appraisal.primary.keys).to contain_exactly(:relevance, :goal_congruence, :goal_importance)
+    end
+
+    it 'normalizes secondary dimensions' do
+      appraisal = build
+      expect(appraisal.secondary.keys).to contain_exactly(:coping_potential, :control_expectation, :future_expectancy)
+    end
+
+    it 'clamps out-of-range values' do
+      appraisal = described_class.new(
+        event:     'e',
+        primary:   { relevance: 2.0, goal_congruence: -0.5, goal_importance: 0.5 },
+        secondary: secondary_high
+      )
+      expect(appraisal.primary[:relevance]).to eq(1.0)
+      expect(appraisal.primary[:goal_congruence]).to eq(0.0)
+    end
+
+    it 'sets default intensity' do
+      expect(build.intensity).to eq(0.5)
+    end
+
+    it 'sets reappraised to false' do
+      expect(build.reappraised).to be(false)
+    end
+  end
+
+  describe '#compute_emotion' do
+    it 'returns :indifference when relevance is low' do
+      appraisal = described_class.new(
+        event:     'e',
+        primary:   { relevance: 0.2, goal_congruence: 0.5, goal_importance: 0.5 },
+        secondary: secondary_high
+      )
+      expect(appraisal.emotional_outcome).to eq(:indifference)
+    end
+
+    it 'returns :anxiety for threat with low coping' do
+      appraisal = described_class.new(
+        event:     'e',
+        primary:   { relevance: 0.9, goal_congruence: 0.3, goal_importance: 0.8 },
+        secondary: { coping_potential: 0.2, control_expectation: 0.3, future_expectancy: 0.4 }
+      )
+      expect(appraisal.emotional_outcome).to eq(:anxiety)
+    end
+
+    it 'returns :challenge for threat with high coping' do
+      appraisal = described_class.new(
+        event:     'e',
+        primary:   { relevance: 0.9, goal_congruence: 0.3, goal_importance: 0.8 },
+        secondary: { coping_potential: 0.8, control_expectation: 0.7, future_expectancy: 0.6 }
+      )
+      expect(appraisal.emotional_outcome).to eq(:challenge)
+    end
+
+    it 'returns :anger for very low goal_congruence' do
+      appraisal = described_class.new(
+        event:     'e',
+        primary:   { relevance: 0.9, goal_congruence: 0.2, goal_importance: 0.8 },
+        secondary: { coping_potential: 0.5, control_expectation: 0.5, future_expectancy: 0.5 }
+      )
+      expect(appraisal.emotional_outcome).to eq(:anger)
+    end
+
+    it 'returns :joy for high goal_congruence' do
+      appraisal = described_class.new(
+        event:     'e',
+        primary:   { relevance: 0.9, goal_congruence: 0.9, goal_importance: 0.8 },
+        secondary: secondary_high
+      )
+      expect(appraisal.emotional_outcome).to eq(:joy)
+    end
+
+    it 'returns :sadness as fallback' do
+      appraisal = described_class.new(
+        event:     'e',
+        primary:   { relevance: 0.9, goal_congruence: 0.5, goal_importance: 0.5 },
+        secondary: { coping_potential: 0.5, control_expectation: 0.5, future_expectancy: 0.5 }
+      )
+      expect(appraisal.emotional_outcome).to eq(:sadness)
+    end
+  end
+
+  describe '#reappraise' do
+    it 'updates emotion and reduces intensity' do
+      appraisal = described_class.new(
+        event: 'e', primary: primary_low, secondary: secondary_low
+      )
+      original_intensity = appraisal.intensity
+      appraisal.reappraise(new_primary: primary_high, new_secondary: secondary_high)
+      expect(appraisal.reappraised).to be(true)
+      expect(appraisal.intensity).to be < original_intensity
+      expect(appraisal.reappraised_at).not_to be_nil
+    end
+
+    it 'recomputes emotional_outcome' do
+      appraisal = described_class.new(
+        event:     'e',
+        primary:   { relevance: 0.2, goal_congruence: 0.5, goal_importance: 0.5 },
+        secondary: secondary_high
+      )
+      expect(appraisal.emotional_outcome).to eq(:indifference)
+      appraisal.reappraise(
+        new_primary:   { relevance: 0.9, goal_congruence: 0.9, goal_importance: 0.8 },
+        new_secondary: secondary_high
+      )
+      expect(appraisal.emotional_outcome).to eq(:joy)
+    end
+
+    it 'applies REAPPRAISAL_DISCOUNT to intensity' do
+      appraisal = build
+      appraisal.reappraise(new_primary: primary_high, new_secondary: secondary_high)
+      expected = 0.5 * (1 - Legion::Extensions::Appraisal::Helpers::Constants::REAPPRAISAL_DISCOUNT)
+      expect(appraisal.intensity).to be_within(0.001).of(expected)
+    end
+  end
+
+  describe '#decay!' do
+    it 'reduces intensity by DECAY_RATE' do
+      appraisal = build
+      appraisal.decay!
+      expected = 0.5 - Legion::Extensions::Appraisal::Helpers::Constants::DECAY_RATE
+      expect(appraisal.intensity).to be_within(0.001).of(expected)
+    end
+
+    it 'does not go below INTENSITY_FLOOR' do
+      appraisal = described_class.new(
+        event:     'e',
+        primary:   { relevance: 0.9, goal_congruence: 0.9, goal_importance: 0.9 },
+        secondary: secondary_high
+      )
+      60.times { appraisal.decay! }
+      expect(appraisal.intensity).to eq(0.0)
+    end
+  end
+
+  describe '#assign_coping' do
+    it 'sets coping_strategy' do
+      appraisal = build
+      appraisal.assign_coping('reframing')
+      expect(appraisal.coping_strategy).to eq('reframing')
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with expected keys' do
+      appraisal = build
+      keys = appraisal.to_h.keys
+      expect(keys).to include(:id, :event, :domain, :primary, :secondary, :emotional_outcome,
+                              :intensity, :coping_strategy, :reappraised, :created_at, :reappraised_at)
+    end
+  end
+end

data/spec/legion/extensions/appraisal/helpers/constants_spec.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Appraisal::Helpers::Constants do
+  let(:mod) { described_class }
+
+  it 'defines MAX_APPRAISALS' do
+    expect(mod::MAX_APPRAISALS).to eq(200)
+  end
+
+  it 'defines MAX_COPING_STRATEGIES' do
+    expect(mod::MAX_COPING_STRATEGIES).to eq(50)
+  end
+
+  it 'defines MAX_HISTORY' do
+    expect(mod::MAX_HISTORY).to eq(300)
+  end
+
+  it 'defines intensity bounds' do
+    expect(mod::INTENSITY_FLOOR).to eq(0.0)
+    expect(mod::INTENSITY_CEILING).to eq(1.0)
+    expect(mod::DEFAULT_INTENSITY).to eq(0.5)
+  end
+
+  it 'defines DECAY_RATE' do
+    expect(mod::DECAY_RATE).to eq(0.02)
+  end
+
+  it 'defines REAPPRAISAL_DISCOUNT' do
+    expect(mod::REAPPRAISAL_DISCOUNT).to eq(0.3)
+  end
+
+  it 'defines PRIMARY_DIMENSIONS' do
+    expect(mod::PRIMARY_DIMENSIONS).to contain_exactly(:relevance, :goal_congruence, :goal_importance)
+  end
+
+  it 'defines SECONDARY_DIMENSIONS' do
+    expect(mod::SECONDARY_DIMENSIONS).to contain_exactly(:coping_potential, :control_expectation, :future_expectancy)
+  end
+
+  it 'maps APPRAISAL_EMOTIONS' do
+    expect(mod::APPRAISAL_EMOTIONS[:threat_low_coping]).to eq(:anxiety)
+    expect(mod::APPRAISAL_EMOTIONS[:goal_congruent]).to eq(:joy)
+    expect(mod::APPRAISAL_EMOTIONS[:irrelevant]).to eq(:indifference)
+  end
+
+  it 'defines COPING_TYPES' do
+    expect(mod::COPING_TYPES).to include(:problem_focused, :emotion_focused, :meaning_focused)
+  end
+end

data/spec/legion/extensions/appraisal/runners/appraisal_spec.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/appraisal/client'
+
+RSpec.describe Legion::Extensions::Appraisal::Runners::Appraisal do
+  let(:client) { Legion::Extensions::Appraisal::Client.new }
+
+  let(:primary_joy)    { { relevance: 0.9, goal_congruence: 0.9, goal_importance: 0.8 } }
+  let(:primary_threat) { { relevance: 0.9, goal_congruence: 0.3, goal_importance: 0.8 } }
+  let(:secondary_low)  { { coping_potential: 0.2, control_expectation: 0.3, future_expectancy: 0.4 } }
+  let(:secondary_high) { { coping_potential: 0.8, control_expectation: 0.7, future_expectancy: 0.6 } }
+
+  describe '#appraise_event' do
+    it 'returns success: true with an appraisal' do
+      result = client.appraise_event(event: 'deadline', primary: primary_joy, secondary: secondary_high)
+      expect(result[:success]).to be(true)
+      expect(result[:appraisal]).to include(:id, :emotional_outcome)
+    end
+
+    it 'assigns emotional_outcome based on appraisal pattern' do
+      result = client.appraise_event(event: 'win', primary: primary_joy, secondary: secondary_high)
+      expect(result[:appraisal][:emotional_outcome]).to eq(:joy)
+    end
+
+    it 'accepts optional domain' do
+      result = client.appraise_event(event: 'test', primary: primary_joy, secondary: secondary_high,
+                                     domain: 'work')
+      expect(result[:appraisal][:domain]).to eq('work')
+    end
+  end
+
+  describe '#reappraise_event' do
+    it 'updates existing appraisal' do
+      appraisal_id = client.appraise_event(event: 'e', primary: primary_threat,
+                                           secondary: secondary_low)[:appraisal][:id]
+      result = client.reappraise_event(appraisal_id: appraisal_id, new_primary: primary_joy,
+                                       new_secondary: secondary_high)
+      expect(result[:success]).to be(true)
+      expect(result[:appraisal][:reappraised]).to be(true)
+    end
+
+    it 'returns failure for unknown id' do
+      result = client.reappraise_event(appraisal_id: 'unknown', new_primary: primary_joy,
+                                       new_secondary: secondary_high)
+      expect(result[:success]).to be(false)
+      expect(result[:error]).to include('not found')
+    end
+  end
+
+  describe '#select_coping_strategy' do
+    it 'assigns a coping strategy to the appraisal' do
+      appraisal_id = client.appraise_event(event: 'e', primary: primary_threat,
+                                           secondary: secondary_low)[:appraisal][:id]
+      result = client.select_coping_strategy(appraisal_id: appraisal_id, coping_type: :problem_focused)
+      expect(result[:success]).to be(true)
+      expect(result[:appraisal][:coping_strategy]).not_to be_nil
+    end
+
+    it 'returns failure for unknown appraisal' do
+      result = client.select_coping_strategy(appraisal_id: 'unknown', coping_type: :problem_focused)
+      expect(result[:success]).to be(false)
+    end
+  end
+
+  describe '#add_coping_strategy' do
+    it 'registers a strategy' do
+      result = client.add_coping_strategy(name: 'journaling', coping_type: :emotion_focused,
+                                          effectiveness: 0.75)
+      expect(result[:success]).to be(true)
+      expect(result[:name]).to eq('journaling')
+    end
+  end
+
+  describe '#evaluate_coping' do
+    it 'returns effectiveness for an appraisal with coping' do
+      client.add_coping_strategy(name: 'breathing', coping_type: :emotion_focused, effectiveness: 0.8)
+      appraisal_id = client.appraise_event(event: 'e', primary: primary_threat,
+                                           secondary: secondary_low)[:appraisal][:id]
+      client.select_coping_strategy(appraisal_id: appraisal_id, coping_type: :emotion_focused)
+      result = client.evaluate_coping(appraisal_id: appraisal_id)
+      expect(result[:success]).to be(true)
+      expect(result[:effectiveness]).to be_a(Float)
+    end
+  end
+
+  describe '#emotional_pattern' do
+    it 'returns success with pattern hash' do
+      client.appraise_event(event: 'a', primary: primary_joy, secondary: secondary_high)
+      client.appraise_event(event: 'b', primary: primary_joy, secondary: secondary_high)
+      result = client.emotional_pattern
+      expect(result[:success]).to be(true)
+      expect(result[:pattern]).to be_a(Hash)
+      expect(result[:pattern][:joy]).to eq(2)
+    end
+  end
+
+  describe '#update_appraisal' do
+    it 'runs decay and returns success' do
+      client.appraise_event(event: 'e', primary: primary_joy, secondary: secondary_high)
+      result = client.update_appraisal
+      expect(result[:success]).to be(true)
+    end
+  end
+
+  describe '#appraisal_stats' do
+    it 'returns stats hash with totals' do
+      client.appraise_event(event: 'a', primary: primary_joy,    secondary: secondary_high)
+      client.appraise_event(event: 'b', primary: primary_threat, secondary: secondary_low)
+      result = client.appraisal_stats
+      expect(result[:success]).to be(true)
+      expect(result[:total]).to eq(2)
+      expect(result[:unresolved]).to eq(2)
+      expect(result[:history_size]).to be >= 2
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,24 @@
+# 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
+
+  module Extensions
+    module Core; end
+  end
+end
+
+require 'legion/extensions/appraisal'
+
+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,77 @@
+--- !ruby/object:Gem::Specification
+name: lex-appraisal
+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: Lazarus's Cognitive Appraisal Theory for brain-modeled agentic AI
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE
+- README.md
+- lex-appraisal.gemspec
+- lib/legion/extensions/appraisal.rb
+- lib/legion/extensions/appraisal/client.rb
+- lib/legion/extensions/appraisal/helpers/appraisal.rb
+- lib/legion/extensions/appraisal/helpers/appraisal_engine.rb
+- lib/legion/extensions/appraisal/helpers/constants.rb
+- lib/legion/extensions/appraisal/runners/appraisal.rb
+- lib/legion/extensions/appraisal/version.rb
+- spec/legion/extensions/appraisal/client_spec.rb
+- spec/legion/extensions/appraisal/helpers/appraisal_engine_spec.rb
+- spec/legion/extensions/appraisal/helpers/appraisal_spec.rb
+- spec/legion/extensions/appraisal/helpers/constants_spec.rb
+- spec/legion/extensions/appraisal/runners/appraisal_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-appraisal
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-appraisal
+  source_code_uri: https://github.com/LegionIO/lex-appraisal
+  documentation_uri: https://github.com/LegionIO/lex-appraisal
+  changelog_uri: https://github.com/LegionIO/lex-appraisal
+  bug_tracker_uri: https://github.com/LegionIO/lex-appraisal/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 Appraisal
+test_files: []