lex-homeostasis 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 24b989d7a6ff4c7dccbcf03f5d43f79c777e9bfac5d5549cb175fe9faa4787d0
+  data.tar.gz: d3b1994e7103256f6d6d4f4501304178b296f3c37ba01f66b1e066579dd43b7b
+SHA512:
+  metadata.gz: 9db26cd90fada5f87e7801377b2d576d3e98c4401b9debc3b50ca09e15ec661d030d72090eef3881851bec2256b15084093eb62f59e1d071e94828318b9f61b0
+  data.tar.gz: 03735a57a5408073d4d3816d28eedd7d83de90fdc7a9f6cd2e45c9d3736a369f74d464d5384fe4288e46f80f13a65df016df6d2ffe0ec886a7b7a3043519dd15

data/Gemfile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :dev, :test do
+  gem 'rspec', '~> 3.12'
+  gem 'rubocop', '~> 1.75'
+  gem 'rubocop-rspec', '~> 3.0'
+end
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 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,90 @@
+# lex-homeostasis
+
+Cognitive self-regulation for LegionIO agents. Part of the LegionIO cognitive architecture extension ecosystem (LEX).
+
+## What It Does
+
+`lex-homeostasis` is the agent's internal thermostat. It maintains seven setpoints covering emotional arousal, curiosity, cognitive load, memory health, prediction accuracy, trust stability, and attention breadth. Each tick, observed values are compared to targets; deviations produce regulation signals (dampen, amplify, or hold) that other subsystems can consume to correct their behavior. Sustained deviation accumulates allostatic load, modeling chronic cognitive strain.
+
+Key capabilities:
+
+- **Seven setpoints**: emotional_arousal, curiosity_intensity, cognitive_load, memory_health, prediction_accuracy, trust_stability, attention_breadth
+- **Proportional negative feedback**: regulation magnitude scales with how far a value has drifted from its target
+- **Allostatic load tracking**: cumulative stress from prolonged out-of-range states, with four classifications (healthy/elevated/high/critical)
+- **Adaptive targets**: setpoints slowly drift toward the agent's natural operating range via EMA
+- **Modulation signals**: per-subsystem dampen/amplify/hold signals consumable by other extensions
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'lex-homeostasis'
+```
+
+Or install directly:
+
+```
+gem install lex-homeostasis
+```
+
+## Usage
+
+```ruby
+require 'legion/extensions/homeostasis'
+
+client = Legion::Extensions::Homeostasis::Client.new
+
+# Run the regulation cycle with tick results from the current tick
+result = client.regulate(tick_results: tick_phase_results)
+# => { signals: { emotional_arousal: { type: :dampen, magnitude: 0.15 }, ... },
+#      regulation_health: 0.85, allostatic_load: 0.12, health_label: :excellent }
+
+# Query the last regulation signal for a specific subsystem
+signal = client.modulation_for(subsystem: :curiosity_intensity)
+# => { type: :hold, magnitude: 0.0, subsystem: :curiosity_intensity }
+
+# Check allostatic load
+status = client.allostatic_status
+# => { load: 0.12, classification: :healthy, recovering: true, trend: -0.01 }
+
+# Overview of all setpoints
+client.regulation_overview
+
+# Summary stats
+client.homeostasis_stats
+```
+
+## Runner Methods
+
+| Method | Description |
+|---|---|
+| `regulate` | Full regulation cycle; returns signals + health summary |
+| `modulation_for` | Last regulation signal for a specific subsystem |
+| `allostatic_status` | Load value, classification, trend, recovering flag |
+| `regulation_overview` | All setpoint current values, deviations, and regulation health |
+| `homeostasis_stats` | Summary: health label, allostatic classification, worst deviation |
+
+## Monitored Setpoints
+
+| Subsystem | Target | Tolerance |
+|---|---|---|
+| emotional_arousal | 0.4 | 0.15 |
+| curiosity_intensity | 0.5 | 0.2 |
+| cognitive_load | 0.6 | 0.2 |
+| memory_health | 0.7 | 0.15 |
+| prediction_accuracy | 0.6 | 0.2 |
+| trust_stability | 0.7 | 0.2 |
+| attention_breadth | 0.5 | 0.2 |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-homeostasis.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/homeostasis/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-homeostasis'
+  spec.version       = Legion::Extensions::Homeostasis::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Homeostasis'
+  spec.description   = 'Cognitive self-regulation with setpoints, negative feedback loops, and allostatic load tracking'
+  spec.homepage      = 'https://github.com/LegionIO/lex-homeostasis'
+  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-homeostasis'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-homeostasis'
+  spec.metadata['changelog_uri'] = 'https://github.com/LegionIO/lex-homeostasis'
+  spec.metadata['bug_tracker_uri'] = 'https://github.com/LegionIO/lex-homeostasis/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-homeostasis.gemspec Gemfile LICENSE README.md]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Homeostasis
+      class Client
+        include Runners::Homeostasis
+
+        attr_reader :regulator, :allostatic_load
+
+        def initialize(regulator: nil, allostatic_load: nil, **)
+          @regulator = regulator || Helpers::Regulator.new
+          @allostatic_load = allostatic_load || Helpers::AllostaticLoad.new
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/homeostasis/helpers/allostatic_load.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Homeostasis
+      module Helpers
+        class AllostaticLoad
+          attr_reader :load, :history, :peak_load
+
+          def initialize
+            @load = 0.0
+            @peak_load = 0.0
+            @history = []
+          end
+
+          def update(regulator)
+            in_tolerance, deviating = regulator.setpoints.values.partition(&:within_tolerance?)
+
+            accumulation = deviating.sum { |sp| sp.deviation_ratio * Constants::ALLOSTATIC_ACCUMULATION }
+            recovery = in_tolerance.size * Constants::ALLOSTATIC_DECAY_RATE
+
+            @load = (@load + accumulation - recovery).clamp(0.0, 1.0)
+            @peak_load = [@peak_load, @load].max
+
+            @history << { load: @load, deviating: deviating.size, at: Time.now.utc }
+            @history = @history.last(Constants::MAX_ALLOSTATIC_HISTORY)
+
+            @load
+          end
+
+          def classification
+            if @load <= Constants::ALLOSTATIC_LOAD_HEALTHY
+              :healthy
+            elsif @load <= Constants::ALLOSTATIC_LOAD_ELEVATED
+              :elevated
+            elsif @load <= Constants::ALLOSTATIC_LOAD_CRITICAL
+              :high
+            else
+              :critical
+            end
+          end
+
+          def recovering?
+            recent = @history.last(5)
+            return false if recent.size < 3
+
+            recent.last[:load] < recent.first[:load]
+          end
+
+          def trend(window: 20)
+            recent = @history.last(window)
+            return :insufficient_data if recent.size < 3
+
+            loads = recent.map { |h| h[:load] }
+            avg_first_half = loads[0...(loads.size / 2)].sum / (loads.size / 2).to_f
+            avg_second_half = loads[(loads.size / 2)..].sum / (loads.size - (loads.size / 2)).to_f
+
+            delta = avg_second_half - avg_first_half
+            if delta > 0.05
+              :accumulating
+            elsif delta < -0.05
+              :recovering
+            else
+              :stable
+            end
+          end
+
+          def reset
+            @load = 0.0
+            @history.clear
+          end
+
+          def to_h
+            {
+              load:           @load,
+              peak_load:      @peak_load,
+              classification: classification,
+              recovering:     recovering?,
+              trend:          trend,
+              history_size:   @history.size
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Homeostasis
+      module Helpers
+        module Constants
+          # Regulated subsystems and their ideal setpoints (0.0-1.0 scale)
+          SETPOINTS = {
+            emotional_arousal:   { target: 0.4, tolerance: 0.2 },
+            curiosity_intensity: { target: 0.5, tolerance: 0.25 },
+            cognitive_load:      { target: 0.6, tolerance: 0.2 },
+            memory_health:       { target: 0.7, tolerance: 0.15 },
+            prediction_accuracy: { target: 0.6, tolerance: 0.2 },
+            trust_stability:     { target: 0.7, tolerance: 0.15 },
+            attention_breadth:   { target: 0.5, tolerance: 0.2 }
+          }.freeze
+
+          # Regulation gains (how aggressively the system corrects)
+          # Higher gain = faster correction but more oscillation risk
+          REGULATION_GAIN = {
+            emotional_arousal:   0.3,
+            curiosity_intensity: 0.2,
+            cognitive_load:      0.4,
+            memory_health:       0.1,
+            prediction_accuracy: 0.15,
+            trust_stability:     0.1,
+            attention_breadth:   0.2
+          }.freeze
+
+          # Allostatic load thresholds
+          ALLOSTATIC_LOAD_HEALTHY    = 0.3
+          ALLOSTATIC_LOAD_ELEVATED   = 0.6
+          ALLOSTATIC_LOAD_CRITICAL   = 0.85
+          ALLOSTATIC_DECAY_RATE      = 0.02  # per tick when within tolerance
+          ALLOSTATIC_ACCUMULATION    = 0.05  # per tick when outside tolerance
+
+          # Modulation signal bounds
+          MAX_DAMPEN  = -0.5  # maximum dampening signal
+          MAX_AMPLIFY =  0.5  # maximum amplification signal
+
+          # EMA alpha for setpoint adaptation
+          SETPOINT_ADAPTATION_ALPHA = 0.05
+
+          # History limits
+          MAX_REGULATION_HISTORY = 100
+          MAX_ALLOSTATIC_HISTORY = 200
+
+          # Regulation signal types
+          SIGNAL_TYPES = %i[dampen amplify hold].freeze
+
+          # Health classification thresholds
+          REGULATION_HEALTH = {
+            (0.8..)     => :stable,
+            (0.6...0.8) => :compensating,
+            (0.4...0.6) => :strained,
+            (0.2...0.4) => :dysregulated,
+            (..0.2)     => :critical
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/homeostasis/helpers/regulator.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Homeostasis
+      module Helpers
+        class Regulator
+          attr_reader :setpoints, :signals, :regulation_count
+
+          def initialize
+            @setpoints = build_setpoints
+            @signals = {}
+            @regulation_count = 0
+          end
+
+          def regulate(observations)
+            @regulation_count += 1
+            new_signals = {}
+
+            observations.each do |subsystem, value|
+              sp = @setpoints[subsystem]
+              next unless sp
+
+              error = sp.update(value)
+              gain = Constants::REGULATION_GAIN.fetch(subsystem, 0.2)
+              signal = compute_signal(error, sp.tolerance, gain)
+
+              new_signals[subsystem] = {
+                type:             classify_signal(signal),
+                magnitude:        signal.abs,
+                direction:        signal,
+                error:            error,
+                within_tolerance: sp.within_tolerance?
+              }
+            end
+
+            @signals = new_signals
+            new_signals
+          end
+
+          def regulation_health
+            return 1.0 if @setpoints.empty?
+
+            in_tolerance = @setpoints.values.count(&:within_tolerance?)
+            in_tolerance.to_f / @setpoints.size
+          end
+
+          def health_label
+            health = regulation_health
+            Constants::REGULATION_HEALTH.each do |range, label|
+              return label if range.cover?(health)
+            end
+            :unknown
+          end
+
+          def worst_deviation
+            worst = @setpoints.values.max_by(&:deviation_ratio)
+            return nil unless worst
+
+            { subsystem: worst.name, deviation_ratio: worst.deviation_ratio, error: worst.error }
+          end
+
+          def subsystem_status(subsystem)
+            sp = @setpoints[subsystem]
+            return nil unless sp
+
+            signal = @signals[subsystem]
+            sp.to_h.merge(signal: signal)
+          end
+
+          def adapt_setpoints
+            @setpoints.each_value do |sp|
+              sp.adapt_target if sp.within_tolerance?
+            end
+          end
+
+          def to_h
+            {
+              setpoints:        @setpoints.transform_values(&:to_h),
+              signals:          @signals,
+              regulation_count: @regulation_count,
+              health:           regulation_health,
+              health_label:     health_label
+            }
+          end
+
+          private
+
+          def build_setpoints
+            Constants::SETPOINTS.to_h do |name, config|
+              [name, Setpoint.new(name: name, target: config[:target], tolerance: config[:tolerance])]
+            end
+          end
+
+          def compute_signal(error, tolerance, gain)
+            return 0.0 if error.abs <= tolerance * 0.1
+
+            correction = -error * gain
+            correction.clamp(Constants::MAX_DAMPEN, Constants::MAX_AMPLIFY)
+          end
+
+          def classify_signal(signal)
+            if signal < -0.01
+              :dampen
+            elsif signal > 0.01
+              :amplify
+            else
+              :hold
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/homeostasis/helpers/setpoint.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Homeostasis
+      module Helpers
+        class Setpoint
+          attr_reader :name, :target, :tolerance, :current_value, :error, :history
+
+          def initialize(name:, target:, tolerance:)
+            @name = name
+            @target = target.to_f
+            @tolerance = tolerance.to_f
+            @current_value = @target
+            @error = 0.0
+            @history = []
+          end
+
+          def update(observed_value)
+            @current_value = observed_value.to_f
+            @error = @current_value - @target
+            @history << { value: @current_value, error: @error, at: Time.now.utc }
+            @history = @history.last(Constants::MAX_REGULATION_HISTORY)
+            @error
+          end
+
+          def within_tolerance?
+            @error.abs <= @tolerance
+          end
+
+          def deviation_ratio
+            return 0.0 if @tolerance.zero?
+
+            (@error.abs / @tolerance).clamp(0.0, 3.0)
+          end
+
+          def adapt_target(alpha: Constants::SETPOINT_ADAPTATION_ALPHA)
+            @target += (alpha * @error)
+            @target = @target.clamp(0.0, 1.0)
+          end
+
+          def trend(window: 10)
+            recent = @history.last(window)
+            return :insufficient_data if recent.size < 3
+
+            values = recent.map { |h| h[:value] }
+            slope = linear_slope(values)
+
+            if slope > 0.01
+              :rising
+            elsif slope < -0.01
+              :falling
+            else
+              :stable
+            end
+          end
+
+          def to_h
+            {
+              name:             @name,
+              target:           @target,
+              tolerance:        @tolerance,
+              current_value:    @current_value,
+              error:            @error,
+              within_tolerance: within_tolerance?,
+              deviation_ratio:  deviation_ratio,
+              trend:            trend,
+              history_size:     @history.size
+            }
+          end
+
+          private
+
+          def linear_slope(values)
+            n = values.size
+            return 0.0 if n < 2
+
+            sum_x = n * (n - 1) / 2.0
+            sum_y = values.sum
+            sum_xy = values.each_with_index.sum { |y, x| x * y }
+            sum_x2 = (0...n).sum { |x| x * x }
+
+            denominator = (n * sum_x2) - (sum_x * sum_x)
+            return 0.0 if denominator.zero?
+
+            ((n * sum_xy) - (sum_x * sum_y)) / denominator
+          end
+        end
+      end
+    end
+  end
+end