lex-agentic-homeostasis 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1334257150dffdf8eaa99b03a859ce6d149dcf8dba1810de335175f651409c1a
+  data.tar.gz: ac4afb8fb7ce2b9c08195574128fe919a1554a3c87d82c1838ec93983394cbd0
+SHA512:
+  metadata.gz: 3da6b13d41ba71e7cff50b4d80a8fb367bcfc1b95625d3c47a4efd4c95095a6d5c13411780671c29a6062e455a670138b22c39d123ffa5d725cb919b9f708cc6
+  data.tar.gz: 1f651a9dbe0f12ee73f4e4c924c7400ae110e91b83cc5d777a330c1fc770dc0ae41e8caea67c12b9bda591b2c5c34c4a5824c7b63b88f0a9116e2818450dff8c

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-18
+
+### Added
+- Initial release as domain consolidation gem
+- Consolidated source extensions into unified domain gem under `Legion::Extensions::Agentic::<Domain>`
+- All sub-modules loaded from single entry point
+- Full spec suite with zero failures
+- RuboCop compliance across all files

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

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,13 @@
+# lex-agentic-homeostasis
+
+LEX agentic homeostasis domain: self-regulation, balance, resource management
+
+## Sub-modules
+
+*(populated as extensions are consolidated)*
+
+## Installation
+
+```ruby
+gem 'lex-agentic-homeostasis'
+```

data/lex-agentic-homeostasis.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/agentic/homeostasis/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-agentic-homeostasis'
+  spec.version       = Legion::Extensions::Agentic::Homeostasis::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Agentic Homeostasis'
+  spec.description   = 'LEX agentic homeostasis domain: self-regulation, balance, resource management'
+  spec.homepage      = 'https://github.com/LegionIO/lex-agentic-homeostasis'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']      = spec.homepage
+  spec.metadata['source_code_uri']   = spec.homepage
+  spec.metadata['changelog_uri']     = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir.glob('{lib,spec}/**/*.rb') + %w[lex-agentic-homeostasis.gemspec Gemfile LICENSE README.md CHANGELOG.md]
+  end
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'rspec', '~> 3.13'
+  spec.add_development_dependency 'rubocop', '~> 1.60'
+  spec.add_development_dependency 'rubocop-rspec', '~> 2.26'
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Homeostasis
+        module Cocoon
+          class Client
+            include Runners::CognitiveCocoon
+
+            def initialize
+              @default_engine = Helpers::Incubator.new
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/homeostasis/cocoon/helpers/cocoon.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Homeostasis
+        module Cocoon
+          module Helpers
+            class Cocoon
+              include Constants
+
+              attr_reader :id, :cocoon_type, :domain, :content, :maturity,
+                          :stage, :protection, :created_at
+
+              def initialize(cocoon_type:, domain:, content: '', maturity: nil, protection: nil)
+                @id = SecureRandom.uuid
+                @cocoon_type = cocoon_type.to_sym
+                @domain     = domain.to_sym
+                @content    = content
+                @maturity   = (maturity || 0.0).to_f.clamp(0.0, 1.0)
+                @protection = (protection || PROTECTION_BY_TYPE.fetch(@cocoon_type, 0.7)).to_f.clamp(0.0, 1.0)
+                @stage      = :encapsulating
+                @created_at = Time.now.utc
+                advance_stage!
+              end
+
+              def gestate!(rate = MATURITY_RATE)
+                return self if @stage == :emerged
+
+                @maturity = (@maturity + rate).clamp(0.0, 1.0).round(10)
+                advance_stage!
+                self
+              end
+
+              def emerge!
+                return { success: false, error: 'not ready', damaged: false } unless ready?
+
+                @stage = :emerged
+                { success: true, content: @content, damaged: false, maturity: @maturity }
+              end
+
+              def expose!
+                damaged = premature?
+                @maturity = (@maturity * PREMATURE_PENALTY).round(10) if damaged
+                @stage = :emerged
+                { success: true, content: @content, damaged: damaged, maturity: @maturity }
+              end
+
+              def ready?
+                @maturity >= 1.0 || @stage == :ready
+              end
+
+              def premature?
+                @stage != :ready && @stage != :emerged && @maturity < 1.0
+              end
+
+              def age_seconds
+                (Time.now.utc - @created_at).round(2)
+              end
+
+              def to_h
+                {
+                  id:             @id,
+                  cocoon_type:    @cocoon_type,
+                  domain:         @domain,
+                  content:        @content,
+                  maturity:       @maturity.round(10),
+                  stage:          @stage,
+                  protection:     @protection.round(10),
+                  ready:          ready?,
+                  premature:      premature?,
+                  maturity_label: Constants.label_for(MATURITY_LABELS, @maturity),
+                  age_seconds:    age_seconds,
+                  created_at:     @created_at.iso8601
+                }
+              end
+
+              private
+
+              def advance_stage!
+                @stage = compute_stage
+              end
+
+              def compute_stage
+                return :emerged if @stage == :emerged
+
+                if @maturity >= 1.0
+                  :ready
+                elsif @maturity >= 0.75
+                  :transforming
+                elsif @maturity >= 0.4
+                  :developing
+                else
+                  :encapsulating
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Homeostasis
+        module Cocoon
+          module Helpers
+            module Constants
+              MAX_COCOONS      = 100
+              MATURITY_RATE    = 0.1
+              PREMATURE_PENALTY = 0.5
+
+              GESTATION_STAGES = %i[encapsulating developing transforming ready emerged].freeze
+
+              COCOON_TYPES = %i[silk chrysalis shell pod web].freeze
+
+              PROTECTION_BY_TYPE = {
+                silk:      0.6,
+                chrysalis: 0.8,
+                shell:     0.9,
+                pod:       0.7,
+                web:       0.5
+              }.freeze
+
+              MATURITY_LABELS = {
+                (0.9..)     => :fully_gestated,
+                (0.7...0.9) => :nearly_ready,
+                (0.5...0.7) => :mid_gestation,
+                (0.3...0.5) => :early_gestation,
+                (0.1...0.3) => :just_encapsulated,
+                (..0.1)     => :newly_formed
+              }.freeze
+
+              def self.label_for(labels, value)
+                labels.each { |range, label| return label if range.cover?(value) }
+                :unknown
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/homeostasis/cocoon/helpers/incubator.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Homeostasis
+        module Cocoon
+          module Helpers
+            class Incubator
+              include Constants
+
+              def initialize
+                @cocoons = {}
+              end
+
+              def create_cocoon(cocoon_type:, domain:, content: '', maturity: nil, protection: nil)
+                prune_cocoons
+                cocoon = Cocoon.new(
+                  cocoon_type: cocoon_type,
+                  domain:      domain,
+                  content:     content,
+                  maturity:    maturity,
+                  protection:  protection
+                )
+                @cocoons[cocoon.id] = cocoon
+                cocoon
+              end
+
+              def gestate_all!(rate = MATURITY_RATE)
+                @cocoons.each_value { |c| c.gestate!(rate) unless c.stage == :emerged }
+                self
+              end
+
+              def harvest_ready
+                ready = @cocoons.values.select(&:ready?)
+                results = ready.map(&:emerge!)
+                ready.each { |c| @cocoons.delete(c.id) if c.stage == :emerged }
+                results
+              end
+
+              def force_emerge(id)
+                cocoon = @cocoons[id]
+                return { success: false, error: 'cocoon not found' } unless cocoon
+
+                result = cocoon.expose!
+                @cocoons.delete(id) if cocoon.stage == :emerged
+                result
+              end
+
+              def by_stage(stage)
+                @cocoons.values.select { |c| c.stage == stage.to_sym }
+              end
+
+              def most_mature(limit: 5)
+                @cocoons.values.sort_by { |c| -c.maturity }.first(limit)
+              end
+
+              def incubator_report
+                total    = @cocoons.size
+                by_s     = Hash.new(0)
+                @cocoons.each_value { |c| by_s[c.stage] += 1 }
+                avg_mat  = total.zero? ? 0.0 : (@cocoons.values.sum(&:maturity) / total).round(10)
+                avg_prot = total.zero? ? 0.0 : (@cocoons.values.sum(&:protection) / total).round(10)
+
+                {
+                  total_cocoons:      total,
+                  average_maturity:   avg_mat,
+                  maturity_label:     Constants.label_for(MATURITY_LABELS, avg_mat),
+                  average_protection: avg_prot,
+                  stage_distribution: by_s,
+                  ready_count:        by_stage(:ready).size,
+                  most_mature:        most_mature(limit: 3).map(&:to_h)
+                }
+              end
+
+              def to_h
+                {
+                  total_cocoons:    @cocoons.size,
+                  average_maturity: @cocoons.empty? ? 0.0 : (@cocoons.values.sum(&:maturity) / @cocoons.size).round(10)
+                }
+              end
+
+              private
+
+              def prune_cocoons
+                return if @cocoons.size < MAX_COCOONS
+
+                emerged = @cocoons.values.select { |c| c.stage == :emerged }
+                emerged.each { |c| @cocoons.delete(c.id) }
+                return if @cocoons.size < MAX_COCOONS
+
+                sorted = @cocoons.values.sort_by(&:maturity)
+                to_remove = sorted.first(@cocoons.size - MAX_COCOONS + 1)
+                to_remove.each { |c| @cocoons.delete(c.id) }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/homeostasis/cocoon/runners/cognitive_cocoon.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Homeostasis
+        module Cocoon
+          module Runners
+            module CognitiveCocoon
+              include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+              def create_cocoon(cocoon_type:, domain:, content: '', maturity: nil,
+                                protection: nil, engine: nil, **)
+                eng = engine || @default_engine
+                cocoon = eng.create_cocoon(
+                  cocoon_type: cocoon_type,
+                  domain:      domain,
+                  content:     content,
+                  maturity:    maturity,
+                  protection:  protection
+                )
+                { success: true, cocoon: cocoon.to_h }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def gestate_all(rate: nil, engine: nil, **)
+                eng = engine || @default_engine
+                eng.gestate_all!(rate || Helpers::Constants::MATURITY_RATE)
+                { success: true }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def harvest_ready(engine: nil, **)
+                eng = engine || @default_engine
+                emerged = eng.harvest_ready
+                { success: true, count: emerged.size, emerged: emerged }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def force_emerge(id:, engine: nil, **)
+                eng = engine || @default_engine
+                result = eng.force_emerge(id)
+                result.merge(success: result[:error].nil?)
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def cocoon_status(engine: nil, **)
+                eng = engine || @default_engine
+                report = eng.incubator_report
+                { success: true, **report }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def list_by_stage(stage:, engine: nil, **)
+                eng = engine || @default_engine
+                cocoons = eng.by_stage(stage)
+                { success: true, stage: stage, count: cocoons.size, cocoons: cocoons.map(&:to_h) }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/homeostasis/cocoon/version.rb

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

data/lib/legion/extensions/agentic/homeostasis/cocoon.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+require_relative 'cocoon/version'
+require_relative 'cocoon/helpers/constants'
+require_relative 'cocoon/helpers/cocoon'
+require_relative 'cocoon/helpers/incubator'
+require_relative 'cocoon/runners/cognitive_cocoon'
+require_relative 'cocoon/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Homeostasis
+        module Cocoon
+        end
+      end
+    end
+  end
+end
+
+Legion::Extensions.extend(Legion::Extensions::Core) if Legion::Extensions.const_defined?(:Core)

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Homeostasis
+        module Core
+          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
+  end
+end

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Homeostasis
+        module Core
+          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
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Homeostasis
+        module Core
+          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
+  end
+end