lex-fatigue 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 845130eba06fa9a364b06a89d3c775770aaf6936c5db41e9ac946c179c23f690
+  data.tar.gz: d5b1744ba68da9b80fc2647279a471426b87aed72832a7268feea28afff31fa8
+SHA512:
+  metadata.gz: c60dc6d59bc80ef1323a0522a4dfa7eaf316fc4054d3d0aa04796ebf243bc505962923c6f89736312247b27ec5e4fef93c397bba0efc7e449b77e5be9ffa9bbf
+  data.tar.gz: 72c2555f2378411df4e05680a54592f2d4602475113404061ae197fb6d55ab38bb199c90f01efe1e70eae829d997c420188fe5bfe5804b78f54f082dad5a0020

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 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,59 @@
+# lex-fatigue
+
+Cognitive fatigue modeling for the LegionIO brain-modeled cognitive architecture.
+
+## What It Does
+
+Models how sustained cognitive effort degrades processing capacity over time and how rest restores it. Tracks energy level as a continuous float (0–1), computes a performance degradation factor that scales with fatigue, detects burnout risk, and generates rest recommendations. Energy decays faster under high cognitive load and emotional arousal, and recovers during rest periods.
+
+## Usage
+
+```ruby
+client = Legion::Extensions::Fatigue::Client.new
+
+# Update per tick with the tick's load metrics
+client.update_fatigue(tick_results: { cognitive_load: 0.7, emotional_arousal: 0.4 })
+# => { energy: 0.96, fatigue_level: :fresh, performance_factor: 1.0,
+#      recommendation: :continue, burnout_risk: false }
+
+# Check current status
+client.energy_status
+# => { energy: 0.72, fatigue_level: :alert, performance_factor: 1.0, needs_rest: false }
+
+# Enter recovery mode
+client.enter_rest(mode: :full_rest)
+# => { mode: :full_rest, energy_before: 0.35, energy_after: 0.5, recovered: 0.15 }
+
+# Project future energy
+client.energy_forecast(ticks: 50)
+# => { forecast: [{ tick: 10, projected_energy: 0.62, fatigue_level: :alert }, ...] }
+
+# Burnout risk check
+client.burnout_risk_assessment
+# => { at_risk: false, energy: 0.72, ticks_until_burnout: 180 }
+
+# Session statistics
+client.fatigue_stats
+```
+
+## Fatigue Levels
+
+| Energy | Level |
+|---|---|
+| 0.8 – 1.0 | `:fresh` |
+| 0.6 – 0.8 | `:alert` |
+| 0.4 – 0.6 | `:tired` |
+| 0.2 – 0.4 | `:exhausted` |
+| 0.0 – 0.2 | `:burnout` |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-fatigue.gemspec

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

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/fatigue/helpers/constants'
+require 'legion/extensions/fatigue/helpers/energy_model'
+require 'legion/extensions/fatigue/helpers/fatigue_store'
+require 'legion/extensions/fatigue/runners/fatigue'
+
+module Legion
+  module Extensions
+    module Fatigue
+      class Client
+        include Runners::Fatigue
+
+        attr_reader :fatigue_store
+
+        def initialize(fatigue_store: nil, **)
+          @fatigue_store = fatigue_store || Helpers::FatigueStore.new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Fatigue
+      module Helpers
+        module Constants
+          MAX_ENERGY = 1.0
+          MIN_ENERGY = 0.0
+
+          RESTING_RECOVERY_RATE       = 0.02
+          ACTIVE_DRAIN_RATE           = 0.01
+          COGNITIVE_DRAIN_MULTIPLIER  = 1.5
+          EMOTIONAL_DRAIN_MULTIPLIER  = 1.3
+
+          FATIGUE_LEVELS = {
+            fresh:     0.8,
+            alert:     0.6,
+            tired:     0.4,
+            exhausted: 0.2,
+            depleted:  0.0
+          }.freeze
+
+          PERFORMANCE_DEGRADATION = {
+            fresh:     1.0,
+            alert:     0.95,
+            tired:     0.8,
+            exhausted: 0.6,
+            depleted:  0.3
+          }.freeze
+
+          RECOVERY_MODES = %i[active_rest light_duty full_rest sleep].freeze
+
+          RECOVERY_RATES = {
+            active_rest: 0.005,
+            light_duty:  0.01,
+            full_rest:   0.02,
+            sleep:       0.05
+          }.freeze
+
+          REST_THRESHOLD      = 0.3
+          CRITICAL_THRESHOLD  = 0.15
+          SECOND_WIND_CHANCE  = 0.05
+          BURNOUT_THRESHOLD   = 50
+          MAX_HISTORY         = 100
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    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

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

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    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

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    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

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

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

data/lib/legion/extensions/fatigue.rb

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