lex-agentic-affect 0.1.0

data/lib/legion/extensions/agentic/affect/fatigue/helpers/energy_model.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Affect
+        module Fatigue
+          module Helpers
+            class EnergyModel
+              include Constants
+
+              attr_reader :energy, :fatigue_level, :ticks_active, :ticks_resting,
+                          :consecutive_low_ticks, :burnout, :recovery_mode,
+                          :peak_energy, :history
+
+              def initialize
+                @energy                 = Constants::MAX_ENERGY
+                @fatigue_level          = :fresh
+                @ticks_active           = 0
+                @ticks_resting          = 0
+                @consecutive_low_ticks  = 0
+                @burnout                = false
+                @recovery_mode          = nil
+                @peak_energy            = Constants::MAX_ENERGY
+                @history                = []
+              end
+
+              def tick(cognitive_load: 0.5, emotional_arousal: 0.5, is_resting: false)
+                if is_resting
+                  recover
+                  @ticks_resting += 1
+                  @consecutive_low_ticks = 0
+                else
+                  drain(cognitive_load, emotional_arousal)
+                  @ticks_active += 1
+                  check_second_wind
+                end
+
+                @energy = @energy.clamp(Constants::MIN_ENERGY, Constants::MAX_ENERGY)
+                @peak_energy = @energy if @energy > @peak_energy
+                classify_fatigue
+                track_low_ticks
+                check_burnout
+                record_snapshot
+
+                to_h
+              end
+
+              def performance_factor
+                Constants::PERFORMANCE_DEGRADATION[@fatigue_level]
+              end
+
+              def needs_rest?
+                @energy < Constants::REST_THRESHOLD
+              end
+
+              def critically_fatigued?
+                @energy < Constants::CRITICAL_THRESHOLD
+              end
+
+              def burnout?
+                @burnout
+              end
+
+              def enter_recovery(mode)
+                return unless Constants::RECOVERY_MODES.include?(mode)
+
+                @recovery_mode = mode
+              end
+
+              def exit_recovery
+                @recovery_mode = nil
+              end
+
+              def time_to_rest_threshold
+                return 0 if needs_rest?
+
+                current_drain = effective_drain(0.5, 0.5)
+                return Float::INFINITY if current_drain <= 0.0
+
+                ((@energy - Constants::REST_THRESHOLD) / current_drain).ceil
+              end
+
+              def time_to_full_recovery
+                rate = @recovery_mode ? Constants::RECOVERY_RATES[@recovery_mode] : Constants::RESTING_RECOVERY_RATE
+                return 0 if @energy >= Constants::MAX_ENERGY
+                return Float::INFINITY if rate <= 0.0
+
+                ((Constants::MAX_ENERGY - @energy) / rate).ceil
+              end
+
+              def trend
+                return :stable if @history.size < 5
+
+                recent = @history.last(5).map { |s| s[:energy] }
+                delta = recent.last - recent.first
+                if delta > 0.01
+                  :recovering
+                elsif delta < -0.01
+                  :draining
+                else
+                  :stable
+                end
+              end
+
+              def to_h
+                {
+                  energy:                @energy.round(4),
+                  fatigue_level:         @fatigue_level,
+                  performance_factor:    performance_factor,
+                  needs_rest:            needs_rest?,
+                  critically_fatigued:   critically_fatigued?,
+                  burnout:               @burnout,
+                  recovery_mode:         @recovery_mode,
+                  peak_energy:           @peak_energy.round(4),
+                  ticks_active:          @ticks_active,
+                  ticks_resting:         @ticks_resting,
+                  consecutive_low_ticks: @consecutive_low_ticks,
+                  trend:                 trend,
+                  history_size:          @history.size
+                }
+              end
+
+              private
+
+              def effective_drain(cognitive_load, emotional_arousal)
+                cognitive_factor  = 1.0 + ((cognitive_load - 0.5) * Constants::COGNITIVE_DRAIN_MULTIPLIER)
+                emotional_factor  = 1.0 + ([0.0, emotional_arousal - 0.5].max * Constants::EMOTIONAL_DRAIN_MULTIPLIER)
+                Constants::ACTIVE_DRAIN_RATE * cognitive_factor * emotional_factor
+              end
+
+              def drain(cognitive_load, emotional_arousal)
+                @energy -= effective_drain(cognitive_load, emotional_arousal)
+              end
+
+              def recover
+                rate = @recovery_mode ? Constants::RECOVERY_RATES[@recovery_mode] : Constants::RESTING_RECOVERY_RATE
+                @energy += rate
+              end
+
+              def classify_fatigue
+                @fatigue_level = Constants::FATIGUE_LEVELS.each_key.find do |level|
+                  @energy >= Constants::FATIGUE_LEVELS[level]
+                end || :depleted
+              end
+
+              def track_low_ticks
+                if needs_rest?
+                  @consecutive_low_ticks += 1
+                else
+                  @consecutive_low_ticks = 0
+                end
+              end
+
+              def check_second_wind
+                return unless @fatigue_level == :tired
+                return unless rand < Constants::SECOND_WIND_CHANCE
+
+                @energy = [@energy + 0.1, Constants::MAX_ENERGY].min
+              end
+
+              def check_burnout
+                @burnout = true if @consecutive_low_ticks > Constants::BURNOUT_THRESHOLD
+              end
+
+              def record_snapshot
+                @history << {
+                  energy:        @energy.round(4),
+                  fatigue_level: @fatigue_level,
+                  performance:   performance_factor,
+                  at:            Time.now.utc
+                }
+                @history.shift if @history.size > Constants::MAX_HISTORY
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/affect/fatigue/helpers/fatigue_store.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Affect
+        module Fatigue
+          module Helpers
+            class FatigueStore
+              include Constants
+
+              attr_reader :model, :session_start, :peak_performance_streak,
+                          :total_rest_ticks, :total_active_ticks
+
+              def initialize(model: nil)
+                @model                  = model || EnergyModel.new
+                @session_start          = Time.now.utc
+                @peak_performance_streak = 0
+                @total_rest_ticks       = 0
+                @total_active_ticks     = 0
+                @current_streak         = 0
+              end
+
+              def update(tick_results: {})
+                cognitive_load    = tick_results[:cognitive_load] || 0.5
+                emotional_arousal = tick_results[:emotional_arousal] || 0.5
+                is_resting        = tick_results[:mode] == :resting || !@model.recovery_mode.nil?
+
+                result = @model.tick(
+                  cognitive_load:    cognitive_load,
+                  emotional_arousal: emotional_arousal,
+                  is_resting:        is_resting
+                )
+
+                if is_resting
+                  @total_rest_ticks += 1
+                else
+                  @total_active_ticks += 1
+                end
+
+                update_streak(result[:performance_factor])
+                result
+              end
+
+              def recommend_action
+                energy = @model.energy
+
+                if @model.burnout?
+                  :emergency_shutdown
+                elsif energy < Constants::CRITICAL_THRESHOLD
+                  :enter_rest
+                elsif @model.needs_rest?
+                  :take_break
+                elsif @model.fatigue_level == :tired
+                  :reduce_load
+                else
+                  :continue
+                end
+              end
+
+              def session_stats
+                total_ticks = @total_active_ticks + @total_rest_ticks
+                duration = Time.now.utc - @session_start
+
+                {
+                  duration_seconds:        duration.round(2),
+                  total_ticks:             total_ticks,
+                  active_ticks:            @total_active_ticks,
+                  rest_ticks:              @total_rest_ticks,
+                  active_ratio:            total_ticks.positive? ? (@total_active_ticks.to_f / total_ticks).round(4) : 0.0,
+                  current_energy:          @model.energy.round(4),
+                  fatigue_level:           @model.fatigue_level,
+                  burnout:                 @model.burnout?,
+                  peak_performance_streak: @peak_performance_streak
+                }
+              end
+
+              def energy_forecast(ticks:)
+                current    = @model.energy
+                drain_rate = Constants::ACTIVE_DRAIN_RATE
+                projected  = []
+
+                ticks.times do |i|
+                  projected_energy = (current - (drain_rate * (i + 1))).clamp(Constants::MIN_ENERGY, Constants::MAX_ENERGY)
+                  level = classify_level(projected_energy)
+                  projected << {
+                    tick:          i + 1,
+                    energy:        projected_energy.round(4),
+                    fatigue_level: level
+                  }
+                end
+
+                {
+                  current_energy: current.round(4),
+                  forecast:       projected,
+                  ticks_to_rest:  @model.time_to_rest_threshold
+                }
+              end
+
+              def optimal_rest_schedule
+                ticks_until_rest = @model.time_to_rest_threshold
+                ticks_to_recover = @model.time_to_full_recovery
+
+                {
+                  recommend_rest_in:   ticks_until_rest,
+                  full_recovery_ticks: ticks_to_recover,
+                  current_energy:      @model.energy.round(4),
+                  recommended_mode:    suggest_recovery_mode,
+                  trend:               @model.trend
+                }
+              end
+
+              private
+
+              def classify_level(energy)
+                Constants::FATIGUE_LEVELS.each_key.find do |level|
+                  energy >= Constants::FATIGUE_LEVELS[level]
+                end || :depleted
+              end
+
+              def update_streak(performance_factor)
+                if performance_factor >= Constants::PERFORMANCE_DEGRADATION[:fresh]
+                  @current_streak += 1
+                  @peak_performance_streak = @current_streak if @current_streak > @peak_performance_streak
+                else
+                  @current_streak = 0
+                end
+              end
+
+              def suggest_recovery_mode
+                energy = @model.energy
+                if energy < Constants::CRITICAL_THRESHOLD
+                  :sleep
+                elsif energy < Constants::REST_THRESHOLD
+                  :full_rest
+                else
+                  :active_rest
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/affect/fatigue/runners/fatigue.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Affect
+        module Fatigue
+          module Runners
+            module Fatigue
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def update_fatigue(tick_results: {}, **)
+                result = fatigue_store.update(tick_results: tick_results)
+                recommendation = fatigue_store.recommend_action
+
+                Legion::Logging.debug "[fatigue] tick: energy=#{result[:energy]} level=#{result[:fatigue_level]} " \
+                                      "perf=#{result[:performance_factor]} rec=#{recommendation}"
+
+                {
+                  energy:             result[:energy],
+                  fatigue_level:      result[:fatigue_level],
+                  performance_factor: result[:performance_factor],
+                  recommendation:     recommendation,
+                  needs_rest:         result[:needs_rest],
+                  burnout:            result[:burnout]
+                }
+              end
+
+              def energy_status(**)
+                model = fatigue_store.model
+                Legion::Logging.debug "[fatigue] status: energy=#{model.energy.round(3)} level=#{model.fatigue_level}"
+
+                {
+                  energy:              model.energy.round(4),
+                  fatigue_level:       model.fatigue_level,
+                  performance_factor:  model.performance_factor,
+                  needs_rest:          model.needs_rest?,
+                  critically_fatigued: model.critically_fatigued?,
+                  burnout:             model.burnout?,
+                  recovery_mode:       model.recovery_mode,
+                  trend:               model.trend
+                }
+              end
+
+              def enter_rest(mode: :full_rest, **)
+                return { success: false, error: "unknown recovery mode: #{mode}" } unless Helpers::Constants::RECOVERY_MODES.include?(mode)
+
+                fatigue_store.model.enter_recovery(mode)
+                Legion::Logging.info "[fatigue] entered recovery mode=#{mode}"
+                { success: true, mode: mode, energy: fatigue_store.model.energy.round(4) }
+              end
+
+              def exit_rest(**)
+                fatigue_store.model.exit_recovery
+                Legion::Logging.info '[fatigue] exited recovery mode'
+                { success: true, energy: fatigue_store.model.energy.round(4), fatigue_level: fatigue_store.model.fatigue_level }
+              end
+
+              def energy_forecast(ticks: 50, **)
+                Legion::Logging.debug "[fatigue] forecasting #{ticks} ticks"
+                fatigue_store.energy_forecast(ticks: ticks)
+              end
+
+              def fatigue_stats(**)
+                stats  = fatigue_store.session_stats
+                model  = fatigue_store.model
+                Legion::Logging.debug "[fatigue] stats: ticks=#{stats[:total_ticks]} burnout=#{stats[:burnout]}"
+
+                {
+                  session:  stats,
+                  history:  model.history.last(10),
+                  trend:    model.trend,
+                  schedule: fatigue_store.optimal_rest_schedule
+                }
+              end
+
+              private
+
+              def fatigue_store
+                @fatigue_store ||= Helpers::FatigueStore.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/affect/fatigue/version'
+require 'legion/extensions/agentic/affect/fatigue/helpers/constants'
+require 'legion/extensions/agentic/affect/fatigue/helpers/energy_model'
+require 'legion/extensions/agentic/affect/fatigue/helpers/fatigue_store'
+require 'legion/extensions/agentic/affect/fatigue/runners/fatigue'
+require 'legion/extensions/agentic/affect/fatigue/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Affect
+        module Fatigue
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Affect
+        module Flow
+          module Helpers
+            module Constants
+              # Flow states (Csikszentmihalyi's model)
+              FLOW_STATES = %i[
+                flow
+                arousal
+                control
+                relaxation
+                boredom
+                apathy
+                worry
+                anxiety
+              ].freeze
+
+              # Input dimensions for flow detection
+              DIMENSIONS = %i[challenge skill].freeze
+
+              # Flow zone boundaries (challenge-skill space)
+              # Flow occurs when challenge ~= skill and both are moderate-to-high
+              FLOW_ZONE = {
+                challenge_min:     0.4,
+                challenge_max:     0.8,
+                skill_min:         0.4,
+                skill_max:         0.8,
+                balance_tolerance: 0.15
+              }.freeze
+
+              # EMA alpha for challenge/skill tracking
+              FLOW_ALPHA = 0.15
+
+              # Minimum ticks in flow before "deep flow" bonus
+              DEEP_FLOW_THRESHOLD = 20
+
+              # Flow score bonuses
+              DEEP_FLOW_BONUS = 0.1
+              CURIOSITY_BONUS = 0.05
+              LOW_ERROR_BONUS = 0.05
+
+              # Flow effects on other subsystems
+              FLOW_EFFECTS = {
+                fatigue_reduction:    0.5,   # fatigue drains 50% slower in flow
+                time_dilation:        0.7,   # subjective time flies (rate < 1.0)
+                performance_boost:    1.15,  # 15% performance improvement
+                attention_broadening: 0.8,   # attention threshold lowered (more open)
+                creativity_boost:     1.2    # curiosity/imagination amplified
+              }.freeze
+
+              # Anti-flow indicators (break flow state)
+              FLOW_BREAKERS = %i[
+                high_anxiety
+                trust_violation
+                critical_error
+                burnout
+                conflict_escalation
+              ].freeze
+
+              # History cap
+              MAX_FLOW_HISTORY = 100
+
+              # State classification regions in challenge-skill space
+              STATE_REGIONS = {
+                flow:       { challenge: (0.4..0.8), skill: (0.4..0.8), balanced: true },
+                arousal:    { challenge: (0.6..1.0), skill: (0.3..0.6), balanced: false },
+                control:    { challenge: (0.2..0.5), skill: (0.5..0.8), balanced: false },
+                relaxation: { challenge: (0.1..0.4), skill: (0.4..0.7), balanced: false },
+                boredom:    { challenge: (0.0..0.3), skill: (0.5..1.0), balanced: false },
+                apathy:     { challenge: (0.0..0.3), skill: (0.0..0.3), balanced: false },
+                worry:      { challenge: (0.5..0.8), skill: (0.1..0.4), balanced: false },
+                anxiety:    { challenge: (0.7..1.0), skill: (0.0..0.4), balanced: false }
+              }.freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end