lex-agentic-affect 0.1.0

data/lib/legion/extensions/agentic/affect/reappraisal/helpers/llm_enhancer.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Affect
+        module Reappraisal
+          module Helpers
+            module LlmEnhancer
+              SYSTEM_PROMPT = <<~PROMPT
+                You are the emotion regulation processor for an autonomous AI agent built on LegionIO.
+                You practice cognitive reappraisal — re-interpreting emotional events to change their impact.
+                Generate genuine, psychologically-grounded re-framings. Be specific to the event content.
+                Do not dismiss or minimize. Reframe with depth and insight.
+              PROMPT
+
+              module_function
+
+              def available?
+                !!(defined?(Legion::LLM) && Legion::LLM.respond_to?(:started?) && Legion::LLM.started?)
+              rescue StandardError
+                false
+              end
+
+              def generate_reappraisal(event_content:, initial_appraisal:, strategy:, valence:, intensity:)
+                prompt = build_generate_reappraisal_prompt(
+                  event_content:     event_content,
+                  initial_appraisal: initial_appraisal,
+                  strategy:          strategy,
+                  valence:           valence,
+                  intensity:         intensity
+                )
+                response = llm_ask(prompt)
+                parse_generate_reappraisal_response(response)
+              rescue StandardError => e
+                Legion::Logging.warn "[cognitive_reappraisal:llm] generate_reappraisal failed: #{e.message}"
+                nil
+              end
+
+              def llm_ask(prompt)
+                chat = Legion::LLM.chat
+                chat.with_instructions(SYSTEM_PROMPT)
+                chat.ask(prompt)
+              end
+              private_class_method :llm_ask
+
+              def build_generate_reappraisal_prompt(event_content:, initial_appraisal:, strategy:, valence:, intensity:)
+                <<~PROMPT
+                  An emotional event needs cognitive reappraisal.
+
+                  EVENT: #{event_content}
+                  CURRENT APPRAISAL: #{initial_appraisal}
+                  VALENCE: #{valence} (negative = aversive, positive = pleasant)
+                  INTENSITY: #{intensity} (0-1, how activating)
+                  STRATEGY: #{strategy}
+
+                  Strategy guidelines:
+                  - reinterpretation: re-frame the meaning of the event
+                  - distancing: create psychological distance from the event
+                  - benefit_finding: identify positive outcomes or growth opportunities
+                  - normalizing: recognize this as a common experience
+                  - perspective_taking: view from another agent's or future self's perspective
+                  - temporal_distancing: project forward — how will this matter in a week/month?
+
+                  Generate a specific, insightful reappraisal using the given strategy.
+
+                  Format EXACTLY as:
+                  REAPPRAISAL: <1-2 sentence reappraisal that applies the strategy to this specific event>
+                PROMPT
+              end
+              private_class_method :build_generate_reappraisal_prompt
+
+              def parse_generate_reappraisal_response(response)
+                return nil unless response&.content
+
+                match = response.content.match(/REAPPRAISAL:\s*(.+)/im)
+                return nil unless match
+
+                { new_appraisal: match.captures.first.strip }
+              end
+              private_class_method :parse_generate_reappraisal_response
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/affect/reappraisal/helpers/reappraisal_engine.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Affect
+        module Reappraisal
+          module Helpers
+            class ReappraisalEngine
+              include Constants
+
+              attr_reader :events, :reappraisal_log
+
+              def initialize
+                @events          = {}
+                @reappraisal_log = []
+              end
+
+              def register_event(content:, valence:, intensity:, appraisal:)
+                event = EmotionalEvent.new(
+                  content:   content,
+                  valence:   valence,
+                  intensity: intensity,
+                  appraisal: appraisal
+                )
+
+                @events.shift while @events.size >= Constants::MAX_EVENTS
+                @events[event.id] = event
+                event
+              end
+
+              def reappraise(event_id:, strategy:, new_appraisal:)
+                event = @events[event_id]
+                return { success: false, reason: :event_not_found } unless event
+                return { success: false, reason: :invalid_strategy } unless Constants.valid_strategy?(strategy)
+
+                old_valence   = event.current_valence
+                old_intensity = event.current_intensity
+
+                change = event.reappraise!(strategy: strategy, new_appraisal: new_appraisal)
+
+                log_entry = {
+                  event_id:         event_id,
+                  strategy:         strategy,
+                  valence_change:   (event.current_valence - old_valence).round(10),
+                  intensity_change: (old_intensity - event.current_intensity).round(10),
+                  applied_at:       Time.now.utc
+                }
+
+                @reappraisal_log.shift while @reappraisal_log.size >= Constants::MAX_REAPPRAISALS
+                @reappraisal_log << log_entry
+
+                {
+                  success:           true,
+                  event_id:          event_id,
+                  strategy:          strategy,
+                  change:            change.round(10),
+                  current_valence:   event.current_valence.round(10),
+                  current_intensity: event.current_intensity.round(10)
+                }
+              end
+
+              def auto_reappraise(event_id:)
+                event = @events[event_id]
+                return { success: false, reason: :event_not_found } unless event
+
+                strategy = select_strategy(event)
+                new_appraisal = "auto-reappraised via #{strategy}"
+                reappraise(event_id: event_id, strategy: strategy, new_appraisal: new_appraisal)
+              end
+
+              def negative_events
+                @events.values.select(&:negative?)
+              end
+
+              def intense_events
+                @events.values.select(&:intense?)
+              end
+
+              def most_regulated(limit: 5)
+                @events.values
+                       .sort_by { |e| -e.regulation_amount }
+                       .first(limit)
+              end
+
+              def strategy_effectiveness
+                grouped = @reappraisal_log.group_by { |entry| entry[:strategy] }
+                grouped.transform_values do |entries|
+                  changes = entries.map { |e| e[:valence_change] }
+                  changes.sum.to_f / changes.size
+                end
+              end
+
+              def average_regulation
+                return 0.0 if @events.empty?
+
+                total = @events.values.sum(&:regulation_amount)
+                (total / @events.size).round(10)
+              end
+
+              def overall_regulation_ability
+                return 0.0 if @events.empty?
+
+                regulated_count = @events.values.count { |e| e.regulation_amount > 0.0 }
+                mean_reg        = average_regulation
+                coverage        = regulated_count.to_f / @events.size
+
+                ((mean_reg + coverage) / 2.0).round(10)
+              end
+
+              def reappraisal_report
+                {
+                  total_events:               @events.size,
+                  total_reappraisals:         @reappraisal_log.size,
+                  negative_events:            negative_events.size,
+                  intense_events:             intense_events.size,
+                  average_regulation:         average_regulation,
+                  overall_regulation_ability: overall_regulation_ability,
+                  strategy_effectiveness:     strategy_effectiveness,
+                  most_regulated:             most_regulated(limit: 3).map(&:to_h)
+                }
+              end
+
+              def to_h
+                {
+                  events:                     @events.transform_values(&:to_h),
+                  reappraisal_log:            @reappraisal_log,
+                  average_regulation:         average_regulation,
+                  overall_regulation_ability: overall_regulation_ability,
+                  strategy_effectiveness:     strategy_effectiveness
+                }
+              end
+
+              private
+
+              def select_strategy(event)
+                if event.negative? && event.intense?
+                  :distancing
+                elsif event.negative?
+                  :reinterpretation
+                elsif event.intense?
+                  :temporal_distancing
+                else
+                  :benefit_finding
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/affect/reappraisal/runners/cognitive_reappraisal.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Affect
+        module Reappraisal
+          module Runners
+            module CognitiveReappraisal
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def register_event(content:, valence:, intensity:, appraisal:, engine: nil, **)
+                eng = engine || reappraisal_engine
+                event = eng.register_event(content: content, valence: valence, intensity: intensity, appraisal: appraisal)
+
+                Legion::Logging.debug "[cognitive_reappraisal] registered event id=#{event.id[0..7]} " \
+                                      "valence=#{event.initial_valence.round(2)} intensity=#{event.initial_intensity.round(2)}"
+
+                {
+                  success:   true,
+                  event_id:  event.id,
+                  valence:   event.initial_valence.round(10),
+                  intensity: event.initial_intensity.round(10),
+                  negative:  event.negative?,
+                  intense:   event.intense?
+                }
+              end
+
+              def reappraise_event(event_id:, strategy:, new_appraisal:, engine: nil, **)
+                unless Helpers::Constants.valid_strategy?(strategy)
+                  return { success: false, reason: :invalid_strategy, valid_strategies: Helpers::Constants::STRATEGIES }
+                end
+
+                eng = engine || reappraisal_engine
+                appraisal = llm_appraisal_for(eng.events[event_id], strategy) || new_appraisal
+                result = eng.reappraise(event_id: event_id, strategy: strategy, new_appraisal: appraisal)
+
+                if result[:success]
+                  Legion::Logging.info "[cognitive_reappraisal] reappraised event=#{event_id[0..7]} " \
+                                       "strategy=#{strategy} change=#{result[:change].round(2)}"
+                else
+                  Legion::Logging.debug "[cognitive_reappraisal] reappraisal failed event=#{event_id[0..7]} reason=#{result[:reason]}"
+                end
+
+                result
+              end
+
+              def auto_reappraise_event(event_id:, engine: nil, **)
+                eng   = engine || reappraisal_engine
+                event = eng.events[event_id]
+                return { success: false, reason: :event_not_found } unless event
+
+                strategy  = select_strategy_for(event)
+                appraisal = llm_appraisal_for(event, strategy) || "auto-reappraised via #{strategy}"
+                result    = eng.reappraise(event_id: event_id, strategy: strategy, new_appraisal: appraisal)
+
+                if result[:success]
+                  Legion::Logging.info "[cognitive_reappraisal] auto-reappraised event=#{event_id[0..7]} " \
+                                       "strategy=#{strategy}"
+                else
+                  Legion::Logging.debug "[cognitive_reappraisal] auto-reappraisal failed: #{result[:reason]}"
+                end
+
+                result
+              end
+
+              def negative_events(engine: nil, **)
+                eng    = engine || reappraisal_engine
+                events = eng.negative_events
+                Legion::Logging.debug "[cognitive_reappraisal] negative events count=#{events.size}"
+                { events: events.map(&:to_h), count: events.size }
+              end
+
+              def intense_events(engine: nil, **)
+                eng    = engine || reappraisal_engine
+                events = eng.intense_events
+                Legion::Logging.debug "[cognitive_reappraisal] intense events count=#{events.size}"
+                { events: events.map(&:to_h), count: events.size }
+              end
+
+              def most_regulated_events(limit: 5, engine: nil, **)
+                eng    = engine || reappraisal_engine
+                events = eng.most_regulated(limit: limit)
+                Legion::Logging.debug "[cognitive_reappraisal] most regulated count=#{events.size}"
+                { events: events.map(&:to_h), count: events.size }
+              end
+
+              def reappraisal_status(engine: nil, **)
+                eng = engine || reappraisal_engine
+                Legion::Logging.debug "[cognitive_reappraisal] status: overall=#{eng.overall_regulation_ability.round(2)}"
+                {
+                  overall_regulation_ability: eng.overall_regulation_ability,
+                  average_regulation:         eng.average_regulation,
+                  total_events:               eng.events.size,
+                  total_reappraisals:         eng.reappraisal_log.size,
+                  strategy_effectiveness:     eng.strategy_effectiveness
+                }
+              end
+
+              def reappraisal_report(engine: nil, **)
+                eng = engine || reappraisal_engine
+                Legion::Logging.debug '[cognitive_reappraisal] generating report'
+                { success: true, report: eng.reappraisal_report }
+              end
+
+              def regulate_pending_events(engine: nil, **)
+                eng       = engine || reappraisal_engine
+                events    = eng.events.values
+                checked   = events.size
+                regulated = 0
+                event_ids = []
+
+                events.each do |event|
+                  next unless event.negative? && event.reappraisal_count.zero?
+
+                  result = eng.auto_reappraise(event_id: event.id)
+                  next unless result[:success]
+
+                  regulated += 1
+                  event_ids << event.id
+                end
+
+                Legion::Logging.debug "[reappraisal] regulate pending: checked=#{checked} regulated=#{regulated}"
+                { checked: checked, regulated: regulated, event_ids: event_ids }
+              end
+
+              private
+
+              def reappraisal_engine
+                @reappraisal_engine ||= Helpers::ReappraisalEngine.new
+              end
+
+              def llm_appraisal_for(event, strategy)
+                return nil unless event && Helpers::LlmEnhancer.available?
+
+                result = Helpers::LlmEnhancer.generate_reappraisal(
+                  event_content:     event.content,
+                  initial_appraisal: event.appraisal,
+                  strategy:          strategy,
+                  valence:           event.current_valence,
+                  intensity:         event.current_intensity
+                )
+                result&.fetch(:new_appraisal, nil)
+              end
+
+              def select_strategy_for(event)
+                if event.negative? && event.intense?
+                  :distancing
+                elsif event.negative?
+                  :reinterpretation
+                elsif event.intense?
+                  :temporal_distancing
+                else
+                  :benefit_finding
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/affect/reappraisal/version.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Affect
+        module Reappraisal
+          VERSION = '0.1.1'
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/affect/reappraisal.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/affect/reappraisal/version'
+require 'legion/extensions/agentic/affect/reappraisal/helpers/constants'
+require 'legion/extensions/agentic/affect/reappraisal/helpers/emotional_event'
+require 'legion/extensions/agentic/affect/reappraisal/helpers/reappraisal_engine'
+require 'legion/extensions/agentic/affect/reappraisal/helpers/llm_enhancer'
+require 'legion/extensions/agentic/affect/reappraisal/runners/cognitive_reappraisal'
+require 'legion/extensions/agentic/affect/reappraisal/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Affect
+        module Reappraisal
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/affect/regulation/client.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/affect/regulation/helpers/constants'
+require 'legion/extensions/agentic/affect/regulation/helpers/regulation_model'
+require 'legion/extensions/agentic/affect/regulation/runners/emotional_regulation'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Affect
+        module Regulation
+          class Client
+            include Runners::EmotionalRegulation
+
+            attr_reader :regulation_model
+
+            def initialize(regulation_model: nil, **)
+              @regulation_model = regulation_model || Helpers::RegulationModel.new
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/affect/regulation/helpers/constants.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Affect
+        module Regulation
+          module Helpers
+            module Constants
+              STRATEGIES = %i[
+                situation_selection
+                situation_modification
+                attentional_deployment
+                cognitive_reappraisal
+                response_suppression
+              ].freeze
+
+              # How much each strategy reduces unwanted emotion magnitude (0..1)
+              STRATEGY_EFFECTIVENESS = {
+                situation_selection:    0.8,
+                situation_modification: 0.6,
+                attentional_deployment: 0.5,
+                cognitive_reappraisal:  0.7,
+                response_suppression:   0.3
+              }.freeze
+
+              # Cognitive/energetic cost of applying each strategy (0..1)
+              STRATEGY_COST = {
+                situation_selection:    0.1,
+                situation_modification: 0.2,
+                attentional_deployment: 0.15,
+                cognitive_reappraisal:  0.25,
+                response_suppression:   0.35
+              }.freeze
+
+              # EMA alpha for skill updating
+              REGULATION_ALPHA = 0.12
+
+              # Initial per-strategy proficiency
+              DEFAULT_SKILL = 0.3
+
+              # Improvement per successful regulated use
+              SKILL_GAIN = 0.05
+
+              # Per-tick decay toward DEFAULT_SKILL
+              SKILL_DECAY = 0.01
+
+              # Maximum regulation events retained in history
+              MAX_REGULATION_HISTORY = 200
+
+              # Consecutive suppression uses before a penalty applies
+              SUPPRESSION_PENALTY_THRESHOLD = 5
+
+              # Bonus applied to recommendation score when reappraisal is chosen
+              REAPPRAISAL_BONUS = 0.1
+
+              # Human-readable proficiency labels keyed by magnitude ranges
+              REGULATION_LABELS = {
+                (0.8..)     => :masterful,
+                (0.6...0.8) => :proficient,
+                (0.4...0.6) => :developing,
+                (0.2...0.4) => :novice,
+                (..0.2)     => :reactive
+              }.freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end