lex-interoception 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dace4cb240f23845d21abe89e16f97bb73d4bc993002ccfe4ceb94e01da4d72b
+  data.tar.gz: 3bcf0cbef4062bcf3fcfb58d93e5aa2c55b24c22ec545cd9a10a48b438d52f7e
+SHA512:
+  metadata.gz: d352233f77c158c7e60869010f7f46ede5099c21eb839871ffc469df701c990e9d253d8dcf9c661155adeb8700cbb2eb0766f639e20ccfa3b77a19a068f36688
+  data.tar.gz: edee25c05cfb81956ec5052fa7e85177b8eab77ab70bf80d2a55512b7d4c0a2472b5d87d0a680f8a522d6f2a1fd3602153757b9b926457145d7d3baea7566f40

data/Gemfile

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

data/lex-interoception.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/interoception/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-interoception'
+  spec.version       = Legion::Extensions::Interoception::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Interoception'
+  spec.description   = 'Somatic marker hypothesis for brain-modeled agentic AI — internal body-state ' \
+                       'monitoring, vital signal tracking, and somatic markers that bias decisions ' \
+                       'based on past outcomes associated with similar internal states.'
+  spec.homepage      = 'https://github.com/LegionIO/lex-interoception'
+  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-interoception'
+  spec.metadata['documentation_uri']     = 'https://github.com/LegionIO/lex-interoception'
+  spec.metadata['changelog_uri']         = 'https://github.com/LegionIO/lex-interoception'
+  spec.metadata['bug_tracker_uri']       = 'https://github.com/LegionIO/lex-interoception/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-interoception.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

data/lib/legion/extensions/interoception/actors/decay.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module Interoception
+      module Actor
+        class Decay < Legion::Extensions::Actors::Every
+          def runner_class
+            Legion::Extensions::Interoception::Runners::Interoception
+          end
+
+          def runner_function
+            'update_interoception'
+          end
+
+          def time
+            60
+          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/interoception/client.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/interoception/helpers/constants'
+require 'legion/extensions/interoception/helpers/somatic_marker'
+require 'legion/extensions/interoception/helpers/body_budget'
+require 'legion/extensions/interoception/runners/interoception'
+
+module Legion
+  module Extensions
+    module Interoception
+      class Client
+        include Runners::Interoception
+
+        def initialize(body_budget: nil, **)
+          @body_budget = body_budget || Helpers::BodyBudget.new
+        end
+
+        private
+
+        attr_reader :body_budget
+      end
+    end
+  end
+end

data/lib/legion/extensions/interoception/helpers/body_budget.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Interoception
+      module Helpers
+        class BodyBudget
+          include Constants
+
+          attr_reader :vitals, :baselines, :markers, :vital_history
+
+          def initialize
+            @vitals        = {}
+            @baselines     = {}
+            @markers       = []
+            @vital_history = {}
+          end
+
+          # --- Vital Signal Tracking ---
+
+          def report_vital(channel:, value:)
+            channel = channel.to_sym
+            normalized = value.clamp(0.0, 1.0)
+            @baselines[channel] ||= DEFAULT_BASELINE
+            @vitals[channel] = if @vitals.key?(channel)
+                                 ema(@vitals[channel], normalized, VITAL_ALPHA)
+                               else
+                                 normalized
+                               end
+            record_vital_history(channel, @vitals[channel])
+            @baselines[channel] = ema(@baselines[channel], @vitals[channel], VITAL_ALPHA * 0.5)
+            @vitals[channel]
+          end
+
+          def vital_for(channel)
+            @vitals.fetch(channel.to_sym, DEFAULT_BASELINE)
+          end
+
+          def deviation_for(channel)
+            channel = channel.to_sym
+            current = @vitals.fetch(channel, DEFAULT_BASELINE)
+            baseline = @baselines.fetch(channel, DEFAULT_BASELINE)
+            current - baseline
+          end
+
+          def vital_label(channel)
+            health = vital_health(channel)
+            VITAL_LABELS.each { |range, lbl| return lbl if range.cover?(health) }
+            :nominal
+          end
+
+          def vital_health(channel)
+            val = vital_for(channel)
+            inverted_channels = %i[cpu_load memory_pressure queue_depth error_rate disk_usage gc_pressure]
+            inverted_channels.include?(channel.to_sym) ? 1.0 - val : val
+          end
+
+          def deviating_channels
+            @vitals.select { |ch, _| deviation_for(ch).abs >= DEVIATION_THRESHOLD }
+                   .map { |ch, _| { channel: ch, deviation: deviation_for(ch).round(4), label: vital_label(ch) } }
+          end
+
+          # --- Somatic Markers ---
+
+          def create_marker(action:, domain:, valence:, strength: 1.0)
+            marker = SomaticMarker.new(action: action, domain: domain, valence: valence, strength: strength)
+            @markers << marker
+            prune_markers if @markers.size > MAX_MARKERS
+            marker
+          end
+
+          def markers_for(action:, domain: nil)
+            results = @markers.select { |m| m.action == action }
+            results = results.select { |m| m.domain == domain } if domain
+            results
+          end
+
+          def bias_for_action(action:, domain: nil)
+            relevant = markers_for(action: action, domain: domain)
+            return 0.0 if relevant.empty?
+
+            relevant.sum { |m| m.bias_for(action) } / relevant.size
+          end
+
+          def reinforce_markers(action:, domain: nil, amount: 0.1)
+            markers_for(action: action, domain: domain).each { |m| m.reinforce(amount: amount) }
+          end
+
+          def decay_markers
+            @markers.each(&:decay)
+            @markers.reject!(&:faded?)
+          end
+
+          # --- Body Budget Overview ---
+
+          def overall_health
+            return DEFAULT_BASELINE if @vitals.empty?
+
+            healths = @vitals.keys.map { |ch| vital_health(ch) }
+            healths.sum / healths.size
+          end
+
+          def body_budget_label
+            health = overall_health
+            BODY_BUDGET_LABELS.each { |range, lbl| return lbl if range.cover?(health) }
+            :comfortable
+          end
+
+          def channel_count
+            @vitals.size
+          end
+
+          def marker_count
+            @markers.size
+          end
+
+          def to_h
+            {
+              overall_health:    overall_health.round(4),
+              body_budget_label: body_budget_label,
+              channels:          channel_count,
+              markers:           marker_count,
+              vitals:            @vitals.transform_values { |v| v.round(4) },
+              deviations:        deviating_channels
+            }
+          end
+
+          private
+
+          def ema(old_val, new_val, alpha)
+            old_val + (alpha * (new_val - old_val))
+          end
+
+          def record_vital_history(channel, value)
+            @vital_history[channel] ||= []
+            @vital_history[channel] << { value: value, at: Time.now.utc }
+            @vital_history[channel].shift while @vital_history[channel].size > MAX_VITAL_HISTORY
+          end
+
+          def prune_markers
+            @markers.sort_by!(&:strength)
+            @markers.shift while @markers.size > MAX_MARKERS
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Interoception
+      module Helpers
+        module Constants
+          # Vital signal channels the agent monitors
+          VITAL_CHANNELS = %i[
+            cpu_load memory_pressure queue_depth
+            response_latency error_rate connection_health
+            disk_usage thread_count gc_pressure
+          ].freeze
+
+          # Somatic marker valence thresholds
+          MARKER_POSITIVE_THRESHOLD = 0.3
+          MARKER_NEGATIVE_THRESHOLD = -0.3
+
+          # How strongly markers bias decisions (0..1)
+          MARKER_INFLUENCE = 0.4
+
+          # EMA alpha for vital signal smoothing
+          VITAL_ALPHA = 0.15
+
+          # Default baseline for vitals (normalized 0..1)
+          DEFAULT_BASELINE = 0.5
+
+          # Deviation from baseline that triggers a somatic marker
+          DEVIATION_THRESHOLD = 0.2
+
+          # Maximum stored somatic markers
+          MAX_MARKERS = 200
+
+          # Maximum stored vital snapshots per channel
+          MAX_VITAL_HISTORY = 100
+
+          # Marker decay per tick
+          MARKER_DECAY = 0.02
+
+          # Marker floor (below this, marker is pruned)
+          MARKER_FLOOR = 0.05
+
+          # Body budget labels based on overall vital health
+          BODY_BUDGET_LABELS = {
+            (0.8..)     => :thriving,
+            (0.6...0.8) => :comfortable,
+            (0.4...0.6) => :strained,
+            (0.2...0.4) => :distressed,
+            (..0.2)     => :critical
+          }.freeze
+
+          # Vital health labels
+          VITAL_LABELS = {
+            (0.8..)     => :healthy,
+            (0.6...0.8) => :nominal,
+            (0.4...0.6) => :elevated,
+            (0.2...0.4) => :warning,
+            (..0.2)     => :critical
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/interoception/helpers/somatic_marker.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Interoception
+      module Helpers
+        class SomaticMarker
+          attr_reader :id, :action, :domain, :valence, :created_at
+          attr_accessor :strength
+
+          def initialize(action:, domain:, valence:, strength: 1.0)
+            @id         = SecureRandom.uuid
+            @action     = action
+            @domain     = domain
+            @valence    = valence.clamp(-1.0, 1.0)
+            @strength   = strength.clamp(0.0, 1.0)
+            @created_at = Time.now.utc
+          end
+
+          def bias_for(candidate_action)
+            return 0.0 unless candidate_action == @action
+
+            @valence * @strength * Constants::MARKER_INFLUENCE
+          end
+
+          def reinforce(amount: 0.1)
+            @strength = [@strength + amount, 1.0].min
+          end
+
+          def decay
+            @strength = [@strength - Constants::MARKER_DECAY, Constants::MARKER_FLOOR].max
+          end
+
+          def faded?
+            @strength <= Constants::MARKER_FLOOR
+          end
+
+          def positive?
+            @valence >= Constants::MARKER_POSITIVE_THRESHOLD
+          end
+
+          def negative?
+            @valence <= Constants::MARKER_NEGATIVE_THRESHOLD
+          end
+
+          def label
+            if positive?
+              :approach
+            elsif negative?
+              :avoid
+            else
+              :neutral
+            end
+          end
+
+          def to_h
+            {
+              id:         @id,
+              action:     @action,
+              domain:     @domain,
+              valence:    @valence,
+              strength:   @strength,
+              label:      label,
+              created_at: @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Interoception
+      module Runners
+        module Interoception
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def report_vital(channel:, value:, **)
+            smoothed = body_budget.report_vital(channel: channel, value: value.to_f)
+            deviation = body_budget.deviation_for(channel)
+            Legion::Logging.debug "[interoception] vital: channel=#{channel} raw=#{value} " \
+                                  "smoothed=#{smoothed.round(3)} deviation=#{deviation.round(3)}"
+            {
+              success:   true,
+              channel:   channel,
+              smoothed:  smoothed.round(4),
+              deviation: deviation.round(4),
+              label:     body_budget.vital_label(channel)
+            }
+          end
+
+          def create_somatic_marker(action:, domain:, valence:, strength: 1.0, **)
+            marker = body_budget.create_marker(action: action, domain: domain, valence: valence.to_f, strength: strength.to_f)
+            Legion::Logging.debug "[interoception] marker: action=#{action} domain=#{domain} " \
+                                  "valence=#{marker.valence.round(2)} label=#{marker.label}"
+            { success: true, marker: marker.to_h }
+          end
+
+          def query_bias(action:, domain: nil, **)
+            bias = body_budget.bias_for_action(action: action, domain: domain)
+            label = if bias > Helpers::Constants::MARKER_POSITIVE_THRESHOLD * Helpers::Constants::MARKER_INFLUENCE
+                      :approach
+                    elsif bias < Helpers::Constants::MARKER_NEGATIVE_THRESHOLD * Helpers::Constants::MARKER_INFLUENCE
+                      :avoid
+                    else
+                      :neutral
+                    end
+            Legion::Logging.debug "[interoception] bias: action=#{action} domain=#{domain} bias=#{bias.round(3)} label=#{label}"
+            { success: true, action: action, domain: domain, bias: bias.round(4), label: label }
+          end
+
+          def reinforce_somatic(action:, domain: nil, amount: 0.1, **)
+            body_budget.reinforce_markers(action: action, domain: domain, amount: amount.to_f)
+            Legion::Logging.debug "[interoception] reinforce: action=#{action} domain=#{domain} amount=#{amount}"
+            { success: true, action: action, domain: domain }
+          end
+
+          def deviating_vitals(**)
+            deviations = body_budget.deviating_channels
+            Legion::Logging.debug "[interoception] deviating: count=#{deviations.size}"
+            { success: true, deviations: deviations, count: deviations.size }
+          end
+
+          def body_status(**)
+            health = body_budget.overall_health
+            label = body_budget.body_budget_label
+            Legion::Logging.debug "[interoception] status: health=#{health.round(3)} label=#{label}"
+            {
+              success:  true,
+              health:   health.round(4),
+              label:    label,
+              channels: body_budget.channel_count,
+              markers:  body_budget.marker_count
+            }
+          end
+
+          def update_interoception(**)
+            body_budget.decay_markers
+            health = body_budget.overall_health
+            Legion::Logging.debug "[interoception] tick: health=#{health.round(3)} " \
+                                  "channels=#{body_budget.channel_count} markers=#{body_budget.marker_count}"
+            {
+              success:  true,
+              health:   health.round(4),
+              label:    body_budget.body_budget_label,
+              channels: body_budget.channel_count,
+              markers:  body_budget.marker_count
+            }
+          end
+
+          def interoception_stats(**)
+            { success: true, stats: body_budget.to_h }
+          end
+
+          private
+
+          def body_budget
+            @body_budget ||= Helpers::BodyBudget.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/interoception.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'legion/extensions/interoception/version'
+require 'legion/extensions/interoception/helpers/constants'
+require 'legion/extensions/interoception/helpers/somatic_marker'
+require 'legion/extensions/interoception/helpers/body_budget'
+require 'legion/extensions/interoception/runners/interoception'
+require 'legion/extensions/interoception/client'
+
+module Legion
+  module Extensions
+    module Interoception
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Interoception::Client do
+  subject(:client) { described_class.new }
+
+  it 'includes Runners::Interoception' do
+    expect(described_class.ancestors).to include(Legion::Extensions::Interoception::Runners::Interoception)
+  end
+
+  it 'responds to all runner methods' do
+    expect(client).to respond_to(:report_vital)
+    expect(client).to respond_to(:create_somatic_marker)
+    expect(client).to respond_to(:query_bias)
+    expect(client).to respond_to(:reinforce_somatic)
+    expect(client).to respond_to(:deviating_vitals)
+    expect(client).to respond_to(:body_status)
+    expect(client).to respond_to(:update_interoception)
+    expect(client).to respond_to(:interoception_stats)
+  end
+
+  it 'supports full somatic marker lifecycle' do
+    # Report some vitals
+    client.report_vital(channel: :cpu_load, value: 0.3)
+    client.report_vital(channel: :connection_health, value: 0.9)
+
+    # Create markers based on outcomes
+    client.create_somatic_marker(action: :deploy, domain: :prod, valence: 0.8)
+    client.create_somatic_marker(action: :risky_change, domain: :prod, valence: -0.6)
+
+    # Query bias should reflect markers
+    approach = client.query_bias(action: :deploy)
+    expect(approach[:bias]).to be > 0
+
+    avoid = client.query_bias(action: :risky_change)
+    expect(avoid[:bias]).to be < 0
+
+    # Reinforce good outcome
+    client.reinforce_somatic(action: :deploy)
+
+    # Tick decay
+    client.update_interoception
+
+    # Check overall status
+    status = client.body_status
+    expect(status[:success]).to be true
+    expect(status[:health]).to be > 0
+
+    stats = client.interoception_stats
+    expect(stats[:stats][:channels]).to eq(2)
+    expect(stats[:stats][:markers]).to be >= 1
+  end
+end

data/spec/legion/extensions/interoception/helpers/body_budget_spec.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Interoception::Helpers::BodyBudget do
+  subject(:budget) { described_class.new }
+
+  describe '#report_vital' do
+    it 'stores and smooths a vital signal' do
+      result = budget.report_vital(channel: :cpu_load, value: 0.7)
+      expect(result).to be_a(Float)
+      expect(result).to be_between(0.0, 1.0)
+    end
+
+    it 'applies EMA smoothing on repeated reports' do
+      budget.report_vital(channel: :cpu_load, value: 0.2)
+      budget.report_vital(channel: :cpu_load, value: 0.8)
+      val = budget.vital_for(:cpu_load)
+      expect(val).to be_between(0.2, 0.8)
+    end
+
+    it 'clamps values to 0..1' do
+      budget.report_vital(channel: :cpu_load, value: 5.0)
+      expect(budget.vital_for(:cpu_load)).to be <= 1.0
+    end
+
+    it 'updates baseline over time' do
+      10.times { budget.report_vital(channel: :cpu_load, value: 0.9) }
+      expect(budget.baselines[:cpu_load]).to be > 0.5
+    end
+  end
+
+  describe '#deviation_for' do
+    it 'returns 0 for new channels' do
+      expect(budget.deviation_for(:cpu_load)).to eq(0.0)
+    end
+
+    it 'detects deviation from baseline' do
+      5.times { budget.report_vital(channel: :cpu_load, value: 0.3) }
+      budget.report_vital(channel: :cpu_load, value: 0.9)
+      expect(budget.deviation_for(:cpu_load).abs).to be > 0
+    end
+  end
+
+  describe '#vital_label' do
+    it 'returns :healthy for healthy vitals' do
+      budget.report_vital(channel: :connection_health, value: 0.9)
+      expect(budget.vital_label(:connection_health)).to eq(:healthy)
+    end
+
+    it 'returns :critical for bad inverted vitals' do
+      budget.report_vital(channel: :cpu_load, value: 0.95)
+      expect(budget.vital_label(:cpu_load)).to eq(:critical)
+    end
+  end
+
+  describe '#vital_health' do
+    it 'inverts cpu_load (high load = low health)' do
+      budget.report_vital(channel: :cpu_load, value: 0.9)
+      expect(budget.vital_health(:cpu_load)).to be < 0.2
+    end
+
+    it 'keeps connection_health direct (high = good)' do
+      budget.report_vital(channel: :connection_health, value: 0.9)
+      expect(budget.vital_health(:connection_health)).to be > 0.8
+    end
+  end
+
+  describe '#deviating_channels' do
+    it 'returns empty when no deviations' do
+      expect(budget.deviating_channels).to be_empty
+    end
+
+    it 'detects channels with significant deviation' do
+      5.times { budget.report_vital(channel: :cpu_load, value: 0.2) }
+      # Force a big jump
+      budget.report_vital(channel: :cpu_load, value: 0.95)
+      budget.report_vital(channel: :cpu_load, value: 0.95)
+      budget.report_vital(channel: :cpu_load, value: 0.95)
+      deviations = budget.deviating_channels
+      expect(deviations.first[:channel]).to eq(:cpu_load) if deviations.any?
+    end
+  end
+
+  describe 'somatic markers' do
+    describe '#create_marker' do
+      it 'creates and stores a marker' do
+        marker = budget.create_marker(action: :deploy, domain: :prod, valence: 0.7)
+        expect(marker).to be_a(Legion::Extensions::Interoception::Helpers::SomaticMarker)
+        expect(budget.marker_count).to eq(1)
+      end
+    end
+
+    describe '#markers_for' do
+      it 'finds markers by action' do
+        budget.create_marker(action: :deploy, domain: :prod, valence: 0.5)
+        budget.create_marker(action: :deploy, domain: :staging, valence: 0.3)
+        budget.create_marker(action: :rollback, domain: :prod, valence: -0.5)
+        expect(budget.markers_for(action: :deploy).size).to eq(2)
+      end
+
+      it 'filters by domain' do
+        budget.create_marker(action: :deploy, domain: :prod, valence: 0.5)
+        budget.create_marker(action: :deploy, domain: :staging, valence: 0.3)
+        expect(budget.markers_for(action: :deploy, domain: :prod).size).to eq(1)
+      end
+    end
+
+    describe '#bias_for_action' do
+      it 'returns 0.0 with no markers' do
+        expect(budget.bias_for_action(action: :deploy)).to eq(0.0)
+      end
+
+      it 'returns positive bias for approach markers' do
+        budget.create_marker(action: :deploy, domain: :prod, valence: 0.8)
+        expect(budget.bias_for_action(action: :deploy)).to be > 0
+      end
+
+      it 'returns negative bias for avoid markers' do
+        budget.create_marker(action: :deploy, domain: :prod, valence: -0.8)
+        expect(budget.bias_for_action(action: :deploy)).to be < 0
+      end
+    end
+
+    describe '#reinforce_markers' do
+      it 'increases strength of matching markers' do
+        budget.create_marker(action: :deploy, domain: :prod, valence: 0.5, strength: 0.4)
+        budget.reinforce_markers(action: :deploy, amount: 0.2)
+        marker = budget.markers_for(action: :deploy).first
+        expect(marker.strength).to be_within(0.001).of(0.6)
+      end
+    end
+
+    describe '#decay_markers' do
+      it 'decays all markers' do
+        budget.create_marker(action: :deploy, domain: :prod, valence: 0.5)
+        before = budget.markers_for(action: :deploy).first.strength
+        budget.decay_markers
+        after = budget.markers_for(action: :deploy).first&.strength
+        expect(after).to be < before if after
+      end
+
+      it 'prunes faded markers' do
+        floor = Legion::Extensions::Interoception::Helpers::Constants::MARKER_FLOOR
+        budget.create_marker(action: :deploy, domain: :prod, valence: 0.5, strength: floor + 0.01)
+        budget.decay_markers
+        expect(budget.marker_count).to eq(0)
+      end
+    end
+  end
+
+  describe '#overall_health' do
+    it 'returns DEFAULT_BASELINE with no vitals' do
+      expect(budget.overall_health).to eq(Legion::Extensions::Interoception::Helpers::Constants::DEFAULT_BASELINE)
+    end
+
+    it 'computes average health across channels' do
+      budget.report_vital(channel: :connection_health, value: 0.9)
+      budget.report_vital(channel: :cpu_load, value: 0.1) # low load = healthy
+      expect(budget.overall_health).to be > 0.7
+    end
+  end
+
+  describe '#body_budget_label' do
+    it 'returns :comfortable for healthy vitals' do
+      budget.report_vital(channel: :connection_health, value: 0.7)
+      label = budget.body_budget_label
+      expect(%i[thriving comfortable]).to include(label)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns comprehensive stats' do
+      budget.report_vital(channel: :cpu_load, value: 0.3)
+      budget.create_marker(action: :deploy, domain: :prod, valence: 0.5)
+      h = budget.to_h
+      expect(h).to include(:overall_health, :body_budget_label, :channels, :markers, :vitals, :deviations)
+    end
+  end
+end

data/spec/legion/extensions/interoception/helpers/somatic_marker_spec.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Interoception::Helpers::SomaticMarker do
+  subject(:marker) { described_class.new(action: :deploy, domain: :production, valence: 0.6) }
+
+  describe '#initialize' do
+    it 'assigns fields' do
+      expect(marker.action).to eq(:deploy)
+      expect(marker.domain).to eq(:production)
+      expect(marker.valence).to eq(0.6)
+      expect(marker.strength).to eq(1.0)
+    end
+
+    it 'assigns uuid and timestamp' do
+      expect(marker.id).to match(/\A[0-9a-f-]{36}\z/)
+      expect(marker.created_at).to be_a(Time)
+    end
+
+    it 'clamps valence to -1.0..1.0' do
+      high = described_class.new(action: :a, domain: :d, valence: 2.0)
+      low  = described_class.new(action: :a, domain: :d, valence: -2.0)
+      expect(high.valence).to eq(1.0)
+      expect(low.valence).to eq(-1.0)
+    end
+
+    it 'clamps strength to 0.0..1.0' do
+      high = described_class.new(action: :a, domain: :d, valence: 0.5, strength: 5.0)
+      expect(high.strength).to eq(1.0)
+    end
+  end
+
+  describe '#bias_for' do
+    it 'returns positive bias for matching action with positive valence' do
+      bias = marker.bias_for(:deploy)
+      expect(bias).to be > 0
+    end
+
+    it 'returns 0 for non-matching action' do
+      expect(marker.bias_for(:rollback)).to eq(0.0)
+    end
+
+    it 'applies MARKER_INFLUENCE factor' do
+      influence = Legion::Extensions::Interoception::Helpers::Constants::MARKER_INFLUENCE
+      expected = marker.valence * marker.strength * influence
+      expect(marker.bias_for(:deploy)).to be_within(0.001).of(expected)
+    end
+  end
+
+  describe '#reinforce' do
+    it 'increases strength' do
+      marker.strength = 0.5
+      marker.reinforce(amount: 0.2)
+      expect(marker.strength).to be_within(0.001).of(0.7)
+    end
+
+    it 'caps at 1.0' do
+      marker.reinforce(amount: 0.5)
+      expect(marker.strength).to eq(1.0)
+    end
+  end
+
+  describe '#decay' do
+    it 'reduces strength by MARKER_DECAY' do
+      before = marker.strength
+      marker.decay
+      decay_amount = Legion::Extensions::Interoception::Helpers::Constants::MARKER_DECAY
+      expect(marker.strength).to be_within(0.001).of(before - decay_amount)
+    end
+
+    it 'does not drop below MARKER_FLOOR' do
+      50.times { marker.decay }
+      expect(marker.strength).to be >= Legion::Extensions::Interoception::Helpers::Constants::MARKER_FLOOR
+    end
+  end
+
+  describe '#faded?' do
+    it 'returns false for strong markers' do
+      expect(marker.faded?).to be false
+    end
+
+    it 'returns true at or below floor' do
+      marker.strength = Legion::Extensions::Interoception::Helpers::Constants::MARKER_FLOOR
+      expect(marker.faded?).to be true
+
+      marker.strength = Legion::Extensions::Interoception::Helpers::Constants::MARKER_FLOOR + 0.01
+      expect(marker.faded?).to be false
+    end
+  end
+
+  describe '#positive? / #negative? / #label' do
+    it 'returns :approach for positive valence' do
+      pos = described_class.new(action: :a, domain: :d, valence: 0.5)
+      expect(pos.positive?).to be true
+      expect(pos.negative?).to be false
+      expect(pos.label).to eq(:approach)
+    end
+
+    it 'returns :avoid for negative valence' do
+      neg = described_class.new(action: :a, domain: :d, valence: -0.5)
+      expect(neg.positive?).to be false
+      expect(neg.negative?).to be true
+      expect(neg.label).to eq(:avoid)
+    end
+
+    it 'returns :neutral for middle valence' do
+      mid = described_class.new(action: :a, domain: :d, valence: 0.0)
+      expect(mid.positive?).to be false
+      expect(mid.negative?).to be false
+      expect(mid.label).to eq(:neutral)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with all fields' do
+      h = marker.to_h
+      expect(h).to include(:id, :action, :domain, :valence, :strength, :label, :created_at)
+      expect(h[:action]).to eq(:deploy)
+    end
+  end
+end

data/spec/legion/extensions/interoception/runners/interoception_spec.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Interoception::Runners::Interoception do
+  let(:client) { Legion::Extensions::Interoception::Client.new }
+
+  describe '#report_vital' do
+    it 'reports and smooths a vital signal' do
+      result = client.report_vital(channel: :cpu_load, value: 0.6)
+      expect(result[:success]).to be true
+      expect(result[:channel]).to eq(:cpu_load)
+      expect(result[:smoothed]).to be_a(Float)
+      expect(result).to have_key(:deviation)
+      expect(result).to have_key(:label)
+    end
+
+    it 'tracks deviation from baseline' do
+      5.times { client.report_vital(channel: :cpu_load, value: 0.2) }
+      result = client.report_vital(channel: :cpu_load, value: 0.9)
+      expect(result[:deviation].abs).to be > 0
+    end
+  end
+
+  describe '#create_somatic_marker' do
+    it 'creates a marker with correct fields' do
+      result = client.create_somatic_marker(action: :deploy, domain: :prod, valence: 0.7)
+      expect(result[:success]).to be true
+      expect(result[:marker][:action]).to eq(:deploy)
+      expect(result[:marker][:valence]).to eq(0.7)
+      expect(result[:marker][:label]).to eq(:approach)
+    end
+
+    it 'creates negative marker' do
+      result = client.create_somatic_marker(action: :delete_data, domain: :prod, valence: -0.8)
+      expect(result[:marker][:label]).to eq(:avoid)
+    end
+  end
+
+  describe '#query_bias' do
+    it 'returns neutral with no markers' do
+      result = client.query_bias(action: :deploy)
+      expect(result[:success]).to be true
+      expect(result[:bias]).to eq(0.0)
+      expect(result[:label]).to eq(:neutral)
+    end
+
+    it 'returns approach bias for positive markers' do
+      client.create_somatic_marker(action: :deploy, domain: :prod, valence: 0.8)
+      result = client.query_bias(action: :deploy)
+      expect(result[:bias]).to be > 0
+    end
+
+    it 'returns avoid bias for negative markers' do
+      client.create_somatic_marker(action: :risky_change, domain: :prod, valence: -0.9)
+      result = client.query_bias(action: :risky_change)
+      expect(result[:bias]).to be < 0
+    end
+  end
+
+  describe '#reinforce_somatic' do
+    it 'reinforces matching markers' do
+      client.create_somatic_marker(action: :deploy, domain: :prod, valence: 0.5, strength: 0.3)
+      result = client.reinforce_somatic(action: :deploy, amount: 0.2)
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#deviating_vitals' do
+    it 'returns deviating channels' do
+      result = client.deviating_vitals
+      expect(result[:success]).to be true
+      expect(result[:deviations]).to be_an(Array)
+    end
+  end
+
+  describe '#body_status' do
+    it 'returns overall health status' do
+      client.report_vital(channel: :cpu_load, value: 0.2)
+      result = client.body_status
+      expect(result[:success]).to be true
+      expect(result[:health]).to be_a(Float)
+      expect(result).to have_key(:label)
+      expect(result).to have_key(:channels)
+      expect(result).to have_key(:markers)
+    end
+  end
+
+  describe '#update_interoception' do
+    it 'decays markers and returns status' do
+      client.create_somatic_marker(action: :deploy, domain: :prod, valence: 0.5)
+      result = client.update_interoception
+      expect(result[:success]).to be true
+      expect(result).to have_key(:health)
+      expect(result).to have_key(:label)
+      expect(result).to have_key(:channels)
+      expect(result).to have_key(:markers)
+    end
+  end
+
+  describe '#interoception_stats' do
+    it 'returns comprehensive stats' do
+      client.report_vital(channel: :cpu_load, value: 0.4)
+      client.create_somatic_marker(action: :deploy, domain: :prod, valence: 0.7)
+      result = client.interoception_stats
+      expect(result[:success]).to be true
+      expect(result[:stats]).to include(:overall_health, :body_budget_label, :channels, :markers)
+    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/interoception'
+
+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-interoception
+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: Somatic marker hypothesis for brain-modeled agentic AI — internal body-state
+  monitoring, vital signal tracking, and somatic markers that bias decisions based
+  on past outcomes associated with similar internal states.
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-interoception.gemspec
+- lib/legion/extensions/interoception.rb
+- lib/legion/extensions/interoception/actors/decay.rb
+- lib/legion/extensions/interoception/client.rb
+- lib/legion/extensions/interoception/helpers/body_budget.rb
+- lib/legion/extensions/interoception/helpers/constants.rb
+- lib/legion/extensions/interoception/helpers/somatic_marker.rb
+- lib/legion/extensions/interoception/runners/interoception.rb
+- lib/legion/extensions/interoception/version.rb
+- spec/legion/extensions/interoception/client_spec.rb
+- spec/legion/extensions/interoception/helpers/body_budget_spec.rb
+- spec/legion/extensions/interoception/helpers/somatic_marker_spec.rb
+- spec/legion/extensions/interoception/runners/interoception_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-interoception
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-interoception
+  source_code_uri: https://github.com/LegionIO/lex-interoception
+  documentation_uri: https://github.com/LegionIO/lex-interoception
+  changelog_uri: https://github.com/LegionIO/lex-interoception
+  bug_tracker_uri: https://github.com/LegionIO/lex-interoception/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 Interoception
+test_files: []