lex-agentic-affect 0.1.0

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

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Affect
+        module Regulation
+          module Helpers
+            class RegulationModel
+              include Constants
+
+              attr_reader :skill, :consecutive_suppressions, :regulation_history
+
+              def initialize
+                @skill = STRATEGIES.to_h { |s| [s, DEFAULT_SKILL] }
+                @consecutive_suppressions = 0
+                @regulation_history = []
+              end
+
+              # Apply a regulation strategy to an emotion.
+              #
+              # Returns a hash with :regulated_magnitude, :cost, :success
+              def regulate(emotion_magnitude:, emotion_valence:, strategy:)
+                unless STRATEGIES.include?(strategy)
+                  return { regulated_magnitude: emotion_magnitude, cost: 0.0, success: false,
+                           reason: :unknown_strategy }
+                end
+
+                base_effectiveness = STRATEGY_EFFECTIVENESS[strategy]
+                base_cost          = STRATEGY_COST[strategy]
+                proficiency        = @skill[strategy]
+
+                # Proficiency scales effectiveness (skill of 1.0 adds 20% to base)
+                effective_reduction = base_effectiveness * (1.0 + (proficiency * 0.2))
+                effective_reduction = [effective_reduction, 1.0].min
+
+                # Suppression penalty: repeated suppression degrades its own effectiveness
+                effective_reduction = apply_suppression_penalty(strategy, effective_reduction)
+
+                regulated = (emotion_magnitude * (1.0 - effective_reduction)).clamp(0.0, 1.0)
+                actual_cost = base_cost * (1.0 - (proficiency * 0.3))
+
+                success = regulated < emotion_magnitude
+                update_skill(strategy, success: success)
+                track_suppression(strategy)
+                record_event({
+                               strategy:            strategy,
+                               emotion_magnitude:   emotion_magnitude,
+                               regulated_magnitude: regulated,
+                               cost:                actual_cost,
+                               emotion_valence:     emotion_valence,
+                               success:             success
+                             })
+
+                { regulated_magnitude: regulated, cost: actual_cost, success: success,
+                  strategy: strategy, proficiency: proficiency }
+              end
+
+              # Recommend the best strategy given current skills and context.
+              def recommend_strategy(emotion_magnitude:, emotion_valence:, context: :general)
+                scores = STRATEGIES.to_h do |strategy|
+                  [strategy, score_strategy(strategy, emotion_magnitude, emotion_valence, context)]
+                end
+
+                best = scores.max_by { |_, v| v }[0]
+                { recommended: best, scores: scores, context: context }
+              end
+
+              # Decay all skills toward DEFAULT_SKILL by SKILL_DECAY each tick.
+              def decay
+                @skill.each_key do |strategy|
+                  current = @skill[strategy]
+                  @skill[strategy] = if current > DEFAULT_SKILL
+                                       [current - SKILL_DECAY, DEFAULT_SKILL].max
+                                     else
+                                       [current + (SKILL_DECAY * 0.5), DEFAULT_SKILL].min
+                                     end
+                end
+              end
+
+              # Get proficiency for a specific strategy.
+              def skill_for(strategy)
+                @skill.fetch(strategy, DEFAULT_SKILL)
+              end
+
+              # Weighted average of all strategy skills.
+              # Effectiveness-weighted so higher-value strategies contribute more.
+              def overall_regulation_ability
+                total_weight = STRATEGIES.sum { |s| STRATEGY_EFFECTIVENESS[s] }
+                weighted_sum = STRATEGIES.sum { |s| @skill[s] * STRATEGY_EFFECTIVENESS[s] }
+                weighted_sum / total_weight
+              end
+
+              # Human-readable label for overall regulation ability.
+              def regulation_label
+                ability = overall_regulation_ability
+                REGULATION_LABELS.each do |range, label|
+                  return label if range.cover?(ability)
+                end
+                :reactive
+              end
+
+              def to_h
+                {
+                  skill:                    @skill.dup,
+                  consecutive_suppressions: @consecutive_suppressions,
+                  overall_ability:          overall_regulation_ability,
+                  regulation_label:         regulation_label,
+                  history_size:             @regulation_history.size
+                }
+              end
+
+              private
+
+              def score_strategy(strategy, emotion_magnitude, _emotion_valence, context)
+                effectiveness = STRATEGY_EFFECTIVENESS[strategy]
+                cost          = STRATEGY_COST[strategy]
+                proficiency   = @skill[strategy]
+
+                base_score = (effectiveness * 0.5) + (proficiency * 0.3) - (cost * 0.2)
+
+                # Reappraisal bonus — healthiest long-term strategy
+                base_score += REAPPRAISAL_BONUS if strategy == :cognitive_reappraisal
+
+                # In high-magnitude situations penalise situation_selection (too late to avoid)
+                base_score -= 0.15 if strategy == :situation_selection && emotion_magnitude > 0.7
+
+                # Suppression penalty in long-running contexts
+                if strategy == :response_suppression
+                  base_score -= 0.1 if context == :sustained
+                  base_score -= ([@consecutive_suppressions, SUPPRESSION_PENALTY_THRESHOLD].min * 0.03)
+                end
+
+                base_score
+              end
+
+              def apply_suppression_penalty(strategy, effectiveness)
+                return effectiveness unless strategy == :response_suppression
+                return effectiveness if @consecutive_suppressions < SUPPRESSION_PENALTY_THRESHOLD
+
+                excess = @consecutive_suppressions - SUPPRESSION_PENALTY_THRESHOLD
+                penalty = [excess * 0.05, 0.2].min
+                [effectiveness - penalty, 0.05].max
+              end
+
+              def update_skill(strategy, success:)
+                current = @skill[strategy]
+                if success
+                  bonus = strategy == :cognitive_reappraisal ? SKILL_GAIN * 1.2 : SKILL_GAIN
+                  @skill[strategy] = [current + bonus, 1.0].min
+                else
+                  @skill[strategy] = [current - (SKILL_GAIN * 0.5), 0.0].max
+                end
+              end
+
+              def track_suppression(strategy)
+                if strategy == :response_suppression
+                  @consecutive_suppressions += 1
+                else
+                  @consecutive_suppressions = 0
+                end
+              end
+
+              def record_event(data)
+                event = data.merge(timestamp: Time.now.utc)
+                @regulation_history << event
+                @regulation_history.shift while @regulation_history.size > MAX_REGULATION_HISTORY
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/affect/regulation/runners/emotional_regulation.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Affect
+        module Regulation
+          module Runners
+            module EmotionalRegulation
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              # Apply emotion regulation. Auto-selects strategy when none is provided.
+              def regulate_emotion(emotion_magnitude:, emotion_valence: :neutral, strategy: nil, **)
+                chosen = strategy || regulation_model.recommend_strategy(
+                  emotion_magnitude: emotion_magnitude,
+                  emotion_valence:   emotion_valence
+                )[:recommended]
+
+                result = regulation_model.regulate(
+                  emotion_magnitude: emotion_magnitude,
+                  emotion_valence:   emotion_valence,
+                  strategy:          chosen
+                )
+
+                Legion::Logging.debug "[emotional_regulation] regulate: strategy=#{chosen} " \
+                                      "magnitude=#{emotion_magnitude.round(2)} -> " \
+                                      "#{result[:regulated_magnitude].round(2)} " \
+                                      "cost=#{result[:cost].round(3)} success=#{result[:success]}"
+
+                { success: true }.merge(result)
+              end
+
+              # Return a strategy recommendation without applying it.
+              def recommend_strategy(emotion_magnitude:, emotion_valence: :neutral, context: :general, **)
+                result = regulation_model.recommend_strategy(
+                  emotion_magnitude: emotion_magnitude,
+                  emotion_valence:   emotion_valence,
+                  context:           context
+                )
+
+                Legion::Logging.debug "[emotional_regulation] recommend: magnitude=#{emotion_magnitude.round(2)} " \
+                                      "context=#{context} recommended=#{result[:recommended]}"
+
+                { success: true }.merge(result)
+              end
+
+              # Per-tick skill decay — call from scheduler or tick actor.
+              def update_emotional_regulation(**)
+                regulation_model.decay
+                ability = regulation_model.overall_regulation_ability
+                label   = regulation_model.regulation_label
+
+                Legion::Logging.debug "[emotional_regulation] decay tick: ability=#{ability.round(3)} label=#{label}"
+
+                { success: true, overall_ability: ability, regulation_label: label }
+              end
+
+              # Return the full skill profile across all strategies.
+              def regulation_profile(**)
+                profile = Helpers::Constants::STRATEGIES.to_h do |strategy|
+                  [strategy, regulation_model.skill_for(strategy)]
+                end
+
+                Legion::Logging.debug "[emotional_regulation] profile query: overall=#{regulation_model.overall_regulation_ability.round(3)}"
+
+                {
+                  success:      true,
+                  skills:       profile,
+                  overall:      regulation_model.overall_regulation_ability,
+                  label:        regulation_model.regulation_label,
+                  suppressions: regulation_model.consecutive_suppressions
+                }
+              end
+
+              # Return recent regulation events.
+              def regulation_history(count: 20, **)
+                events = regulation_model.regulation_history.last(count)
+                Legion::Logging.debug "[emotional_regulation] history: requested=#{count} returned=#{events.size}"
+                { success: true, events: events, count: events.size }
+              end
+
+              # Return aggregate statistics about regulation performance.
+              def emotional_regulation_stats(**)
+                history = regulation_model.regulation_history
+                total   = history.size
+
+                if total.zero?
+                  return { success: true, total_events: 0, success_rate: 0.0,
+                           average_cost: 0.0, strategy_breakdown: {},
+                           overall_ability: regulation_model.overall_regulation_ability,
+                           regulation_label: regulation_model.regulation_label }
+                end
+
+                successes  = history.count { |e| e[:success] }
+                total_cost = history.sum { |e| e[:cost] }
+
+                strategy_breakdown = Helpers::Constants::STRATEGIES.to_h do |strategy|
+                  events = history.select { |e| e[:strategy] == strategy }
+                  [strategy, { count: events.size, successes: events.count { |e| e[:success] } }]
+                end
+
+                Legion::Logging.debug "[emotional_regulation] stats: total=#{total} success_rate=#{(successes.to_f / total).round(2)}"
+
+                {
+                  success:            true,
+                  total_events:       total,
+                  success_rate:       successes.to_f / total,
+                  average_cost:       total_cost / total,
+                  strategy_breakdown: strategy_breakdown,
+                  overall_ability:    regulation_model.overall_regulation_ability,
+                  regulation_label:   regulation_model.regulation_label
+                }
+              end
+
+              private
+
+              def regulation_model
+                @regulation_model ||= Helpers::RegulationModel.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/affect/regulation/version'
+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'
+require 'legion/extensions/agentic/affect/regulation/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Affect
+        module Regulation
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/affect/resilience/helpers/constants'
+require 'legion/extensions/agentic/affect/resilience/helpers/adversity_tracker'
+require 'legion/extensions/agentic/affect/resilience/helpers/resilience_model'
+require 'legion/extensions/agentic/affect/resilience/runners/resilience'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Affect
+        module Resilience
+          class Client
+            include Runners::Resilience
+
+            attr_reader :adversity_tracker, :resilience_model
+
+            def initialize(adversity_tracker: nil, resilience_model: nil, **)
+              @adversity_tracker = adversity_tracker || Helpers::AdversityTracker.new
+              @resilience_model = resilience_model || Helpers::ResilienceModel.new
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/affect/resilience/helpers/adversity_tracker.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Affect
+        module Resilience
+          module Helpers
+            class AdversityTracker
+              attr_reader :active_adversities, :resolved_adversities, :consecutive_recoveries
+
+              def initialize
+                @active_adversities = []
+                @resolved_adversities = []
+                @consecutive_recoveries = 0
+                @adversity_counter = 0
+              end
+
+              def register(type:, severity:, context: {})
+                return nil unless Constants::ADVERSITY_TYPES.include?(type)
+                return nil unless Constants::SEVERITY_LEVELS.key?(severity)
+
+                @adversity_counter += 1
+                severity_config = Constants::SEVERITY_LEVELS[severity]
+
+                adversity = {
+                  id:              @adversity_counter,
+                  type:            type,
+                  severity:        severity,
+                  impact:          severity_config[:impact],
+                  expected_ticks:  severity_config[:recovery_ticks],
+                  phase:           :absorbing,
+                  health_at_onset: 1.0,
+                  current_health:  1.0 - severity_config[:impact],
+                  ticks_elapsed:   0,
+                  context:         context,
+                  registered_at:   Time.now.utc
+                }
+
+                @active_adversities << adversity
+                trim_active
+                adversity
+              end
+
+              def tick_recovery
+                @active_adversities.each do |adv|
+                  adv[:ticks_elapsed] += 1
+                  advance_phase(adv)
+                  recover_health(adv)
+                end
+
+                newly_resolved = @active_adversities.select { |a| a[:current_health] >= Constants::RECOVERY_THRESHOLD }
+                newly_resolved.each { |a| resolve(a) }
+
+                {
+                  active_count:   @active_adversities.size,
+                  resolved_count: newly_resolved.size,
+                  worst_health:   worst_health
+                }
+              end
+
+              def worst_health
+                return 1.0 if @active_adversities.empty?
+
+                @active_adversities.map { |a| a[:current_health] }.min
+              end
+
+              def active_by_type
+                @active_adversities.group_by { |a| a[:type] }.transform_values(&:size)
+              end
+
+              def recovery_rate
+                total = @resolved_adversities.size
+                return 0.0 if total.zero?
+
+                on_time = @resolved_adversities.count { |a| a[:ticks_elapsed] <= a[:expected_ticks] }
+                on_time.to_f / total
+              end
+
+              def average_recovery_speed
+                return 0.0 if @resolved_adversities.empty?
+
+                ratios = @resolved_adversities.map { |a| a[:ticks_elapsed].to_f / [a[:expected_ticks], 1].max }
+                ratios.sum / ratios.size.to_f
+              end
+
+              def total_adversities
+                @active_adversities.size + @resolved_adversities.size
+              end
+
+              private
+
+              def advance_phase(adv)
+                progress = adv[:current_health]
+                adv[:phase] = if progress < 0.3
+                                :absorbing
+                              elsif progress < 0.6
+                                :adapting
+                              elsif progress < Constants::RECOVERY_THRESHOLD
+                                :recovering
+                              else
+                                :thriving
+                              end
+              end
+
+              def recover_health(adv)
+                recovery_rate = 1.0 / [adv[:expected_ticks], 1].max
+                adv[:current_health] = [adv[:current_health] + recovery_rate, 1.0].min
+              end
+
+              def resolve(adv)
+                adv[:phase] = :thriving
+                adv[:resolved_at] = Time.now.utc
+                @active_adversities.delete(adv)
+                @resolved_adversities << adv
+                @resolved_adversities.shift while @resolved_adversities.size > Constants::MAX_RESILIENCE_HISTORY
+
+                @consecutive_recoveries += 1
+              end
+
+              def trim_active
+                @active_adversities.shift while @active_adversities.size > Constants::MAX_ACTIVE_ADVERSITIES
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Affect
+        module Resilience
+          module Helpers
+            module Constants
+              # Adversity types the resilience system tracks
+              ADVERSITY_TYPES = %i[
+                prediction_failure
+                trust_violation
+                conflict_escalation
+                resource_depletion
+                communication_failure
+                goal_failure
+                emotional_shock
+                system_error
+              ].freeze
+
+              # Recovery phases (Masten's resilience model)
+              RECOVERY_PHASES = %i[
+                absorbing
+                adapting
+                recovering
+                thriving
+              ].freeze
+
+              # Resilience dimensions
+              DIMENSIONS = {
+                elasticity:   { description: 'Speed of recovery to baseline', weight: 0.30 },
+                robustness:   { description: 'Resistance to initial disruption', weight: 0.25 },
+                adaptability: { description: 'Capacity to adjust strategy', weight: 0.25 },
+                growth:       { description: 'Ability to improve from adversity', weight: 0.20 }
+              }.freeze
+
+              # EMA alpha for resilience dimension tracking
+              RESILIENCE_ALPHA = 0.08
+
+              # Growth bonus per successful recovery
+              GROWTH_INCREMENT = 0.02
+
+              # Maximum growth bonus (anti-fragile ceiling)
+              MAX_GROWTH_BONUS = 0.3
+
+              # Adversity severity levels
+              SEVERITY_LEVELS = {
+                minor:    { impact: 0.1, recovery_ticks: 5 },
+                moderate: { impact: 0.3, recovery_ticks: 15 },
+                major:    { impact: 0.5, recovery_ticks: 30 },
+                severe:   { impact: 0.8, recovery_ticks: 60 },
+                critical: { impact: 1.0, recovery_ticks: 100 }
+              }.freeze
+
+              # Threshold for considering recovery complete
+              RECOVERY_THRESHOLD = 0.9
+
+              # Maximum active adversity events tracked
+              MAX_ACTIVE_ADVERSITIES = 20
+
+              # History cap
+              MAX_RESILIENCE_HISTORY = 200
+
+              # Fragility threshold — below this, the system is fragile
+              FRAGILITY_THRESHOLD = 0.3
+
+              # Anti-fragility threshold — above this, the system grows from stress
+              ANTIFRAGILITY_THRESHOLD = 0.7
+
+              # Consecutive recoveries needed to boost growth dimension
+              GROWTH_TRIGGER = 3
+            end
+          end
+        end
+      end
+    end
+  end
+end