lex-cognitive-metabolism 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 19eba116503c91b42ca676c5b7a5252973d32f83a8772a52c1c653af91da343b
+  data.tar.gz: d0f46b89bb8b79e725f43472ca8df65c30fe2053cefc2376d2d3d2f044631cfc
+SHA512:
+  metadata.gz: d574a9365e90c4113e59f6f41663b7acc5329cab7ed0f0557c28b466f70d34fb91fc3f49342bae457104f5bc47349a3b3a862cf1805caf2faced0f693466063a
+  data.tar.gz: c8d3ef82f31d6270c0928961d5bf00b5413738ca33d2252148cbb15d3aaf93d19bcb308a6b0975ea890eb5d92136b71c876b6efe1a8031b1fdf21e5cea29f0e2

data/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ci:
+    uses: LegionIO/.github/.github/workflows/ci.yml@main
+
+  release:
+    needs: ci
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    uses: LegionIO/.github/.github/workflows/release.yml@main
+    secrets:
+      rubygems-api-key: ${{ secrets.RUBYGEMS_API_KEY }}

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.gem
+.rspec_status
+Gemfile.lock

data/.rspec

@@ -0,0 +1,2 @@
+--require spec_helper
+--format documentation

data/.rubocop.yml

@@ -0,0 +1,58 @@
+AllCops:
+  TargetRubyVersion: 3.4
+  NewCops: enable
+  SuggestExtensions: false
+
+Layout/LineLength:
+  Max: 160
+
+Layout/SpaceAroundEqualsInParameterDefault:
+  EnforcedStyle: space
+
+Layout/HashAlignment:
+  EnforcedHashRocketStyle: table
+  EnforcedColonStyle: table
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/ModuleLength:
+  Max: 150
+
+Metrics/BlockLength:
+  Max: 40
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/AbcSize:
+  Max: 25
+
+Metrics/ParameterLists:
+  Max: 8
+  MaxOptionalParameters: 8
+
+Style/Documentation:
+  Enabled: false
+
+Style/SymbolArray:
+  Enabled: true
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Style/OneClassPerFile:
+  Exclude:
+    - 'spec/spec_helper.rb'
+
+Naming/FileName:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false
+
+Naming/PredicatePrefix:
+  Enabled: false

data/CLAUDE.md

@@ -0,0 +1,95 @@
+# lex-cognitive-metabolism
+
+**Level 3 Leaf Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-agentic/CLAUDE.md`
+
+## Purpose
+
+Energy reserve model for cognitive processing. Inspired by biological metabolism: spending energy on operations depletes reserves and degrades efficiency; recovery restores both. Catabolism converts complex structures into energy (breakdown for fuel); anabolism converts energy into structural value (building). Metabolic cycles track sequences of operations with timing and energy-per-operation metrics. Six operation types with defined costs: `perception` (5), `reasoning` (15), `creativity` (20), and others.
+
+## Gem Info
+
+- **Gem name**: `lex-cognitive-metabolism`
+- **Module**: `Legion::Extensions::CognitiveMetabolism`
+- **Version**: `0.1.0`
+- **Ruby**: `>= 3.4`
+- **License**: MIT
+
+## File Structure
+
+```
+lib/legion/extensions/cognitive_metabolism/
+  version.rb
+  client.rb
+  helpers/
+    constants.rb
+    energy_reserve.rb
+    metabolic_cycle.rb
+  runners/
+    cognitive_metabolism.rb
+```
+
+## Key Constants
+
+| Constant | Value | Purpose |
+|---|---|---|
+| `MAX_ENERGY` | `1000.0` | Maximum energy reserve |
+| `RESTING_METABOLIC_RATE` | `0.5` | Baseline energy consumed per idle cycle |
+| `RECOVERY_RATE` | `2.0` | Energy restored per recovery unit |
+| `EFFICIENCY_DECAY` | `0.01` | Efficiency reduction per energy-spending operation |
+| `OPERATION_COSTS` | hash | Per-type energy costs (perception=5, reasoning=15, creativity=20, etc.) |
+| `METABOLIC_STATES` | symbol array | `%i[hyperactive active resting recovering depleted]` |
+| `STATE_THRESHOLDS` | hash | Energy ratio thresholds for each metabolic state |
+
+## Helpers
+
+### `Helpers::EnergyReserve`
+Core energy tracker with efficiency modulator.
+
+- `energy_ratio` — `energy / MAX_ENERGY`
+- `state` — current metabolic state based on `energy_ratio` vs `STATE_THRESHOLDS`
+- `depleted?` — energy at or below zero
+- `spend!(operation_type)` — deducts operation cost divided by current efficiency; degrades efficiency by `EFFICIENCY_DECAY`
+- `recover!(amount)` — restores energy by `amount * RECOVERY_RATE`; partially restores efficiency at `0.5x` rate
+- `catabolize!(complexity)` — converts complexity * 10 into energy (breakdown)
+- `anabolize!(energy_amount)` — converts energy_amount to `structure_value` via efficiency ratio
+
+### `Helpers::MetabolicCycle`
+Records an operational cycle.
+
+- `record_operation(type:, cost:)` — appends operation record
+- `complete!` — marks cycle done, sets `completed_at`
+- `duration_seconds` — wall-clock duration
+- `average_energy_per_operation` — total cost / operation count
+
+## Runners
+
+Module: `Runners::CognitiveMetabolism`
+
+| Runner Method | Description |
+|---|---|
+| `create_reserve(initial_energy:)` | Initialize an energy reserve |
+| `spend_energy(operation_type:)` | Spend energy on an operation |
+| `recover(amount:)` | Restore energy and partial efficiency |
+| `catabolize(complexity:)` | Convert complexity to energy |
+| `anabolize(energy_amount:)` | Convert energy to structural value |
+| `metabolic_status` | Current reserve state |
+| `run_cycle(operations:)` | Execute a sequence of operations as a cycle |
+
+All runners return `{success: true/false, ...}` hashes.
+
+## Integration Points
+
+- `lex-tick` integration: `metabolic_status` can gate whether full-active mode is available (depleted reserve → fallback to sentinel)
+- `lex-cognitive-load`: extraneous load maps to energy overhead; reducing extraneous load = recovering energy
+- `lex-emotion` arousal correlates with energy level: depleted → low arousal
+- `lex-dream` dormant_active cycle can trigger `recover` operations during idle consolidation
+- Catabolism (breaking down old structures) parallels `lex-memory` decay: pruned traces release conceptual energy
+
+## Development Notes
+
+- `Client` instantiates a single `EnergyReserve`; runners operate on it
+- `spend!` cost is divided by efficiency: at `efficiency = 0.5`, operations cost double
+- `recover!` restores efficiency at `0.5x` rate to prevent instant full reset after recovery
+- `OPERATION_COSTS` keys must match the `operation_type:` argument to `spend_energy`; unknown types raise or return error
+- `MetabolicCycle` is a lightweight record object; it does not hold a reference to the reserve

data/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+gemspec
+
+group :test do
+  gem 'rspec', '~> 3.13'
+  gem 'rubocop', '~> 1.75', require: false
+  gem 'rubocop-rspec', require: false
+end
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Esity
+
+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,51 @@
+# lex-cognitive-metabolism
+
+Energy reserve and metabolic cycle model for LegionIO cognitive agents. Operations consume energy and degrade efficiency; recovery restores both. Catabolism breaks down complexity into energy; anabolism converts energy into structural value.
+
+## What It Does
+
+- Energy reserve with 5 metabolic states: hyperactive, active, resting, recovering, depleted
+- Six operation types with defined costs (perception=5, reasoning=15, creativity=20)
+- Efficiency modulator: spending energy degrades efficiency; higher operations cost more when efficiency is low
+- Recovery restores energy and partially restores efficiency
+- Catabolism: convert cognitive complexity into energy (useful during restructuring)
+- Anabolism: convert energy into structural value (useful when building new patterns)
+- Metabolic cycles: group sequences of operations with timing and cost metrics
+
+## Usage
+
+```ruby
+# Create a reserve
+runner.create_reserve(initial_energy: 500.0)
+
+# Spend energy on operations
+runner.spend_energy(operation_type: :reasoning)
+# => { success: true, spent: 15.0, remaining: 485.0, efficiency: 0.49, state: :active }
+
+runner.spend_energy(operation_type: :creativity)
+# => { success: true, spent: 20.0 / efficiency, ... }
+
+# Recover
+runner.recover(amount: 10.0)
+# => { success: true, restored: 20.0, efficiency_restored: 10.0, state: :active }
+
+# Catabolize to gain energy from complexity
+runner.catabolize(complexity: 5.0)
+# => { success: true, energy_gained: 50.0 }
+
+# Current status
+runner.metabolic_status
+# => { success: true, energy: 485.0, energy_ratio: 0.485, state: :active, efficiency: 0.49, ... }
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-metabolism.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_metabolism/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-metabolism'
+  spec.version       = Legion::Extensions::CognitiveMetabolism::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Cognitive Metabolism'
+  spec.description   = 'ATP-like cognitive energy system with metabolic cycles, catabolism, and anabolism for brain-modeled agentic AI'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-metabolism'
+  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-cognitive-metabolism'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-cognitive-metabolism'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-cognitive-metabolism'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-cognitive-metabolism/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_metabolism/helpers/constants'
+require 'legion/extensions/cognitive_metabolism/helpers/energy_reserve'
+require 'legion/extensions/cognitive_metabolism/helpers/metabolic_cycle'
+require 'legion/extensions/cognitive_metabolism/helpers/metabolism_engine'
+require 'legion/extensions/cognitive_metabolism/runners/cognitive_metabolism'
+
+module Legion
+  module Extensions
+    module CognitiveMetabolism
+      class Client
+        include Runners::CognitiveMetabolism
+
+        def initialize(**)
+          @engine = Helpers::MetabolismEngine.new
+        end
+
+        private
+
+        attr_reader :engine
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveMetabolism
+      module Helpers
+        module Constants
+          MAX_ENERGY = 1000.0
+          RESTING_METABOLIC_RATE = 0.5
+          RECOVERY_RATE        = 2.0
+          EFFICIENCY_DECAY     = 0.01
+
+          OPERATION_COSTS = {
+            perception:       5.0,
+            memory_retrieval: 8.0,
+            reasoning:        15.0,
+            creativity:       20.0,
+            decision:         12.0,
+            communication:    10.0
+          }.freeze
+
+          METABOLIC_STATES = %i[optimal efficient normal strained depleted].freeze
+
+          STATE_THRESHOLDS = {
+            optimal:   (0.8..),
+            efficient: (0.6...0.8),
+            normal:    (0.4...0.6),
+            strained:  (0.15...0.4),
+            depleted:  (..0.15)
+          }.freeze
+
+          module_function
+
+          def label_for(energy_ratio)
+            ratio = energy_ratio.clamp(0.0, 1.0)
+            STATE_THRESHOLDS.each do |state, range|
+              return state if range.cover?(ratio)
+            end
+            :depleted
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_metabolism/helpers/energy_reserve.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveMetabolism
+      module Helpers
+        class EnergyReserve
+          include Constants
+
+          attr_reader :id, :current_energy, :max_energy, :metabolic_rate, :efficiency, :created_at
+
+          def initialize(max_energy: MAX_ENERGY, metabolic_rate: RESTING_METABOLIC_RATE, efficiency: 1.0)
+            @id             = SecureRandom.uuid
+            @max_energy     = max_energy.clamp(1.0, Float::INFINITY)
+            @current_energy = @max_energy
+            @metabolic_rate = metabolic_rate.clamp(0.0, Float::INFINITY)
+            @efficiency     = efficiency.clamp(0.0, 1.0)
+            @created_at     = Time.now.utc
+          end
+
+          def energy_ratio
+            (@current_energy / @max_energy).clamp(0.0, 1.0)
+          end
+
+          def state
+            Constants.label_for(energy_ratio)
+          end
+
+          def depleted?
+            state == :depleted
+          end
+
+          def spend!(amount)
+            effective_cost = amount / @efficiency.clamp(0.01, 1.0)
+            before = @current_energy
+            @current_energy = (@current_energy - effective_cost).clamp(0.0, @max_energy)
+            @efficiency = (@efficiency - EFFICIENCY_DECAY).clamp(0.0, 1.0)
+            before - @current_energy
+          end
+
+          def recover!(amount)
+            before = @current_energy
+            @current_energy = (@current_energy + amount).clamp(0.0, @max_energy)
+            @efficiency = (@efficiency + (EFFICIENCY_DECAY * 0.5)).clamp(0.0, 1.0)
+            @current_energy - before
+          end
+
+          def catabolize!(complexity: 1.0)
+            energy_gained = (complexity * 10.0).round(10)
+            @current_energy = (@current_energy + energy_gained).clamp(0.0, @max_energy)
+            { energy_gained: energy_gained, current_energy: @current_energy.round(10), state: state }
+          end
+
+          def anabolize!(energy_cost: 5.0)
+            raise ArgumentError, 'insufficient energy for anabolism' if @current_energy < energy_cost
+
+            @current_energy = (@current_energy - energy_cost).clamp(0.0, @max_energy)
+            structure_value = (energy_cost * @efficiency).round(10)
+            { energy_spent: energy_cost, structure_value: structure_value, current_energy: @current_energy.round(10), state: state }
+          end
+
+          def to_h
+            {
+              id:             @id,
+              current_energy: @current_energy.round(10),
+              max_energy:     @max_energy,
+              metabolic_rate: @metabolic_rate,
+              efficiency:     @efficiency.round(10),
+              energy_ratio:   energy_ratio.round(10),
+              state:          state,
+              depleted:       depleted?,
+              created_at:     @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_metabolism/helpers/metabolic_cycle.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveMetabolism
+      module Helpers
+        class MetabolicCycle
+          attr_reader :id, :cycle_count, :operations_log, :energy_spent_this_cycle, :started_at, :completed_at
+
+          def initialize
+            @id                    = SecureRandom.uuid
+            @cycle_count           = 0
+            @operations_log        = []
+            @energy_spent_this_cycle = 0.0
+            @started_at            = Time.now.utc
+            @completed_at          = nil
+          end
+
+          def record_operation(operation_type:, energy_spent:)
+            @operations_log << {
+              operation_type: operation_type,
+              energy_spent:   energy_spent.round(10),
+              recorded_at:    Time.now.utc
+            }
+            @energy_spent_this_cycle += energy_spent
+            @cycle_count += 1
+          end
+
+          def complete!
+            @completed_at = Time.now.utc
+            to_h
+          end
+
+          def duration_seconds
+            return nil unless @completed_at
+
+            (@completed_at - @started_at).round(4)
+          end
+
+          def average_energy_per_operation
+            return 0.0 if @cycle_count.zero?
+
+            (@energy_spent_this_cycle / @cycle_count).round(10)
+          end
+
+          def to_h
+            {
+              id:                      @id,
+              cycle_count:             @cycle_count,
+              energy_spent_this_cycle: @energy_spent_this_cycle.round(10),
+              average_per_operation:   average_energy_per_operation,
+              operations_log:          @operations_log,
+              started_at:              @started_at,
+              completed_at:            @completed_at,
+              duration_seconds:        duration_seconds
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_metabolism/helpers/metabolism_engine.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveMetabolism
+      module Helpers
+        class MetabolismEngine
+          include Constants
+
+          MAX_EFFICIENCY_HISTORY = 200
+
+          def initialize
+            @reserves = {}
+            @efficiency_history = []
+          end
+
+          def create_reserve(max_energy: MAX_ENERGY, metabolic_rate: RESTING_METABOLIC_RATE, efficiency: 1.0)
+            reserve = EnergyReserve.new(max_energy: max_energy, metabolic_rate: metabolic_rate, efficiency: efficiency)
+            @reserves[reserve.id] = reserve
+            reserve
+          end
+
+          def spend_energy(reserve_id:, operation_type:)
+            reserve = fetch_reserve(reserve_id)
+            cost = OPERATION_COSTS.fetch(operation_type) do
+              raise ArgumentError, "Unknown operation type: #{operation_type.inspect}"
+            end
+            actual_spent = reserve.spend!(cost)
+            record_efficiency(reserve)
+            {
+              reserve_id:     reserve_id,
+              operation_type: operation_type,
+              base_cost:      cost,
+              actual_spent:   actual_spent.round(10),
+              current_energy: reserve.current_energy.round(10),
+              state:          reserve.state
+            }
+          end
+
+          def recover(reserve_id:, duration: 1.0)
+            reserve = fetch_reserve(reserve_id)
+            amount = (RECOVERY_RATE * duration.clamp(0.0, Float::INFINITY)).round(10)
+            gained = reserve.recover!(amount)
+            record_efficiency(reserve)
+            {
+              reserve_id:     reserve_id,
+              duration:       duration,
+              energy_gained:  gained.round(10),
+              current_energy: reserve.current_energy.round(10),
+              state:          reserve.state
+            }
+          end
+
+          def catabolize(reserve_id:, complexity: 1.0)
+            reserve = fetch_reserve(reserve_id)
+            result = reserve.catabolize!(complexity: complexity)
+            result.merge(reserve_id: reserve_id)
+          end
+
+          def anabolize(reserve_id:, energy_cost: 5.0)
+            reserve = fetch_reserve(reserve_id)
+            result = reserve.anabolize!(energy_cost: energy_cost)
+            result.merge(reserve_id: reserve_id)
+          end
+
+          def run_cycle(reserve_id:, operations: [])
+            reserve = fetch_reserve(reserve_id)
+            cycle   = MetabolicCycle.new
+
+            operations.each do |op_type|
+              cost_base = OPERATION_COSTS.fetch(op_type, 0.0)
+              reserve.spend!(cost_base) if cost_base > 0.0
+              cycle.record_operation(operation_type: op_type, energy_spent: cost_base)
+            end
+
+            reserve.spend!(reserve.metabolic_rate)
+            cycle.record_operation(operation_type: :resting_rate, energy_spent: reserve.metabolic_rate)
+
+            cycle.complete!.merge(reserve_state: reserve.state, reserve_energy: reserve.current_energy.round(10))
+          end
+
+          def metabolic_report(reserve_id:)
+            reserve = fetch_reserve(reserve_id)
+            {
+              reserve:            reserve.to_h,
+              efficiency_history: efficiency_history_for(reserve_id)
+            }
+          end
+
+          def efficiency_history
+            @efficiency_history.dup
+          end
+
+          def all_reserves
+            @reserves.transform_values(&:to_h)
+          end
+
+          private
+
+          def fetch_reserve(id)
+            @reserves.fetch(id) { raise ArgumentError, "Unknown reserve: #{id.inspect}" }
+          end
+
+          def record_efficiency(reserve)
+            @efficiency_history << {
+              reserve_id:  reserve.id,
+              efficiency:  reserve.efficiency.round(10),
+              state:       reserve.state,
+              recorded_at: Time.now.utc
+            }
+            @efficiency_history.shift while @efficiency_history.size > MAX_EFFICIENCY_HISTORY
+          end
+
+          def efficiency_history_for(reserve_id)
+            @efficiency_history.select { |e| e[:reserve_id] == reserve_id }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveMetabolism
+      module Runners
+        module CognitiveMetabolism
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def create_reserve(max_energy: Helpers::Constants::MAX_ENERGY,
+                             metabolic_rate: Helpers::Constants::RESTING_METABOLIC_RATE,
+                             efficiency: 1.0, **)
+            reserve = engine.create_reserve(max_energy: max_energy, metabolic_rate: metabolic_rate, efficiency: efficiency)
+            Legion::Logging.debug "[cognitive_metabolism] reserve created: id=#{reserve.id} max_energy=#{reserve.max_energy}"
+            { success: true, reserve: reserve.to_h }
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def spend_energy(reserve_id:, operation_type:, **)
+            result = engine.spend_energy(reserve_id: reserve_id, operation_type: operation_type)
+            Legion::Logging.debug "[cognitive_metabolism] spend: reserve=#{reserve_id} op=#{operation_type} " \
+                                  "spent=#{result[:actual_spent]} state=#{result[:state]}"
+            { success: true }.merge(result)
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def recover(reserve_id:, duration: 1.0, **)
+            result = engine.recover(reserve_id: reserve_id, duration: duration)
+            Legion::Logging.debug "[cognitive_metabolism] recover: reserve=#{reserve_id} " \
+                                  "gained=#{result[:energy_gained]} state=#{result[:state]}"
+            { success: true }.merge(result)
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def catabolize(reserve_id:, complexity: 1.0, **)
+            result = engine.catabolize(reserve_id: reserve_id, complexity: complexity)
+            Legion::Logging.debug "[cognitive_metabolism] catabolize: reserve=#{reserve_id} " \
+                                  "complexity=#{complexity} gained=#{result[:energy_gained]}"
+            { success: true }.merge(result)
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def anabolize(reserve_id:, energy_cost: 5.0, **)
+            result = engine.anabolize(reserve_id: reserve_id, energy_cost: energy_cost)
+            Legion::Logging.debug "[cognitive_metabolism] anabolize: reserve=#{reserve_id} " \
+                                  "cost=#{energy_cost} value=#{result[:structure_value]}"
+            { success: true }.merge(result)
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def metabolic_status(reserve_id:, **)
+            result = engine.metabolic_report(reserve_id: reserve_id)
+            Legion::Logging.debug "[cognitive_metabolism] status: reserve=#{reserve_id} state=#{result[:reserve][:state]}"
+            { success: true }.merge(result)
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          def run_cycle(reserve_id:, operations: [], **)
+            result = engine.run_cycle(reserve_id: reserve_id, operations: operations)
+            Legion::Logging.debug "[cognitive_metabolism] cycle: reserve=#{reserve_id} " \
+                                  "ops=#{result[:cycle_count]} spent=#{result[:energy_spent_this_cycle]} state=#{result[:reserve_state]}"
+            { success: true }.merge(result)
+          rescue ArgumentError => e
+            { success: false, error: e.message }
+          end
+
+          private
+
+          def engine
+            @engine ||= Helpers::MetabolismEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_metabolism.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'legion/extensions/cognitive_metabolism/version'
+require 'legion/extensions/cognitive_metabolism/helpers/constants'
+require 'legion/extensions/cognitive_metabolism/helpers/energy_reserve'
+require 'legion/extensions/cognitive_metabolism/helpers/metabolic_cycle'
+require 'legion/extensions/cognitive_metabolism/helpers/metabolism_engine'
+require 'legion/extensions/cognitive_metabolism/runners/cognitive_metabolism'
+require 'legion/extensions/cognitive_metabolism/client'
+
+module Legion
+  module Extensions
+    module CognitiveMetabolism
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: lex-cognitive-metabolism
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Esity
+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: ATP-like cognitive energy system with metabolic cycles, catabolism, and
+  anabolism for brain-modeled agentic AI
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- CLAUDE.md
+- Gemfile
+- LICENSE
+- README.md
+- lex-cognitive-metabolism.gemspec
+- lib/legion/extensions/cognitive_metabolism.rb
+- lib/legion/extensions/cognitive_metabolism/client.rb
+- lib/legion/extensions/cognitive_metabolism/helpers/constants.rb
+- lib/legion/extensions/cognitive_metabolism/helpers/energy_reserve.rb
+- lib/legion/extensions/cognitive_metabolism/helpers/metabolic_cycle.rb
+- lib/legion/extensions/cognitive_metabolism/helpers/metabolism_engine.rb
+- lib/legion/extensions/cognitive_metabolism/runners/cognitive_metabolism.rb
+- lib/legion/extensions/cognitive_metabolism/version.rb
+homepage: https://github.com/LegionIO/lex-cognitive-metabolism
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-cognitive-metabolism
+  source_code_uri: https://github.com/LegionIO/lex-cognitive-metabolism
+  documentation_uri: https://github.com/LegionIO/lex-cognitive-metabolism
+  changelog_uri: https://github.com/LegionIO/lex-cognitive-metabolism
+  bug_tracker_uri: https://github.com/LegionIO/lex-cognitive-metabolism/issues
+  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: LEX Cognitive Metabolism
+test_files: []