lex-resilience 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c568cb863f7bce59fa4b9671135e36e5ac16142915c271f217e97f926810257c
+  data.tar.gz: b727773a253036e8ff144cade567ae6ade65933f760e0febf188a53242e8d0e1
+SHA512:
+  metadata.gz: e9ec2c68dfa1d5fd33a7f1160b2650c5d0d89e27354b8862e5cda540c94bd71a0f18682870583260f322c6c3c075311c856bc0902fece25f620d012046f17660
+  data.tar.gz: 3fca179ba62761d865ef34aa12473585990bb6a7456929eb3961c2beec2dd5ae6d4ff06d976b476e475d4804c91c51fec341881a0b4dcff9b5e55b113ac58947

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/resilience/helpers/constants'
+require 'legion/extensions/resilience/helpers/adversity_tracker'
+require 'legion/extensions/resilience/helpers/resilience_model'
+require 'legion/extensions/resilience/runners/resilience'
+
+module Legion
+  module Extensions
+    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

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

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

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

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

data/lib/legion/extensions/resilience/helpers/resilience_model.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Resilience
+      module Helpers
+        class ResilienceModel
+          attr_reader :dimensions, :growth_bonus, :history
+
+          def initialize
+            @dimensions = Constants::DIMENSIONS.keys.to_h { |d| [d, 0.5] }
+            @growth_bonus = 0.0
+            @history = []
+          end
+
+          def update_from_tracker(tracker)
+            update_elasticity(tracker)
+            update_robustness(tracker)
+            update_adaptability(tracker)
+            update_growth(tracker)
+
+            record_snapshot
+          end
+
+          def composite_score
+            total = 0.0
+            Constants::DIMENSIONS.each do |dim, config|
+              total += (@dimensions[dim] + (dim == :growth ? @growth_bonus : 0.0)) * config[:weight]
+            end
+            total.clamp(0.0, 1.0)
+          end
+
+          def classification
+            score = composite_score
+            if score >= Constants::ANTIFRAGILITY_THRESHOLD
+              :antifragile
+            elsif score >= 0.5
+              :resilient
+            elsif score >= Constants::FRAGILITY_THRESHOLD
+              :fragile
+            else
+              :brittle
+            end
+          end
+
+          def dimension_detail(name)
+            return nil unless @dimensions.key?(name)
+
+            {
+              name:    name,
+              value:   @dimensions[name].round(4),
+              config:  Constants::DIMENSIONS[name],
+              trend:   dimension_trend(name),
+              healthy: @dimensions[name] >= 0.5
+            }
+          end
+
+          def trend
+            return :insufficient_data if @history.size < 5
+
+            recent = @history.last(10)
+            scores = recent.map { |h| h[:composite] }
+            first_half = scores[0...(scores.size / 2)]
+            second_half = scores[(scores.size / 2)..]
+            diff = mean(second_half) - mean(first_half)
+
+            if diff > 0.03
+              :strengthening
+            elsif diff < -0.03
+              :weakening
+            else
+              :stable
+            end
+          end
+
+          def to_h
+            {
+              dimensions:   @dimensions.transform_values { |v| v.round(4) },
+              growth_bonus: @growth_bonus.round(4),
+              composite:    composite_score.round(4),
+              class:        classification,
+              trend:        trend
+            }
+          end
+
+          private
+
+          def update_elasticity(tracker)
+            speed = tracker.average_recovery_speed
+            signal = if speed.zero?
+                       0.5
+                     elsif speed <= 1.0
+                       0.7 + ((1.0 - speed) * 0.3)
+                     else
+                       [0.3, 0.7 - ((speed - 1.0) * 0.2)].max
+                     end
+            @dimensions[:elasticity] = ema(@dimensions[:elasticity], signal, Constants::RESILIENCE_ALPHA)
+          end
+
+          def update_robustness(tracker)
+            worst = tracker.worst_health
+            @dimensions[:robustness] = ema(@dimensions[:robustness], worst, Constants::RESILIENCE_ALPHA)
+          end
+
+          def update_adaptability(tracker)
+            rate = tracker.recovery_rate
+            signal = tracker.total_adversities.zero? ? 0.5 : rate
+            @dimensions[:adaptability] = ema(@dimensions[:adaptability], signal, Constants::RESILIENCE_ALPHA)
+          end
+
+          def update_growth(tracker)
+            if tracker.consecutive_recoveries >= Constants::GROWTH_TRIGGER
+              @growth_bonus = [@growth_bonus + Constants::GROWTH_INCREMENT, Constants::MAX_GROWTH_BONUS].min
+            end
+
+            growth_signal = tracker.total_adversities.zero? ? 0.5 : 0.5 + @growth_bonus
+            @dimensions[:growth] = ema(@dimensions[:growth], growth_signal, Constants::RESILIENCE_ALPHA)
+          end
+
+          def dimension_trend(name)
+            return :insufficient_data if @history.size < 5
+
+            recent = @history.last(10)
+            values = recent.map { |h| h[:dimensions][name] }
+            first_half = values[0...(values.size / 2)]
+            second_half = values[(values.size / 2)..]
+            diff = mean(second_half) - mean(first_half)
+
+            if diff > 0.02
+              :improving
+            elsif diff < -0.02
+              :declining
+            else
+              :stable
+            end
+          end
+
+          def ema(current, observed, alpha)
+            (current * (1.0 - alpha)) + (observed * alpha)
+          end
+
+          def mean(values)
+            return 0.0 if values.empty?
+
+            values.sum / values.size.to_f
+          end
+
+          def record_snapshot
+            @history << {
+              dimensions: @dimensions.dup,
+              composite:  composite_score,
+              class:      classification,
+              at:         Time.now.utc
+            }
+            @history.shift while @history.size > Constants::MAX_RESILIENCE_HISTORY
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Resilience
+      module Runners
+        module Resilience
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def update_resilience(tick_results: {}, **)
+            detect_adversities(tick_results)
+            recovery = adversity_tracker.tick_recovery
+            resilience_model.update_from_tracker(adversity_tracker)
+
+            Legion::Logging.debug "[resilience] active=#{recovery[:active_count]} " \
+                                  "resolved=#{recovery[:resolved_count]} " \
+                                  "composite=#{resilience_model.composite_score.round(3)}"
+
+            {
+              active_adversities: recovery[:active_count],
+              resolved_this_tick: recovery[:resolved_count],
+              worst_health:       recovery[:worst_health],
+              composite_score:    resilience_model.composite_score.round(4),
+              classification:     resilience_model.classification,
+              growth_bonus:       resilience_model.growth_bonus.round(4)
+            }
+          end
+
+          def register_adversity(type:, severity:, context: {}, **)
+            adversity = adversity_tracker.register(type: type, severity: severity, context: context)
+            return { success: false, error: 'invalid type or severity' } unless adversity
+
+            Legion::Logging.info "[resilience] adversity registered: type=#{type} severity=#{severity}"
+            { success: true, adversity: adversity }
+          end
+
+          def resilience_status(**)
+            model_state = resilience_model.to_h
+            Legion::Logging.debug "[resilience] status: #{model_state[:class]} score=#{model_state[:composite]}"
+
+            model_state.merge(
+              active_adversities:     adversity_tracker.active_adversities.size,
+              total_adversities:      adversity_tracker.total_adversities,
+              consecutive_recoveries: adversity_tracker.consecutive_recoveries,
+              recovery_rate:          adversity_tracker.recovery_rate.round(4)
+            )
+          end
+
+          def adversity_report(**)
+            Legion::Logging.debug '[resilience] adversity report'
+
+            {
+              active:    adversity_tracker.active_adversities,
+              by_type:   adversity_tracker.active_by_type,
+              total:     adversity_tracker.total_adversities,
+              worst:     adversity_tracker.worst_health.round(4),
+              avg_speed: adversity_tracker.average_recovery_speed.round(4)
+            }
+          end
+
+          def dimension_detail(dimension:, **)
+            detail = resilience_model.dimension_detail(dimension.to_sym)
+            return { error: "unknown dimension: #{dimension}" } unless detail
+
+            Legion::Logging.debug "[resilience] dimension #{dimension}: #{detail[:value]}"
+            detail
+          end
+
+          def resilience_stats(**)
+            Legion::Logging.debug '[resilience] stats'
+
+            {
+              composite:              resilience_model.composite_score.round(4),
+              classification:         resilience_model.classification,
+              dimensions:             resilience_model.dimensions.transform_values { |v| v.round(4) },
+              growth_bonus:           resilience_model.growth_bonus.round(4),
+              trend:                  resilience_model.trend,
+              total_adversities:      adversity_tracker.total_adversities,
+              active_adversities:     adversity_tracker.active_adversities.size,
+              recovery_rate:          adversity_tracker.recovery_rate.round(4),
+              consecutive_recoveries: adversity_tracker.consecutive_recoveries,
+              history_size:           resilience_model.history.size
+            }
+          end
+
+          private
+
+          def adversity_tracker
+            @adversity_tracker ||= Helpers::AdversityTracker.new
+          end
+
+          def resilience_model
+            @resilience_model ||= Helpers::ResilienceModel.new
+          end
+
+          def detect_adversities(tick_results)
+            detect_prediction_adversity(tick_results)
+            detect_trust_adversity(tick_results)
+            detect_conflict_adversity(tick_results)
+            detect_energy_adversity(tick_results)
+            detect_emotional_adversity(tick_results)
+          end
+
+          def detect_prediction_adversity(tick_results)
+            error_rate = tick_results.dig(:prediction_engine, :error_rate)
+            return unless error_rate && error_rate > 0.7
+
+            severity = error_rate > 0.9 ? :major : :moderate
+            adversity_tracker.register(type: :prediction_failure, severity: severity)
+          end
+
+          def detect_trust_adversity(tick_results)
+            violation = tick_results.dig(:trust, :violation)
+            return unless violation
+
+            adversity_tracker.register(type: :trust_violation, severity: :major)
+          end
+
+          def detect_conflict_adversity(tick_results)
+            conflict_severity = tick_results.dig(:conflict, :severity)
+            return unless conflict_severity && conflict_severity >= 3
+
+            severity = conflict_severity >= 4 ? :severe : :moderate
+            adversity_tracker.register(type: :conflict_escalation, severity: severity)
+          end
+
+          def detect_energy_adversity(tick_results)
+            energy = tick_results.dig(:fatigue, :energy)
+            return unless energy && energy < 0.2
+
+            severity = energy < 0.1 ? :major : :moderate
+            adversity_tracker.register(type: :resource_depletion, severity: severity)
+          end
+
+          def detect_emotional_adversity(tick_results)
+            arousal = tick_results.dig(:emotional_evaluation, :arousal)
+            return unless arousal && arousal > 0.9
+
+            adversity_tracker.register(type: :emotional_shock, severity: :moderate)
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/resilience.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/resilience/version'
+require 'legion/extensions/resilience/helpers/constants'
+require 'legion/extensions/resilience/helpers/adversity_tracker'
+require 'legion/extensions/resilience/helpers/resilience_model'
+require 'legion/extensions/resilience/runners/resilience'
+require 'legion/extensions/resilience/client'
+
+module Legion
+  module Extensions
+    module Resilience
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined?(:Core)
+    end
+  end
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: lex-resilience
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Matthew Iverson
+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: Models resilience as the capacity to recover from setbacks and grow stronger
+  from adversity
+email:
+- matt@legionIO.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/legion/extensions/resilience.rb
+- lib/legion/extensions/resilience/client.rb
+- lib/legion/extensions/resilience/helpers/adversity_tracker.rb
+- lib/legion/extensions/resilience/helpers/constants.rb
+- lib/legion/extensions/resilience/helpers/resilience_model.rb
+- lib/legion/extensions/resilience/runners/resilience.rb
+- lib/legion/extensions/resilience/version.rb
+homepage: https://github.com/LegionIO/lex-resilience
+licenses:
+- MIT
+metadata:
+  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: Anti-fragility and adversity recovery for LegionIO cognitive agents
+test_files: []