lex-arousal 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cd18506c2aa666a76b1df8c348a61119fd1871041b5d06e9f8e38a8c25104596
+  data.tar.gz: f8b1dd784ef606eac38de02072e7815dba1d4e79151248e230430edcb94f380f
+SHA512:
+  metadata.gz: 944c6c7317069df58999a0e6e4a95d4ec9be4b31cfd5f42ae232c6abb463382acc475223e4480b700b806e4d5651fb65c93999909b7250fc670c73243ebc4f3f
+  data.tar.gz: 960732fa65fdce73e209030ed3b603b21ac5f5a6a3b090e9a17248aab7b544b45ac67bb64788676324f8191548dbfacc27298eb2ff7758e5e0e859692572bd91

data/Gemfile

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

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Iverson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/lex-arousal.gemspec

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

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/arousal/helpers/constants'
+require 'legion/extensions/arousal/helpers/arousal_model'
+require 'legion/extensions/arousal/runners/arousal'
+
+module Legion
+  module Extensions
+    module Arousal
+      class Client
+        include Runners::Arousal
+
+        def initialize(**)
+          @arousal_model = Helpers::ArousalModel.new
+        end
+
+        private
+
+        attr_reader :arousal_model
+      end
+    end
+  end
+end

data/lib/legion/extensions/arousal/helpers/arousal_model.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Arousal
+      module Helpers
+        class ArousalModel
+          include Constants
+
+          attr_reader :arousal, :arousal_history, :performance_last
+
+          def initialize
+            @arousal = DEFAULT_AROUSAL
+            @arousal_history = []
+            @performance_last = 0.0
+          end
+
+          def stimulate(amount:, source: :unknown)
+            boost = amount || BOOST_FACTOR
+            raw = @arousal + boost.to_f.clamp(0.0, 1.0)
+            update_arousal(raw, source: source)
+          end
+
+          def calm(amount:)
+            reduction = amount || CALM_FACTOR
+            raw = @arousal - reduction.to_f.clamp(0.0, 1.0)
+            update_arousal(raw, source: :calm)
+          end
+
+          def decay
+            delta = (@arousal - DEFAULT_AROUSAL) * DECAY_RATE
+            raw = @arousal - delta
+            update_arousal(raw, source: :decay)
+          end
+
+          def performance(task_complexity: :moderate)
+            optimal = optimal_for(task_complexity)
+            diff = @arousal - optimal
+            @performance_last = Math.exp(-PERFORMANCE_SENSITIVITY * (diff**2))
+            @performance_last
+          end
+
+          def arousal_label
+            AROUSAL_LABELS.each do |range, label|
+              return label if range.cover?(@arousal)
+            end
+            :dormant
+          end
+
+          def optimal_for(complexity)
+            TASK_COMPLEXITIES.fetch(complexity, OPTIMAL_AROUSAL_DEFAULT)
+          end
+
+          def to_h
+            {
+              arousal:          @arousal,
+              label:            arousal_label,
+              performance_last: @performance_last,
+              history_size:     @arousal_history.size
+            }
+          end
+
+          private
+
+          def update_arousal(raw, source: :unknown)
+            clamped = raw.clamp(AROUSAL_FLOOR, AROUSAL_CEILING)
+            @arousal = (AROUSAL_ALPHA * clamped) + ((1.0 - AROUSAL_ALPHA) * @arousal)
+            record_history(source)
+            @arousal
+          end
+
+          def record_history(source)
+            @arousal_history << { arousal: @arousal, source: source, at: Time.now.utc }
+            @arousal_history.shift while @arousal_history.size > MAX_AROUSAL_HISTORY
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Arousal
+      module Helpers
+        module Constants
+          DEFAULT_AROUSAL          = 0.3
+          AROUSAL_ALPHA            = 0.15
+          DECAY_RATE               = 0.05
+          OPTIMAL_AROUSAL_SIMPLE   = 0.7
+          OPTIMAL_AROUSAL_COMPLEX  = 0.4
+          OPTIMAL_AROUSAL_DEFAULT  = 0.5
+          PERFORMANCE_SENSITIVITY  = 4.0
+          BOOST_FACTOR             = 0.2
+          CALM_FACTOR              = 0.15
+          AROUSAL_FLOOR            = 0.0
+          AROUSAL_CEILING          = 1.0
+          MAX_AROUSAL_HISTORY      = 200
+
+          TASK_COMPLEXITIES = {
+            trivial:  0.8,
+            simple:   0.7,
+            moderate: 0.5,
+            complex:  0.4,
+            extreme:  0.3
+          }.freeze
+
+          AROUSAL_LABELS = {
+            (0.8..)     => :panic,
+            (0.6...0.8) => :high,
+            (0.4...0.6) => :optimal,
+            (0.2...0.4) => :low,
+            (..0.2)     => :dormant
+          }.freeze
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Arousal
+      module Runners
+        module Arousal
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def stimulate(amount: nil, source: :unknown, **)
+            model = arousal_model
+            amount ||= Helpers::Constants::BOOST_FACTOR
+            new_level = model.stimulate(amount: amount, source: source)
+            Legion::Logging.debug "[arousal] stimulate: source=#{source} amount=#{amount.round(2)} level=#{new_level.round(3)}"
+            {
+              success: true,
+              arousal: new_level,
+              label:   model.arousal_label,
+              source:  source
+            }
+          end
+
+          def calm(amount: nil, **)
+            model = arousal_model
+            amount ||= Helpers::Constants::CALM_FACTOR
+            new_level = model.calm(amount: amount)
+            Legion::Logging.debug "[arousal] calm: amount=#{amount.round(2)} level=#{new_level.round(3)}"
+            {
+              success: true,
+              arousal: new_level,
+              label:   model.arousal_label
+            }
+          end
+
+          def update_arousal(**)
+            model = arousal_model
+            model.decay
+            perf = model.performance
+            Legion::Logging.debug "[arousal] update: level=#{model.arousal.round(3)} label=#{model.arousal_label} perf=#{perf.round(3)}"
+            {
+              success:     true,
+              arousal:     model.arousal,
+              label:       model.arousal_label,
+              performance: perf
+            }
+          end
+
+          def check_performance(task_complexity: :moderate, **)
+            model = arousal_model
+            perf = model.performance(task_complexity: task_complexity)
+            optimal = model.optimal_for(task_complexity)
+            msg = "[arousal] performance: complexity=#{task_complexity} " \
+                  "arousal=#{model.arousal.round(3)} optimal=#{optimal} perf=#{perf.round(3)}"
+            Legion::Logging.debug msg
+            {
+              success:         true,
+              performance:     perf,
+              arousal:         model.arousal,
+              optimal_arousal: optimal,
+              task_complexity: task_complexity
+            }
+          end
+
+          def arousal_status(**)
+            model = arousal_model
+            perf = model.performance
+            Legion::Logging.debug "[arousal] status: level=#{model.arousal.round(3)} label=#{model.arousal_label}"
+            {
+              success:      true,
+              arousal:      model.arousal,
+              label:        model.arousal_label,
+              performance:  perf,
+              history_size: model.arousal_history.size
+            }
+          end
+
+          def arousal_guidance(task_complexity: :moderate, **)
+            model = arousal_model
+            current = model.arousal
+            optimal = model.optimal_for(task_complexity)
+            perf = model.performance(task_complexity: task_complexity)
+            guidance = compute_guidance(current, optimal)
+            Legion::Logging.debug "[arousal] guidance: complexity=#{task_complexity} current=#{current.round(3)} optimal=#{optimal} guidance=#{guidance}"
+            {
+              success:         true,
+              guidance:        guidance,
+              arousal:         current,
+              optimal_arousal: optimal,
+              performance:     perf,
+              task_complexity: task_complexity
+            }
+          end
+
+          private
+
+          def arousal_model
+            @arousal_model ||= Helpers::ArousalModel.new
+          end
+
+          def compute_guidance(current, optimal)
+            gap = current - optimal
+            if gap > 0.15
+              :throttle
+            elsif gap < -0.15
+              :boost
+            else
+              :maintain
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/arousal.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/arousal/version'
+require 'legion/extensions/arousal/helpers/constants'
+require 'legion/extensions/arousal/helpers/arousal_model'
+require 'legion/extensions/arousal/runners/arousal'
+
+module Legion
+  module Extensions
+    module Arousal
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/arousal/client'
+
+RSpec.describe Legion::Extensions::Arousal::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to all runner methods' do
+    expect(client).to respond_to(:stimulate)
+    expect(client).to respond_to(:calm)
+    expect(client).to respond_to(:update_arousal)
+    expect(client).to respond_to(:check_performance)
+    expect(client).to respond_to(:arousal_status)
+    expect(client).to respond_to(:arousal_guidance)
+  end
+
+  it 'runs a full arousal cycle' do
+    client.stimulate(amount: 0.3, source: :external)
+    status = client.arousal_status
+    expect(status[:arousal]).to be > Legion::Extensions::Arousal::Helpers::Constants::DEFAULT_AROUSAL
+    expect(status[:label]).to be_a(Symbol)
+
+    client.calm(amount: 0.1)
+    calmed = client.arousal_status
+    expect(calmed[:arousal]).to be_a(Float)
+
+    guidance = client.arousal_guidance(task_complexity: :moderate)
+    expect(guidance[:guidance]).to be_a(Symbol)
+  end
+
+  it 'persists state across calls' do
+    client.stimulate(amount: 0.5, source: :test)
+    client.stimulate(amount: 0.2, source: :test)
+    status = client.arousal_status
+    expect(status[:history_size]).to be >= 2
+  end
+
+  it 'returns higher performance near the optimal arousal for a given complexity' do
+    perf_moderate = client.check_performance(task_complexity: :moderate)
+    expect(perf_moderate[:performance]).to be_between(0.0, 1.0)
+  end
+end

data/spec/legion/extensions/arousal/helpers/arousal_model_spec.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Arousal::Helpers::ArousalModel do
+  let(:model) { described_class.new }
+
+  describe '#initialize' do
+    it 'starts at the default arousal level' do
+      expect(model.arousal).to be_within(0.001).of(Legion::Extensions::Arousal::Helpers::Constants::DEFAULT_AROUSAL)
+    end
+
+    it 'starts with empty history' do
+      expect(model.arousal_history).to be_empty
+    end
+
+    it 'starts with zero performance' do
+      expect(model.performance_last).to eq(0.0)
+    end
+  end
+
+  describe '#stimulate' do
+    it 'increases arousal' do
+      before = model.arousal
+      model.stimulate(amount: 0.3, source: :test)
+      expect(model.arousal).to be > before
+    end
+
+    it 'records the source in history' do
+      model.stimulate(amount: 0.2, source: :external)
+      expect(model.arousal_history.last[:source]).to eq(:external)
+    end
+
+    it 'clamps arousal at ceiling' do
+      10.times { model.stimulate(amount: 1.0, source: :test) }
+      expect(model.arousal).to be <= 1.0
+    end
+
+    it 'returns the new arousal level' do
+      result = model.stimulate(amount: 0.2, source: :test)
+      expect(result).to eq(model.arousal)
+    end
+  end
+
+  describe '#calm' do
+    before { model.stimulate(amount: 0.5, source: :setup) }
+
+    it 'decreases arousal' do
+      before = model.arousal
+      model.calm(amount: 0.2)
+      expect(model.arousal).to be < before
+    end
+
+    it 'clamps arousal at floor' do
+      10.times { model.calm(amount: 1.0) }
+      expect(model.arousal).to be >= 0.0
+    end
+
+    it 'returns the new arousal level' do
+      result = model.calm(amount: 0.1)
+      expect(result).to eq(model.arousal)
+    end
+  end
+
+  describe '#decay' do
+    it 'moves arousal toward the default resting level from above' do
+      model.stimulate(amount: 0.5, source: :setup)
+      raised = model.arousal
+      model.decay
+      # After stimulating above default, decay should lower it (move toward default)
+      expect(model.arousal).to be < raised
+    end
+
+    it 'records a decay entry in history' do
+      model.decay
+      expect(model.arousal_history.last[:source]).to eq(:decay)
+    end
+  end
+
+  describe '#performance' do
+    it 'returns a value between 0 and 1' do
+      perf = model.performance
+      expect(perf).to be >= 0.0
+      expect(perf).to be <= 1.0
+    end
+
+    it 'returns highest performance near the optimal arousal' do
+      model.stimulate(amount: 0.2, source: :test)
+      perf_near_optimal = model.performance(task_complexity: :moderate)
+
+      model2 = described_class.new
+      10.times { model2.stimulate(amount: 0.8, source: :test) }
+      perf_far_from_optimal = model2.performance(task_complexity: :moderate)
+
+      expect(perf_near_optimal).to be >= perf_far_from_optimal
+    end
+
+    it 'uses complexity-specific optimal for simple tasks' do
+      perf_simple = model.performance(task_complexity: :simple)
+      expect(perf_simple).to be_a(Float)
+    end
+
+    it 'updates performance_last' do
+      model.performance(task_complexity: :moderate)
+      expect(model.performance_last).to be > 0.0
+    end
+  end
+
+  describe '#arousal_label' do
+    it 'returns :dormant for near-zero arousal' do
+      10.times { model.calm(amount: 1.0) }
+      expect(model.arousal_label).to eq(:dormant)
+    end
+
+    it 'returns :panic for high arousal' do
+      10.times { model.stimulate(amount: 1.0, source: :test) }
+      expect(model.arousal_label).to eq(:panic)
+    end
+
+    it 'returns a symbol for any arousal level' do
+      expect(model.arousal_label).to be_a(Symbol)
+    end
+  end
+
+  describe '#optimal_for' do
+    it 'returns the correct optimal for each complexity' do
+      constants = Legion::Extensions::Arousal::Helpers::Constants
+      expect(model.optimal_for(:trivial)).to eq(constants::TASK_COMPLEXITIES[:trivial])
+      expect(model.optimal_for(:moderate)).to eq(constants::TASK_COMPLEXITIES[:moderate])
+      expect(model.optimal_for(:extreme)).to eq(constants::TASK_COMPLEXITIES[:extreme])
+    end
+
+    it 'returns the default when complexity is unknown' do
+      expect(model.optimal_for(:unknown)).to eq(Legion::Extensions::Arousal::Helpers::Constants::OPTIMAL_AROUSAL_DEFAULT)
+    end
+  end
+
+  describe '#arousal_history cap' do
+    it 'does not exceed MAX_AROUSAL_HISTORY entries' do
+      max = Legion::Extensions::Arousal::Helpers::Constants::MAX_AROUSAL_HISTORY
+      (max + 10).times { model.stimulate(amount: 0.01, source: :test) }
+      expect(model.arousal_history.size).to eq(max)
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes arousal, label, performance_last, and history_size' do
+      h = model.to_h
+      expect(h).to have_key(:arousal)
+      expect(h).to have_key(:label)
+      expect(h).to have_key(:performance_last)
+      expect(h).to have_key(:history_size)
+    end
+
+    it 'reflects the current state' do
+      model.stimulate(amount: 0.2, source: :test)
+      h = model.to_h
+      expect(h[:arousal]).to eq(model.arousal)
+      expect(h[:history_size]).to eq(model.arousal_history.size)
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Arousal::Helpers::Constants do
+  describe 'DEFAULT_AROUSAL' do
+    it 'is 0.3' do
+      expect(described_class::DEFAULT_AROUSAL).to eq(0.3)
+    end
+  end
+
+  describe 'AROUSAL_FLOOR and AROUSAL_CEILING' do
+    it 'floor is 0.0' do
+      expect(described_class::AROUSAL_FLOOR).to eq(0.0)
+    end
+
+    it 'ceiling is 1.0' do
+      expect(described_class::AROUSAL_CEILING).to eq(1.0)
+    end
+  end
+
+  describe 'TASK_COMPLEXITIES' do
+    it 'includes all expected complexity levels' do
+      expect(described_class::TASK_COMPLEXITIES.keys).to contain_exactly(:trivial, :simple, :moderate, :complex, :extreme)
+    end
+
+    it 'trivial has the highest optimal arousal' do
+      expect(described_class::TASK_COMPLEXITIES[:trivial]).to be > described_class::TASK_COMPLEXITIES[:extreme]
+    end
+
+    it 'extreme has the lowest optimal arousal' do
+      expect(described_class::TASK_COMPLEXITIES[:extreme]).to eq(0.3)
+    end
+  end
+
+  describe 'AROUSAL_LABELS' do
+    it 'covers the full 0.0..1.0 range' do
+      test_values = [0.0, 0.1, 0.3, 0.5, 0.7, 0.9, 1.0]
+      test_values.each do |v|
+        matched = described_class::AROUSAL_LABELS.any? { |range, _| range.cover?(v) }
+        expect(matched).to be(true), "Expected #{v} to match a label range"
+      end
+    end
+
+    it 'maps values >= 0.8 to :panic' do
+      range, label = described_class::AROUSAL_LABELS.find { |r, _| r.cover?(0.9) }
+      expect(label).to eq(:panic)
+      expect(range).to cover(0.9)
+    end
+
+    it 'maps values in 0.4..0.6 to :optimal' do
+      range, label = described_class::AROUSAL_LABELS.find { |r, _| r.cover?(0.5) }
+      expect(label).to eq(:optimal)
+      expect(range).to cover(0.5)
+    end
+  end
+
+  describe 'OPTIMAL_AROUSAL_SIMPLE and OPTIMAL_AROUSAL_COMPLEX' do
+    it 'simple optimal is higher than complex optimal' do
+      expect(described_class::OPTIMAL_AROUSAL_SIMPLE).to be > described_class::OPTIMAL_AROUSAL_COMPLEX
+    end
+  end
+end

data/spec/legion/extensions/arousal/runners/arousal_spec.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/arousal/client'
+
+RSpec.describe Legion::Extensions::Arousal::Runners::Arousal do
+  let(:client) { Legion::Extensions::Arousal::Client.new }
+
+  describe '#stimulate' do
+    it 'returns success: true' do
+      result = client.stimulate
+      expect(result[:success]).to be(true)
+    end
+
+    it 'returns the new arousal level' do
+      result = client.stimulate(amount: 0.2, source: :test)
+      expect(result[:arousal]).to be_a(Float)
+    end
+
+    it 'returns a label' do
+      result = client.stimulate
+      expect(result[:label]).to be_a(Symbol)
+    end
+
+    it 'returns the source' do
+      result = client.stimulate(source: :external_event)
+      expect(result[:source]).to eq(:external_event)
+    end
+
+    it 'increases arousal above default' do
+      result = client.stimulate(amount: 0.4)
+      expect(result[:arousal]).to be > Legion::Extensions::Arousal::Helpers::Constants::DEFAULT_AROUSAL
+    end
+  end
+
+  describe '#calm' do
+    before { client.stimulate(amount: 0.5) }
+
+    it 'returns success: true' do
+      expect(client.calm[:success]).to be(true)
+    end
+
+    it 'returns the new arousal level' do
+      result = client.calm(amount: 0.1)
+      expect(result[:arousal]).to be_a(Float)
+    end
+
+    it 'returns a label' do
+      expect(client.calm[:label]).to be_a(Symbol)
+    end
+  end
+
+  describe '#update_arousal' do
+    it 'returns success: true' do
+      expect(client.update_arousal[:success]).to be(true)
+    end
+
+    it 'returns arousal, label, and performance' do
+      result = client.update_arousal
+      expect(result).to have_key(:arousal)
+      expect(result).to have_key(:label)
+      expect(result).to have_key(:performance)
+    end
+
+    it 'returns performance between 0 and 1' do
+      result = client.update_arousal
+      expect(result[:performance]).to be_between(0.0, 1.0)
+    end
+  end
+
+  describe '#check_performance' do
+    it 'returns success: true' do
+      expect(client.check_performance[:success]).to be(true)
+    end
+
+    it 'returns performance, arousal, optimal_arousal, and task_complexity' do
+      result = client.check_performance(task_complexity: :simple)
+      expect(result).to have_key(:performance)
+      expect(result).to have_key(:arousal)
+      expect(result).to have_key(:optimal_arousal)
+      expect(result[:task_complexity]).to eq(:simple)
+    end
+
+    it 'reflects the optimal arousal for the given complexity' do
+      result_simple  = client.check_performance(task_complexity: :simple)
+      result_extreme = client.check_performance(task_complexity: :extreme)
+      expect(result_simple[:optimal_arousal]).to be > result_extreme[:optimal_arousal]
+    end
+  end
+
+  describe '#arousal_status' do
+    it 'returns success: true' do
+      expect(client.arousal_status[:success]).to be(true)
+    end
+
+    it 'returns arousal, label, performance, and history_size' do
+      result = client.arousal_status
+      expect(result).to have_key(:arousal)
+      expect(result).to have_key(:label)
+      expect(result).to have_key(:performance)
+      expect(result).to have_key(:history_size)
+    end
+  end
+
+  describe '#arousal_guidance' do
+    it 'returns success: true' do
+      expect(client.arousal_guidance[:success]).to be(true)
+    end
+
+    it 'returns guidance as a symbol' do
+      result = client.arousal_guidance
+      expect(result[:guidance]).to be_a(Symbol)
+    end
+
+    it 'returns :throttle when arousal is well above optimal' do
+      5.times { client.stimulate(amount: 1.0) }
+      result = client.arousal_guidance(task_complexity: :extreme)
+      expect(result[:guidance]).to eq(:throttle)
+    end
+
+    it 'returns :boost when arousal is well below optimal' do
+      10.times { client.calm(amount: 1.0) }
+      result = client.arousal_guidance(task_complexity: :trivial)
+      expect(result[:guidance]).to eq(:boost)
+    end
+
+    it 'returns :maintain when near optimal' do
+      result = client.arousal_guidance(task_complexity: :moderate)
+      expect(%i[maintain throttle boost]).to include(result[:guidance])
+    end
+
+    it 'includes optimal_arousal and task_complexity' do
+      result = client.arousal_guidance(task_complexity: :complex)
+      expect(result[:optimal_arousal]).to eq(0.4)
+      expect(result[:task_complexity]).to eq(:complex)
+    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/arousal'
+
+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,74 @@
+--- !ruby/object:Gem::Specification
+name: lex-arousal
+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: Yerkes-Dodson arousal regulation for brain-modeled agentic AI
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE
+- lex-arousal.gemspec
+- lib/legion/extensions/arousal.rb
+- lib/legion/extensions/arousal/client.rb
+- lib/legion/extensions/arousal/helpers/arousal_model.rb
+- lib/legion/extensions/arousal/helpers/constants.rb
+- lib/legion/extensions/arousal/runners/arousal.rb
+- lib/legion/extensions/arousal/version.rb
+- spec/legion/extensions/arousal/client_spec.rb
+- spec/legion/extensions/arousal/helpers/arousal_model_spec.rb
+- spec/legion/extensions/arousal/helpers/constants_spec.rb
+- spec/legion/extensions/arousal/runners/arousal_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-arousal
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-arousal
+  source_code_uri: https://github.com/LegionIO/lex-arousal
+  documentation_uri: https://github.com/LegionIO/lex-arousal
+  changelog_uri: https://github.com/LegionIO/lex-arousal
+  bug_tracker_uri: https://github.com/LegionIO/lex-arousal/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 Arousal
+test_files: []