lex-neuromodulation 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9699c48e6cd9388c89541b230de7e5bfdec101a9be590af7ac37d9ee61453ef2
+  data.tar.gz: 48ca816c952d030a32969e5f02b226377d51b28e7374a47e22ff4949d164e075
+SHA512:
+  metadata.gz: 07ec0cda24a8ad10c7541477fd5f5da565c8f074f5d5faf580e073685ccdba703f8906af7422e9edff7d445f8df2442b453bc12f08062b3d4d5af13bf65a8a10
+  data.tar.gz: d4c84c120625ac383bd2f25428e80b6430dfd0bb51d4ff90a136eb4e91cb07e4644fdcc18ccaab181045fec41e66505f7fbadf7da29f57e591a39402e07dbf9b

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/lex-neuromodulation.gemspec

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

data/lib/legion/extensions/neuromodulation/actors/drift.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module Neuromodulation
+      module Actor
+        class Drift < Legion::Extensions::Actors::Every
+          def runner_class
+            Legion::Extensions::Neuromodulation::Runners::Neuromodulation
+          end
+
+          def runner_function
+            'update_neuromodulation'
+          end
+
+          def time
+            30
+          end
+
+          def run_now?
+            false
+          end
+
+          def use_runner?
+            false
+          end
+
+          def check_subtask?
+            false
+          end
+
+          def generate_task?
+            false
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/neuromodulation/helpers/constants'
+require 'legion/extensions/neuromodulation/helpers/modulator'
+require 'legion/extensions/neuromodulation/helpers/modulator_system'
+require 'legion/extensions/neuromodulation/runners/neuromodulation'
+
+module Legion
+  module Extensions
+    module Neuromodulation
+      class Client
+        include Runners::Neuromodulation
+
+        def initialize(system: nil, **)
+          @neuromod_system = system || Helpers::ModulatorSystem.new
+        end
+
+        private
+
+        attr_reader :neuromod_system
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Neuromodulation
+      module Helpers
+        module Constants
+          MODULATORS         = %i[dopamine serotonin norepinephrine acetylcholine].freeze
+          DEFAULT_LEVEL      = 0.5
+          LEVEL_FLOOR        = 0.0
+          LEVEL_CEILING      = 1.0
+          MODULATION_ALPHA   = 0.15
+          BASELINE_DRIFT     = 0.01
+          MAX_EVENTS         = 200
+
+          OPTIMAL_RANGES = {
+            dopamine:       (0.4..0.7),
+            serotonin:      (0.4..0.7),
+            norepinephrine: (0.3..0.6),
+            acetylcholine:  (0.4..0.7)
+          }.freeze
+
+          STATE_LABELS = {
+            dopamine:       {
+              high:    :surplus,
+              optimal: :optimal,
+              low:     :deficit
+            },
+            serotonin:      {
+              high:    :surplus,
+              optimal: :optimal,
+              low:     :deficit
+            },
+            norepinephrine: {
+              high:    :surplus,
+              optimal: :optimal,
+              low:     :deficit
+            },
+            acetylcholine:  {
+              high:    :surplus,
+              optimal: :optimal,
+              low:     :deficit
+            }
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/neuromodulation/helpers/modulator.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Neuromodulation
+      module Helpers
+        class Modulator
+          include Constants
+
+          attr_reader :name, :level, :baseline, :events
+
+          def initialize(name)
+            @name     = name
+            @level    = DEFAULT_LEVEL
+            @baseline = DEFAULT_LEVEL
+            @events   = []
+          end
+
+          def boost(amount, reason: nil)
+            old_level = @level
+            @level    = clamp(@level + amount)
+            record_event(:boost, amount, reason, old_level)
+            @level
+          end
+
+          def suppress(amount, reason: nil)
+            old_level = @level
+            @level    = clamp(@level - amount)
+            record_event(:suppress, amount, reason, old_level)
+            @level
+          end
+
+          def drift_to_baseline
+            delta  = @baseline - @level
+            @level = clamp(@level + (delta * BASELINE_DRIFT))
+          end
+
+          def optimal?
+            OPTIMAL_RANGES.fetch(@name).include?(@level)
+          end
+
+          def state_label
+            range = OPTIMAL_RANGES.fetch(@name)
+            if @level > range.end
+              STATE_LABELS.dig(@name, :high)
+            elsif @level < range.begin
+              STATE_LABELS.dig(@name, :low)
+            else
+              STATE_LABELS.dig(@name, :optimal)
+            end
+          end
+
+          INFLUENCE_MAP = {
+            dopamine:       %i[learning_rate exploration_bias],
+            serotonin:      %i[patience_factor],
+            norepinephrine: %i[arousal_level attention_precision],
+            acetylcholine:  %i[memory_encoding attention_precision]
+          }.freeze
+
+          def influence_on(target_property)
+            relevant = INFLUENCE_MAP.fetch(@name, [])
+            return 0.0 unless relevant.include?(target_property)
+
+            scale(@level)
+          end
+
+          def to_h
+            {
+              name:        @name,
+              level:       @level.round(4),
+              baseline:    @baseline.round(4),
+              state:       state_label,
+              optimal:     optimal?,
+              event_count: @events.size
+            }
+          end
+
+          private
+
+          def clamp(value)
+            value.clamp(LEVEL_FLOOR, LEVEL_CEILING)
+          end
+
+          def scale(value)
+            (value - DEFAULT_LEVEL) * 2.0
+          end
+
+          def record_event(type, amount, reason, old_level)
+            @events << {
+              type:      type,
+              amount:    amount,
+              reason:    reason,
+              old_level: old_level.round(4),
+              new_level: @level.round(4),
+              timestamp: Time.now.utc
+            }
+            @events.shift while @events.size > MAX_EVENTS
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/neuromodulation/helpers/modulator_system.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Neuromodulation
+      module Helpers
+        class ModulatorSystem
+          include Constants
+
+          attr_reader :modulators
+
+          def initialize
+            @modulators = MODULATORS.to_h { |name| [name, Modulator.new(name)] }
+          end
+
+          def boost(name, amount, reason: nil)
+            validate_name!(name)
+            result = @modulators[name].boost(amount, reason: reason)
+            apply_interactions(name)
+            result
+          end
+
+          def suppress(name, amount, reason: nil)
+            validate_name!(name)
+            result = @modulators[name].suppress(amount, reason: reason)
+            apply_interactions(name)
+            result
+          end
+
+          def level(name)
+            validate_name!(name)
+            @modulators[name].level
+          end
+
+          def all_levels
+            @modulators.transform_values(&:level)
+          end
+
+          def tick
+            @modulators.each_value(&:drift_to_baseline)
+          end
+
+          def learning_rate_modifier
+            da = @modulators[:dopamine].level
+            ach = @modulators[:acetylcholine].level
+            clamp((da * 0.6) + (ach * 0.4))
+          end
+
+          def attention_precision
+            ne = @modulators[:norepinephrine].level
+            ach = @modulators[:acetylcholine].level
+            clamp((ne * 0.5) + (ach * 0.5))
+          end
+
+          def exploration_bias
+            @modulators[:dopamine].level
+          end
+
+          def patience_factor
+            @modulators[:serotonin].level
+          end
+
+          def memory_encoding_strength
+            @modulators[:acetylcholine].level
+          end
+
+          def arousal_level
+            @modulators[:norepinephrine].level
+          end
+
+          def composite_influences
+            {
+              learning_rate_modifier:   learning_rate_modifier.round(4),
+              attention_precision:      attention_precision.round(4),
+              exploration_bias:         exploration_bias.round(4),
+              patience_factor:          patience_factor.round(4),
+              memory_encoding_strength: memory_encoding_strength.round(4),
+              arousal_level:            arousal_level.round(4)
+            }
+          end
+
+          def balance_score
+            in_range = @modulators.values.count(&:optimal?)
+            in_range.to_f / @modulators.size
+          end
+
+          def to_h
+            {
+              modulators: @modulators.transform_values(&:to_h),
+              influences: composite_influences,
+              balance:    balance_score.round(4)
+            }
+          end
+
+          private
+
+          def validate_name!(name)
+            raise ArgumentError, "Unknown modulator: #{name}" unless MODULATORS.include?(name)
+          end
+
+          def clamp(value)
+            value.clamp(LEVEL_FLOOR, LEVEL_CEILING)
+          end
+
+          def apply_interactions(changed)
+            case changed
+            when :dopamine
+              high_da = @modulators[:dopamine].level > 0.7
+              @modulators[:serotonin].suppress(0.05, reason: :dopamine_suppression) if high_da
+            when :norepinephrine
+              high_ne = @modulators[:norepinephrine].level > 0.8
+              @modulators[:acetylcholine].suppress(0.03, reason: :ne_suppression) if high_ne
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Neuromodulation
+      module Runners
+        module Neuromodulation
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def boost_modulator(name:, amount:, reason: nil, **)
+            mod_name = name.to_sym
+            return { success: false, error: "Unknown modulator: #{name}" } unless Helpers::Constants::MODULATORS.include?(mod_name)
+
+            new_level = neuromod_system.boost(mod_name, amount.to_f, reason: reason)
+            Legion::Logging.debug "[neuromodulation] boost #{mod_name} by #{amount} -> #{new_level.round(4)}"
+            {
+              success:   true,
+              modulator: mod_name,
+              level:     new_level.round(4),
+              state:     neuromod_system.modulators[mod_name].state_label
+            }
+          end
+
+          def suppress_modulator(name:, amount:, reason: nil, **)
+            mod_name = name.to_sym
+            return { success: false, error: "Unknown modulator: #{name}" } unless Helpers::Constants::MODULATORS.include?(mod_name)
+
+            new_level = neuromod_system.suppress(mod_name, amount.to_f, reason: reason)
+            Legion::Logging.debug "[neuromodulation] suppress #{mod_name} by #{amount} -> #{new_level.round(4)}"
+            {
+              success:   true,
+              modulator: mod_name,
+              level:     new_level.round(4),
+              state:     neuromod_system.modulators[mod_name].state_label
+            }
+          end
+
+          def modulator_level(name:, **)
+            mod_name = name.to_sym
+            return { success: false, error: "Unknown modulator: #{name}" } unless Helpers::Constants::MODULATORS.include?(mod_name)
+
+            level = neuromod_system.level(mod_name)
+            {
+              success:   true,
+              modulator: mod_name,
+              level:     level.round(4),
+              state:     neuromod_system.modulators[mod_name].state_label
+            }
+          end
+
+          def all_modulator_levels(**)
+            levels = neuromod_system.all_levels
+            Legion::Logging.debug "[neuromodulation] all levels: #{levels.map { |k, v| "#{k}=#{v.round(3)}" }.join(' ')}"
+            { success: true, levels: levels.transform_values { |v| v.round(4) } }
+          end
+
+          def cognitive_influence(**)
+            influences = neuromod_system.composite_influences
+            Legion::Logging.debug '[neuromodulation] cognitive influence snapshot'
+            { success: true, influences: influences }
+          end
+
+          def is_optimal(name:, **)
+            mod_name = name.to_sym
+            return { success: false, error: "Unknown modulator: #{name}" } unless Helpers::Constants::MODULATORS.include?(mod_name)
+
+            optimal = neuromod_system.modulators[mod_name].optimal?
+            {
+              success:   true,
+              modulator: mod_name,
+              optimal:   optimal,
+              level:     neuromod_system.level(mod_name).round(4),
+              range:     Helpers::Constants::OPTIMAL_RANGES[mod_name].to_s
+            }
+          end
+
+          def system_balance(**)
+            score = neuromod_system.balance_score
+            states = neuromod_system.modulators.transform_values(&:state_label)
+            status = if score >= 1.0
+                       :fully_balanced
+                     elsif score >= 0.75
+                       :mostly_balanced
+                     elsif score >= 0.5
+                       :partially_balanced
+                     else
+                       :imbalanced
+                     end
+            Legion::Logging.debug "[neuromodulation] system balance: #{score.round(2)} status=#{status}"
+            {
+              success: true,
+              score:   score.round(4),
+              status:  status,
+              states:  states
+            }
+          end
+
+          def modulator_history(name:, limit: 20, **)
+            mod_name = name.to_sym
+            return { success: false, error: "Unknown modulator: #{name}" } unless Helpers::Constants::MODULATORS.include?(mod_name)
+
+            events = neuromod_system.modulators[mod_name].events.last(limit.to_i)
+            {
+              success:   true,
+              modulator: mod_name,
+              events:    events,
+              count:     events.size
+            }
+          end
+
+          def update_neuromodulation(**)
+            neuromod_system.tick
+            levels = neuromod_system.all_levels
+            Legion::Logging.debug '[neuromodulation] drift tick completed'
+            {
+              success: true,
+              action:  :drift_tick,
+              levels:  levels.transform_values { |v| v.round(4) }
+            }
+          end
+
+          def neuromodulation_stats(**)
+            {
+              success: true,
+              system:  neuromod_system.to_h
+            }
+          end
+
+          private
+
+          def neuromod_system
+            @neuromod_system ||= Helpers::ModulatorSystem.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/neuromodulation.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/neuromodulation/version'
+require 'legion/extensions/neuromodulation/helpers/constants'
+require 'legion/extensions/neuromodulation/helpers/modulator'
+require 'legion/extensions/neuromodulation/helpers/modulator_system'
+require 'legion/extensions/neuromodulation/runners/neuromodulation'
+
+module Legion
+  module Extensions
+    module Neuromodulation
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

data/spec/legion/extensions/neuromodulation/client_spec.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/neuromodulation/client'
+
+RSpec.describe Legion::Extensions::Neuromodulation::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to all runner methods' do
+    expect(client).to respond_to(:boost_modulator)
+    expect(client).to respond_to(:suppress_modulator)
+    expect(client).to respond_to(:modulator_level)
+    expect(client).to respond_to(:all_modulator_levels)
+    expect(client).to respond_to(:cognitive_influence)
+    expect(client).to respond_to(:is_optimal)
+    expect(client).to respond_to(:system_balance)
+    expect(client).to respond_to(:modulator_history)
+    expect(client).to respond_to(:update_neuromodulation)
+    expect(client).to respond_to(:neuromodulation_stats)
+  end
+
+  it 'accepts an injected system' do
+    system = Legion::Extensions::Neuromodulation::Helpers::ModulatorSystem.new
+    system.boost(:dopamine, 0.3)
+    c = described_class.new(system: system)
+    result = c.modulator_level(name: :dopamine)
+    expect(result[:level]).to be > 0.5
+  end
+
+  it 'maintains state across calls' do
+    client.boost_modulator(name: :acetylcholine, amount: 0.2)
+    level_result = client.modulator_level(name: :acetylcholine)
+    expect(level_result[:level]).to be_within(0.001).of(0.7)
+  end
+
+  it 'round-trips a full neuromodulation cycle' do
+    client.boost_modulator(name: :dopamine, amount: 0.15)
+    client.suppress_modulator(name: :serotonin, amount: 0.1)
+    ci = client.cognitive_influence
+    expect(ci[:influences][:exploration_bias]).to be > 0.5
+    expect(ci[:influences][:patience_factor]).to be < 0.5
+    client.update_neuromodulation
+    stats = client.neuromodulation_stats
+    expect(stats[:system][:modulators][:dopamine][:level]).to be_a(Float)
+  end
+end

data/spec/legion/extensions/neuromodulation/helpers/constants_spec.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Neuromodulation::Helpers::Constants do
+  let(:mod) { Legion::Extensions::Neuromodulation::Helpers::Constants }
+
+  describe 'MODULATORS' do
+    it 'contains the four neuromodulator names' do
+      expect(mod::MODULATORS).to contain_exactly(:dopamine, :serotonin, :norepinephrine, :acetylcholine)
+    end
+
+    it 'is frozen' do
+      expect(mod::MODULATORS).to be_frozen
+    end
+  end
+
+  describe 'OPTIMAL_RANGES' do
+    it 'defines a range for each modulator' do
+      mod::MODULATORS.each do |name|
+        expect(mod::OPTIMAL_RANGES[name]).to be_a(Range)
+      end
+    end
+
+    it 'has non-overlapping floor/ceiling bounds' do
+      mod::OPTIMAL_RANGES.each_value do |range|
+        expect(range.begin).to be >= mod::LEVEL_FLOOR
+        expect(range.end).to be <= mod::LEVEL_CEILING
+      end
+    end
+  end
+
+  describe 'numeric constants' do
+    it 'DEFAULT_LEVEL is 0.5' do
+      expect(mod::DEFAULT_LEVEL).to eq(0.5)
+    end
+
+    it 'LEVEL_FLOOR is 0.0' do
+      expect(mod::LEVEL_FLOOR).to eq(0.0)
+    end
+
+    it 'LEVEL_CEILING is 1.0' do
+      expect(mod::LEVEL_CEILING).to eq(1.0)
+    end
+
+    it 'MODULATION_ALPHA is 0.15' do
+      expect(mod::MODULATION_ALPHA).to eq(0.15)
+    end
+
+    it 'BASELINE_DRIFT is 0.01' do
+      expect(mod::BASELINE_DRIFT).to eq(0.01)
+    end
+
+    it 'MAX_EVENTS is 200' do
+      expect(mod::MAX_EVENTS).to eq(200)
+    end
+  end
+
+  describe 'STATE_LABELS' do
+    it 'defines high/optimal/low labels for each modulator' do
+      mod::MODULATORS.each do |name|
+        expect(mod::STATE_LABELS[name]).to have_key(:high)
+        expect(mod::STATE_LABELS[name]).to have_key(:optimal)
+        expect(mod::STATE_LABELS[name]).to have_key(:low)
+      end
+    end
+  end
+end

data/spec/legion/extensions/neuromodulation/helpers/modulator_spec.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Neuromodulation::Helpers::Modulator do
+  subject(:mod) { described_class.new(:dopamine) }
+
+  describe '#initialize' do
+    it 'sets name' do
+      expect(mod.name).to eq(:dopamine)
+    end
+
+    it 'sets level to DEFAULT_LEVEL' do
+      expect(mod.level).to eq(0.5)
+    end
+
+    it 'sets baseline to DEFAULT_LEVEL' do
+      expect(mod.baseline).to eq(0.5)
+    end
+
+    it 'starts with empty events' do
+      expect(mod.events).to be_empty
+    end
+  end
+
+  describe '#boost' do
+    it 'increases level' do
+      mod.boost(0.2)
+      expect(mod.level).to be_within(0.001).of(0.7)
+    end
+
+    it 'clamps at LEVEL_CEILING' do
+      mod.boost(1.0)
+      expect(mod.level).to eq(1.0)
+    end
+
+    it 'records an event' do
+      mod.boost(0.1, reason: :reward)
+      expect(mod.events.size).to eq(1)
+      expect(mod.events.last[:type]).to eq(:boost)
+      expect(mod.events.last[:reason]).to eq(:reward)
+    end
+
+    it 'returns the new level' do
+      result = mod.boost(0.1)
+      expect(result).to be_within(0.001).of(0.6)
+    end
+  end
+
+  describe '#suppress' do
+    it 'decreases level' do
+      mod.suppress(0.2)
+      expect(mod.level).to be_within(0.001).of(0.3)
+    end
+
+    it 'clamps at LEVEL_FLOOR' do
+      mod.suppress(1.0)
+      expect(mod.level).to eq(0.0)
+    end
+
+    it 'records an event' do
+      mod.suppress(0.1, reason: :fatigue)
+      expect(mod.events.size).to eq(1)
+      expect(mod.events.last[:type]).to eq(:suppress)
+      expect(mod.events.last[:reason]).to eq(:fatigue)
+    end
+
+    it 'returns the new level' do
+      result = mod.suppress(0.1)
+      expect(result).to be_within(0.001).of(0.4)
+    end
+  end
+
+  describe '#drift_to_baseline' do
+    it 'moves level toward baseline' do
+      mod.boost(0.3)
+      level_before = mod.level
+      mod.drift_to_baseline
+      expect(mod.level).to be < level_before
+    end
+
+    it 'does not overshoot baseline' do
+      mod.boost(0.3)
+      100.times { mod.drift_to_baseline }
+      expect(mod.level).to be >= mod.baseline
+    end
+  end
+
+  describe '#optimal?' do
+    it 'returns true when level is in optimal range' do
+      expect(mod.optimal?).to be true
+    end
+
+    it 'returns false when level is too high' do
+      mod.boost(0.5)
+      expect(mod.optimal?).to be false
+    end
+
+    it 'returns false when level is too low' do
+      mod.suppress(0.4)
+      expect(mod.optimal?).to be false
+    end
+  end
+
+  describe '#state_label' do
+    it 'returns :optimal at default level' do
+      expect(mod.state_label).to eq(:optimal)
+    end
+
+    it 'returns :surplus when high' do
+      mod.boost(0.4)
+      expect(mod.state_label).to eq(:surplus)
+    end
+
+    it 'returns :deficit when low' do
+      mod.suppress(0.4)
+      expect(mod.state_label).to eq(:deficit)
+    end
+  end
+
+  describe '#influence_on' do
+    it 'returns a numeric influence for known property' do
+      expect(mod.influence_on(:learning_rate)).to be_a(Numeric)
+    end
+
+    it 'returns 0.0 for unknown property' do
+      expect(mod.influence_on(:unknown_property)).to eq(0.0)
+    end
+
+    it 'returns higher influence when level is high' do
+      mod.boost(0.3)
+      high_influence = mod.influence_on(:learning_rate)
+      mod2 = described_class.new(:dopamine)
+      mod2.suppress(0.3)
+      low_influence = mod2.influence_on(:learning_rate)
+      expect(high_influence).to be > low_influence
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with required keys' do
+      h = mod.to_h
+      expect(h).to have_key(:name)
+      expect(h).to have_key(:level)
+      expect(h).to have_key(:baseline)
+      expect(h).to have_key(:state)
+      expect(h).to have_key(:optimal)
+      expect(h).to have_key(:event_count)
+    end
+
+    it 'reflects current state' do
+      mod.boost(0.3)
+      h = mod.to_h
+      expect(h[:level]).to be > 0.5
+      expect(h[:event_count]).to eq(1)
+    end
+  end
+
+  describe 'event ring buffer' do
+    it 'caps events at MAX_EVENTS' do
+      250.times { mod.boost(0.001) }
+      expect(mod.events.size).to eq(200)
+    end
+  end
+end

data/spec/legion/extensions/neuromodulation/helpers/modulator_system_spec.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Neuromodulation::Helpers::ModulatorSystem do
+  subject(:system) { described_class.new }
+
+  describe '#initialize' do
+    it 'creates all four modulators' do
+      expect(system.modulators.keys).to contain_exactly(:dopamine, :serotonin, :norepinephrine, :acetylcholine)
+    end
+
+    it 'starts each at default level' do
+      system.modulators.each_value do |mod|
+        expect(mod.level).to eq(0.5)
+      end
+    end
+  end
+
+  describe '#boost' do
+    it 'raises for unknown modulator' do
+      expect { system.boost(:cortisol, 0.1) }.to raise_error(ArgumentError)
+    end
+
+    it 'increases the target modulator level' do
+      system.boost(:dopamine, 0.2)
+      expect(system.level(:dopamine)).to be_within(0.001).of(0.7)
+    end
+
+    it 'applies dopamine->serotonin suppression when dopamine goes high' do
+      serotonin_before = system.level(:serotonin)
+      system.boost(:dopamine, 0.3)
+      expect(system.level(:serotonin)).to be < serotonin_before
+    end
+
+    it 'does not suppress serotonin for moderate dopamine boost' do
+      serotonin_before = system.level(:serotonin)
+      system.boost(:dopamine, 0.05)
+      expect(system.level(:serotonin)).to eq(serotonin_before)
+    end
+  end
+
+  describe '#suppress' do
+    it 'raises for unknown modulator' do
+      expect { system.suppress(:cortisol, 0.1) }.to raise_error(ArgumentError)
+    end
+
+    it 'decreases the target modulator level' do
+      system.suppress(:serotonin, 0.2)
+      expect(system.level(:serotonin)).to be_within(0.001).of(0.3)
+    end
+
+    it 'applies norepinephrine->acetylcholine suppression when NE goes very high' do
+      ach_before = system.level(:acetylcholine)
+      system.boost(:norepinephrine, 0.35)
+      expect(system.level(:acetylcholine)).to be < ach_before
+    end
+  end
+
+  describe '#level' do
+    it 'raises for unknown modulator' do
+      expect { system.level(:unknown) }.to raise_error(ArgumentError)
+    end
+
+    it 'returns current level' do
+      expect(system.level(:dopamine)).to eq(0.5)
+    end
+  end
+
+  describe '#all_levels' do
+    it 'returns a hash with all four modulators' do
+      levels = system.all_levels
+      expect(levels.keys).to contain_exactly(:dopamine, :serotonin, :norepinephrine, :acetylcholine)
+    end
+
+    it 'reflects current state' do
+      system.boost(:dopamine, 0.2)
+      levels = system.all_levels
+      expect(levels[:dopamine]).to be > 0.5
+    end
+  end
+
+  describe '#tick' do
+    it 'drifts all modulators toward baseline' do
+      system.boost(:dopamine, 0.3)
+      level_before = system.level(:dopamine)
+      system.tick
+      expect(system.level(:dopamine)).to be < level_before
+    end
+
+    it 'processes all four modulators' do
+      system.boost(:norepinephrine, 0.2)
+      system.suppress(:serotonin, 0.2)
+      ne_before   = system.level(:norepinephrine)
+      ser_before  = system.level(:serotonin)
+      system.tick
+      expect(system.level(:norepinephrine)).to be < ne_before
+      expect(system.level(:serotonin)).to be > ser_before
+    end
+  end
+
+  describe 'composite influences' do
+    describe '#learning_rate_modifier' do
+      it 'returns a value between 0 and 1' do
+        expect(system.learning_rate_modifier).to be_between(0.0, 1.0)
+      end
+
+      it 'increases with higher dopamine' do
+        base = system.learning_rate_modifier
+        system.boost(:dopamine, 0.2)
+        expect(system.learning_rate_modifier).to be > base
+      end
+    end
+
+    describe '#attention_precision' do
+      it 'returns a value between 0 and 1' do
+        expect(system.attention_precision).to be_between(0.0, 1.0)
+      end
+
+      it 'increases with higher norepinephrine' do
+        base = system.attention_precision
+        system.boost(:norepinephrine, 0.1)
+        expect(system.attention_precision).to be > base
+      end
+    end
+
+    describe '#exploration_bias' do
+      it 'equals dopamine level' do
+        expect(system.exploration_bias).to eq(system.level(:dopamine))
+      end
+    end
+
+    describe '#patience_factor' do
+      it 'equals serotonin level' do
+        expect(system.patience_factor).to eq(system.level(:serotonin))
+      end
+    end
+
+    describe '#memory_encoding_strength' do
+      it 'equals acetylcholine level' do
+        expect(system.memory_encoding_strength).to eq(system.level(:acetylcholine))
+      end
+    end
+
+    describe '#arousal_level' do
+      it 'equals norepinephrine level' do
+        expect(system.arousal_level).to eq(system.level(:norepinephrine))
+      end
+    end
+
+    describe '#composite_influences' do
+      it 'returns a hash with all influence keys' do
+        ci = system.composite_influences
+        expect(ci).to have_key(:learning_rate_modifier)
+        expect(ci).to have_key(:attention_precision)
+        expect(ci).to have_key(:exploration_bias)
+        expect(ci).to have_key(:patience_factor)
+        expect(ci).to have_key(:memory_encoding_strength)
+        expect(ci).to have_key(:arousal_level)
+      end
+    end
+  end
+
+  describe '#balance_score' do
+    it 'returns 1.0 when all modulators are optimal' do
+      expect(system.balance_score).to eq(1.0)
+    end
+
+    it 'decreases when a modulator goes out of range' do
+      system.boost(:dopamine, 0.5)
+      expect(system.balance_score).to be < 1.0
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns modulators, influences, and balance' do
+      h = system.to_h
+      expect(h).to have_key(:modulators)
+      expect(h).to have_key(:influences)
+      expect(h).to have_key(:balance)
+    end
+  end
+end

data/spec/legion/extensions/neuromodulation/runners/neuromodulation_spec.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/neuromodulation/client'
+
+RSpec.describe Legion::Extensions::Neuromodulation::Runners::Neuromodulation do
+  let(:client) { Legion::Extensions::Neuromodulation::Client.new }
+
+  describe '#boost_modulator' do
+    it 'returns success true' do
+      result = client.boost_modulator(name: :dopamine, amount: 0.1)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns updated level' do
+      result = client.boost_modulator(name: :dopamine, amount: 0.1)
+      expect(result[:level]).to be > 0.5
+    end
+
+    it 'returns state label' do
+      result = client.boost_modulator(name: :dopamine, amount: 0.1)
+      expect(result[:state]).to be_a(Symbol)
+    end
+
+    it 'returns error for unknown modulator' do
+      result = client.boost_modulator(name: :cortisol, amount: 0.1)
+      expect(result[:success]).to be false
+      expect(result[:error]).to include('cortisol')
+    end
+
+    it 'accepts string modulator name' do
+      result = client.boost_modulator(name: 'serotonin', amount: 0.1)
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#suppress_modulator' do
+    it 'returns success true' do
+      result = client.suppress_modulator(name: :serotonin, amount: 0.1)
+      expect(result[:success]).to be true
+    end
+
+    it 'decreases level' do
+      result = client.suppress_modulator(name: :serotonin, amount: 0.1)
+      expect(result[:level]).to be < 0.5
+    end
+
+    it 'returns error for unknown modulator' do
+      result = client.suppress_modulator(name: :adrenaline, amount: 0.1)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#modulator_level' do
+    it 'returns current level' do
+      result = client.modulator_level(name: :norepinephrine)
+      expect(result[:success]).to be true
+      expect(result[:level]).to eq(0.5)
+    end
+
+    it 'returns error for unknown modulator' do
+      result = client.modulator_level(name: :unknown)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#all_modulator_levels' do
+    it 'returns all four modulators' do
+      result = client.all_modulator_levels
+      expect(result[:success]).to be true
+      expect(result[:levels].keys).to contain_exactly(:dopamine, :serotonin, :norepinephrine, :acetylcholine)
+    end
+
+    it 'reflects changes after boost' do
+      client.boost_modulator(name: :dopamine, amount: 0.2)
+      result = client.all_modulator_levels
+      expect(result[:levels][:dopamine]).to be > 0.5
+    end
+  end
+
+  describe '#cognitive_influence' do
+    it 'returns all six cognitive properties' do
+      result = client.cognitive_influence
+      expect(result[:success]).to be true
+      influences = result[:influences]
+      expect(influences).to have_key(:learning_rate_modifier)
+      expect(influences).to have_key(:attention_precision)
+      expect(influences).to have_key(:exploration_bias)
+      expect(influences).to have_key(:patience_factor)
+      expect(influences).to have_key(:memory_encoding_strength)
+      expect(influences).to have_key(:arousal_level)
+    end
+  end
+
+  describe '#is_optimal' do
+    it 'returns true at default level' do
+      result = client.is_optimal(name: :dopamine)
+      expect(result[:success]).to be true
+      expect(result[:optimal]).to be true
+    end
+
+    it 'returns false when out of range' do
+      client.boost_modulator(name: :dopamine, amount: 0.5)
+      result = client.is_optimal(name: :dopamine)
+      expect(result[:optimal]).to be false
+    end
+
+    it 'includes range string' do
+      result = client.is_optimal(name: :serotonin)
+      expect(result[:range]).to be_a(String)
+    end
+
+    it 'returns error for unknown modulator' do
+      result = client.is_optimal(name: :cortisol)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#system_balance' do
+    it 'returns fully_balanced at default' do
+      result = client.system_balance
+      expect(result[:success]).to be true
+      expect(result[:status]).to eq(:fully_balanced)
+      expect(result[:score]).to eq(1.0)
+    end
+
+    it 'returns imbalanced when all are out of range' do
+      client.boost_modulator(name: :dopamine,       amount: 0.5)
+      client.boost_modulator(name: :norepinephrine, amount: 0.5)
+      client.suppress_modulator(name: :serotonin,      amount: 0.4)
+      client.suppress_modulator(name: :acetylcholine,  amount: 0.4)
+      result = client.system_balance
+      expect(result[:score]).to be < 1.0
+    end
+
+    it 'returns state for each modulator' do
+      result = client.system_balance
+      expect(result[:states].keys).to contain_exactly(:dopamine, :serotonin, :norepinephrine, :acetylcholine)
+    end
+  end
+
+  describe '#modulator_history' do
+    it 'returns empty events initially' do
+      result = client.modulator_history(name: :dopamine)
+      expect(result[:success]).to be true
+      expect(result[:events]).to be_empty
+    end
+
+    it 'returns events after changes' do
+      client.boost_modulator(name: :dopamine, amount: 0.1)
+      client.suppress_modulator(name: :dopamine, amount: 0.05)
+      result = client.modulator_history(name: :dopamine)
+      expect(result[:events].size).to eq(2)
+    end
+
+    it 'respects the limit parameter' do
+      10.times { client.boost_modulator(name: :dopamine, amount: 0.001) }
+      result = client.modulator_history(name: :dopamine, limit: 3)
+      expect(result[:events].size).to eq(3)
+    end
+
+    it 'returns error for unknown modulator' do
+      result = client.modulator_history(name: :unknown)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#update_neuromodulation' do
+    it 'returns success' do
+      result = client.update_neuromodulation
+      expect(result[:success]).to be true
+      expect(result[:action]).to eq(:drift_tick)
+    end
+
+    it 'returns current levels after drift' do
+      result = client.update_neuromodulation
+      expect(result[:levels].keys).to contain_exactly(:dopamine, :serotonin, :norepinephrine, :acetylcholine)
+    end
+
+    it 'nudges boosted modulators toward baseline' do
+      client.boost_modulator(name: :dopamine, amount: 0.3)
+      level_after_boost = client.modulator_level(name: :dopamine)[:level]
+      client.update_neuromodulation
+      level_after_tick = client.modulator_level(name: :dopamine)[:level]
+      expect(level_after_tick).to be < level_after_boost
+    end
+  end
+
+  describe '#neuromodulation_stats' do
+    it 'returns full system snapshot' do
+      result = client.neuromodulation_stats
+      expect(result[:success]).to be true
+      expect(result[:system]).to have_key(:modulators)
+      expect(result[:system]).to have_key(:influences)
+      expect(result[:system]).to have_key(:balance)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+module Legion
+  module Logging
+    def self.debug(_msg); end
+    def self.info(_msg); end
+    def self.warn(_msg); end
+    def self.error(_msg); end
+  end
+end
+
+require 'legion/extensions/neuromodulation'
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = '.rspec_status'
+  config.disable_monkey_patching!
+  config.expect_with(:rspec) { |c| c.syntax = :expect }
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: lex-neuromodulation
+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: Neuromodulatory system modeling dopamine, serotonin, norepinephrine,
+  and acetylcholine pathways for brain-modeled agentic AI
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-neuromodulation.gemspec
+- lib/legion/extensions/neuromodulation.rb
+- lib/legion/extensions/neuromodulation/actors/drift.rb
+- lib/legion/extensions/neuromodulation/client.rb
+- lib/legion/extensions/neuromodulation/helpers/constants.rb
+- lib/legion/extensions/neuromodulation/helpers/modulator.rb
+- lib/legion/extensions/neuromodulation/helpers/modulator_system.rb
+- lib/legion/extensions/neuromodulation/runners/neuromodulation.rb
+- lib/legion/extensions/neuromodulation/version.rb
+- spec/legion/extensions/neuromodulation/client_spec.rb
+- spec/legion/extensions/neuromodulation/helpers/constants_spec.rb
+- spec/legion/extensions/neuromodulation/helpers/modulator_spec.rb
+- spec/legion/extensions/neuromodulation/helpers/modulator_system_spec.rb
+- spec/legion/extensions/neuromodulation/runners/neuromodulation_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-neuromodulation
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-neuromodulation
+  source_code_uri: https://github.com/LegionIO/lex-neuromodulation
+  documentation_uri: https://github.com/LegionIO/lex-neuromodulation
+  changelog_uri: https://github.com/LegionIO/lex-neuromodulation
+  bug_tracker_uri: https://github.com/LegionIO/lex-neuromodulation/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 Neuromodulation
+test_files: []