lex-somatic-marker 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d139fd458759ac7941be893a1b5d8030e1923d366d1e8a79a796d18afee34044
+  data.tar.gz: 0ffb155f12fdae620c562849a81c1fbbcaf224e7b5b9ca4e81365615fe1dcd54
+SHA512:
+  metadata.gz: 273656c152ceb7d137acbd0dbef32305d4acf57802347ec816f2e4f7e5a371b714a0b02ea88a4273b915458df85cc16cdbc2c1edbfdf925411c4b8d44b803cbb
+  data.tar.gz: a6924be1392b3adfbdab40357888e81b066c246f306781b6e512c21b7a437e9d3df2059b39cb9a2bf00be9d03861cd9e3155c8b0dfb9b5e19ba5aab81074dba1

data/Gemfile

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

data/LICENSE

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

data/README.md

@@ -0,0 +1,61 @@
+# lex-somatic-marker
+
+Damasio Somatic Marker Hypothesis implementation for LegionIO cognitive agents. Affective signals associated with past actions bias future decision-making toward approach or avoidance.
+
+## What It Does
+
+`lex-somatic-marker` models how learned bodily signals (somatic markers) guide decisions. Each action the agent considers has an associated marker with a valence score. Positive valence produces an `:approach` signal; negative valence produces `:avoid`. A BodyState tracks global arousal, tension, comfort, and gut signal, providing the affective context in which decisions are made.
+
+- **Markers**: action-associated valence scores, updated via EMA on each outcome
+- **Signal**: `:approach` (valence > 0.6), `:avoid` (valence < -0.6), or `:neutral`
+- **BodyState**: arousal, tension, comfort, gut_signal — composite valence = `comfort*0.4 + (1-tension)*0.3 + gut_signal*0.3`
+- **Decision ranking**: `make_decision` evaluates multiple options and ranks by valence
+- **Decay**: marker valence and body state drift toward neutral each tick
+
+## Usage
+
+```ruby
+require 'legion/extensions/somatic_marker'
+
+client = Legion::Extensions::SomaticMarker::Client.new
+
+# Register a marker for an action
+result = client.register_marker(action: 'deploy_without_tests', domain: :engineering)
+marker_id = result[:marker_id]
+
+# Bad outcome — reinforce with negative valence
+client.reinforce(marker_id: marker_id, outcome_valence: -0.9)
+# => { valence: -0.11, signal: :neutral }  (first update from 0.0)
+
+# After repeated bad outcomes, signal becomes :avoid
+client.reinforce(marker_id: marker_id, outcome_valence: -0.9)
+# => { valence: -0.21, signal: :neutral }
+
+# Evaluate an option
+client.evaluate_option(action: 'deploy_without_tests')
+# => { signal: :neutral, valence: -0.21, body_valence: 0.59 }
+
+# Rank multiple options
+client.make_decision(options: ['deploy_without_tests', 'add_tests_first', 'skip_deployment'])
+# => { ranked_options: [...], recommended: 'add_tests_first' }
+
+# Update body state (e.g., from emotion evaluation)
+client.update_body(dimension: :tension, value: 0.8)
+client.body_state
+# => { arousal: 0.5, tension: 0.8, comfort: 0.7, gut_signal: 0.0, composite_valence: 0.46, stressed: false }
+
+# Per-tick decay
+client.update_somatic_markers
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-somatic-marker.gemspec

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

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

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/somatic_marker/helpers/constants'
+require 'legion/extensions/somatic_marker/helpers/somatic_marker'
+require 'legion/extensions/somatic_marker/helpers/body_state'
+require 'legion/extensions/somatic_marker/helpers/marker_store'
+require 'legion/extensions/somatic_marker/runners/somatic_marker'
+
+module Legion
+  module Extensions
+    module SomaticMarker
+      class Client
+        include Runners::SomaticMarker
+
+        def initialize(**)
+          @store = Helpers::MarkerStore.new
+        end
+
+        private
+
+        attr_reader :store
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module SomaticMarker
+      module Helpers
+        class BodyState
+          include Constants
+
+          attr_reader :arousal, :tension, :comfort, :gut_signal
+
+          def initialize(arousal: 0.5, tension: 0.5, comfort: 0.5, gut_signal: 0.0)
+            @arousal    = arousal.clamp(0.0, 1.0)
+            @tension    = tension.clamp(0.0, 1.0)
+            @comfort    = comfort.clamp(0.0, 1.0)
+            @gut_signal = gut_signal.clamp(-1.0, 1.0)
+          end
+
+          def update(arousal: nil, tension: nil, comfort: nil, gut_signal: nil)
+            @arousal    = arousal.clamp(0.0, 1.0)    if arousal
+            @tension    = tension.clamp(0.0, 1.0)    if tension
+            @comfort    = comfort.clamp(0.0, 1.0)    if comfort
+            @gut_signal = gut_signal.clamp(-1.0, 1.0) if gut_signal
+          end
+
+          def composite_valence
+            (@comfort * 0.4) + ((1.0 - @tension) * 0.3) + (@gut_signal * 0.3)
+          end
+
+          def decay
+            @arousal    = drift(@arousal,    0.5, BODY_STATE_DECAY)
+            @tension    = drift(@tension,    0.5, BODY_STATE_DECAY)
+            @comfort    = drift(@comfort,    0.5, BODY_STATE_DECAY)
+            @gut_signal = drift(@gut_signal, 0.0, BODY_STATE_DECAY)
+          end
+
+          def stressed?
+            @tension > 0.7 && @comfort < 0.3
+          end
+
+          def to_h
+            {
+              arousal:           @arousal,
+              tension:           @tension,
+              comfort:           @comfort,
+              gut_signal:        @gut_signal,
+              composite_valence: composite_valence,
+              stressed:          stressed?
+            }
+          end
+
+          private
+
+          def drift(value, target, rate)
+            if value > target
+              (value - rate).clamp(target, 1.0)
+            else
+              (value + rate).clamp(-1.0, target)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module SomaticMarker
+      module Helpers
+        module Constants
+          MAX_MARKERS              = 500
+          MAX_OPTIONS_PER_DECISION = 20
+          MAX_DECISION_HISTORY     = 200
+          MARKER_DECAY             = 0.01
+          MARKER_STRENGTH_FLOOR    = 0.05
+          MARKER_ALPHA             = 0.12
+          POSITIVE_BIAS            = 0.6
+          NEGATIVE_BIAS            = -0.6
+          DEFAULT_VALENCE          = 0.0
+          REINFORCEMENT_BOOST      = 0.15
+          PUNISHMENT_PENALTY       = 0.2
+          BODY_STATE_DECAY         = 0.03
+          MAX_BODY_STATES          = 50
+
+          VALENCE_LABELS = {
+            (-1.0..-0.6) => :strongly_negative,
+            (-0.6..-0.2) => :negative,
+            (-0.2..0.2)  => :neutral,
+            (0.2..0.6)   => :positive,
+            (0.6..1.0)   => :strongly_positive
+          }.freeze
+
+          SIGNAL_LABELS = {
+            approach: 'somatic signal favoring action',
+            avoid:    'somatic signal against action',
+            neutral:  'no clear somatic signal'
+          }.freeze
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module SomaticMarker
+      module Helpers
+        class MarkerStore
+          include Constants
+
+          attr_reader :markers, :body_state
+
+          def initialize
+            @markers          = {}
+            @body_state       = BodyState.new
+            @decision_history = []
+            @next_id          = 1
+          end
+
+          def register_marker(action:, domain:, valence:, source: :experience)
+            evict_weakest if @markers.size >= MAX_MARKERS
+
+            id     = generate_id
+            marker = SomaticMarker.new(
+              id:      id,
+              action:  action,
+              domain:  domain,
+              valence: valence,
+              source:  source
+            )
+            @markers[id] = marker
+            marker
+          end
+
+          def evaluate_option(action:, domain:)
+            relevant = markers_for(action: action, domain: domain)
+            return { signal: :neutral, valence: DEFAULT_VALENCE, marker_count: 0 } if relevant.empty?
+
+            weighted_valence = compute_weighted_valence(relevant)
+            signal           = valence_to_signal(weighted_valence)
+            { signal: signal, valence: weighted_valence, marker_count: relevant.size }
+          end
+
+          def decide(options:, domain:)
+            capped = options.first(MAX_OPTIONS_PER_DECISION)
+            ranked = capped.map do |option|
+              eval_result = evaluate_option(action: option, domain: domain)
+              {
+                action:       option,
+                signal:       eval_result[:signal],
+                valence:      eval_result[:valence],
+                marker_count: eval_result[:marker_count]
+              }
+            end
+
+            ranked.sort_by! { |r| -r[:valence] }
+
+            body_contribution = body_influence
+
+            record = {
+              options:           capped,
+              ranked:            ranked,
+              domain:            domain,
+              body_contribution: body_contribution,
+              decided_at:        Time.now.utc
+            }
+
+            @decision_history.shift while @decision_history.size >= MAX_DECISION_HISTORY
+            @decision_history << record
+
+            record
+          end
+
+          def reinforce_marker(marker_id:, outcome_valence:)
+            marker = @markers[marker_id]
+            return nil unless marker
+
+            marker.reinforce(outcome_valence: outcome_valence)
+            marker
+          end
+
+          def update_body_state(arousal: nil, tension: nil, comfort: nil, gut_signal: nil)
+            @body_state.update(
+              arousal:    arousal,
+              tension:    tension,
+              comfort:    comfort,
+              gut_signal: gut_signal
+            )
+            @body_state
+          end
+
+          def markers_for(action:, domain:)
+            @markers.values.select { |m| m.action == action && m.domain == domain }
+          end
+
+          def body_influence
+            {
+              composite_valence: @body_state.composite_valence,
+              stressed:          @body_state.stressed?
+            }
+          end
+
+          def decay_all
+            @markers.each_value(&:decay)
+            faded_ids = @markers.select { |_id, m| m.faded? }.keys
+            faded_ids.each { |id| @markers.delete(id) }
+            @body_state.decay
+            { markers_decayed: @markers.size, markers_removed: faded_ids.size }
+          end
+
+          def decision_history(limit: 10)
+            @decision_history.last(limit)
+          end
+
+          def to_h
+            {
+              marker_count:   @markers.size,
+              decision_count: @decision_history.size,
+              body_state:     @body_state.to_h,
+              stressed:       @body_state.stressed?
+            }
+          end
+
+          private
+
+          def compute_weighted_valence(relevant)
+            total_strength = relevant.sum(&:strength)
+            return DEFAULT_VALENCE unless total_strength.positive?
+
+            relevant.sum { |m| m.valence * m.strength } / total_strength
+          end
+
+          def valence_to_signal(weighted_valence)
+            if weighted_valence > POSITIVE_BIAS
+              :approach
+            elsif weighted_valence < NEGATIVE_BIAS
+              :avoid
+            else
+              :neutral
+            end
+          end
+
+          def generate_id
+            id = "sm_#{@next_id}"
+            @next_id += 1
+            id
+          end
+
+          def evict_weakest
+            weakest_id = @markers.min_by { |_id, m| m.strength }&.first
+            @markers.delete(weakest_id) if weakest_id
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module SomaticMarker
+      module Helpers
+        class SomaticMarker
+          include Constants
+
+          attr_reader :id, :action, :domain, :valence, :strength, :source, :created_at
+
+          def initialize(id:, action:, domain:, valence:, strength: 0.5, source: :experience)
+            @id         = id
+            @action     = action
+            @domain     = domain
+            @valence    = valence.clamp(-1.0, 1.0)
+            @strength   = strength.clamp(0.0, 1.0)
+            @source     = source
+            @created_at = Time.now.utc
+          end
+
+          def signal
+            if @valence > POSITIVE_BIAS
+              :approach
+            elsif @valence < NEGATIVE_BIAS
+              :avoid
+            else
+              :neutral
+            end
+          end
+
+          def reinforce(outcome_valence:)
+            @valence  = (MARKER_ALPHA * outcome_valence) + ((1.0 - MARKER_ALPHA) * @valence)
+            @valence  = @valence.clamp(-1.0, 1.0)
+            @strength = (@strength + REINFORCEMENT_BOOST).clamp(0.0, 1.0)
+          end
+
+          def decay
+            @strength = (@strength - MARKER_DECAY).clamp(0.0, 1.0)
+          end
+
+          def faded?
+            @strength <= MARKER_STRENGTH_FLOOR
+          end
+
+          def valence_label
+            VALENCE_LABELS.each do |range, label|
+              return label if range.cover?(@valence)
+            end
+            :neutral
+          end
+
+          def to_h
+            {
+              id:         @id,
+              action:     @action,
+              domain:     @domain,
+              valence:    @valence,
+              strength:   @strength,
+              source:     @source,
+              signal:     signal,
+              label:      valence_label,
+              created_at: @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module SomaticMarker
+      module Runners
+        module SomaticMarker
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def register_marker(action:, domain:, valence:, source: :experience, **)
+            marker = store.register_marker(action: action, domain: domain, valence: valence, source: source)
+            Legion::Logging.debug "[somatic_marker] register: action=#{action} domain=#{domain} " \
+                                  "valence=#{valence.round(3)} source=#{source} id=#{marker.id}"
+            { success: true, marker: marker.to_h }
+          rescue StandardError => e
+            Legion::Logging.error "[somatic_marker] register failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def evaluate_option(action:, domain:, **)
+            result = store.evaluate_option(action: action, domain: domain)
+            Legion::Logging.debug "[somatic_marker] evaluate: action=#{action} domain=#{domain} " \
+                                  "signal=#{result[:signal]} valence=#{result[:valence].round(3)}"
+            { success: true }.merge(result)
+          rescue StandardError => e
+            Legion::Logging.error "[somatic_marker] evaluate failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def make_decision(options:, domain:, **)
+            result = store.decide(options: options, domain: domain)
+            Legion::Logging.debug "[somatic_marker] decide: domain=#{domain} options=#{options.size} " \
+                                  "top=#{result[:ranked].first&.fetch(:action)}"
+            { success: true, decision: result }
+          rescue StandardError => e
+            Legion::Logging.error "[somatic_marker] decide failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def reinforce(marker_id:, outcome_valence:, **)
+            marker = store.reinforce_marker(marker_id: marker_id, outcome_valence: outcome_valence)
+            unless marker
+              Legion::Logging.debug "[somatic_marker] reinforce: marker_id=#{marker_id} not found"
+              return { success: false, error: 'marker not found' }
+            end
+
+            Legion::Logging.debug "[somatic_marker] reinforce: id=#{marker_id} " \
+                                  "outcome=#{outcome_valence.round(3)} new_valence=#{marker.valence.round(3)}"
+            { success: true, marker: marker.to_h }
+          rescue StandardError => e
+            Legion::Logging.error "[somatic_marker] reinforce failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def update_body(arousal: nil, tension: nil, comfort: nil, gut_signal: nil, **)
+            state = store.update_body_state(
+              arousal:    arousal,
+              tension:    tension,
+              comfort:    comfort,
+              gut_signal: gut_signal
+            )
+            Legion::Logging.debug "[somatic_marker] body_update: composite=#{state.composite_valence.round(3)} " \
+                                  "stressed=#{state.stressed?}"
+            { success: true, body_state: state.to_h }
+          rescue StandardError => e
+            Legion::Logging.error "[somatic_marker] body update failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def body_state(**)
+            state = store.body_state
+            Legion::Logging.debug "[somatic_marker] body_state: composite=#{state.composite_valence.round(3)}"
+            { success: true, body_state: state.to_h }
+          rescue StandardError => e
+            Legion::Logging.error "[somatic_marker] body_state failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def markers_for_action(action:, domain:, **)
+            markers = store.markers_for(action: action, domain: domain)
+            Legion::Logging.debug "[somatic_marker] markers_for: action=#{action} domain=#{domain} " \
+                                  "count=#{markers.size}"
+            { success: true, markers: markers.map(&:to_h), count: markers.size }
+          rescue StandardError => e
+            Legion::Logging.error "[somatic_marker] markers_for_action failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def recent_decisions(limit: 10, **)
+            decisions = store.decision_history(limit: limit)
+            Legion::Logging.debug "[somatic_marker] recent_decisions: limit=#{limit} count=#{decisions.size}"
+            { success: true, decisions: decisions, count: decisions.size }
+          rescue StandardError => e
+            Legion::Logging.error "[somatic_marker] recent_decisions failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def update_somatic_markers(**)
+            result = store.decay_all
+            Legion::Logging.debug "[somatic_marker] decay: remaining=#{result[:markers_decayed]} " \
+                                  "removed=#{result[:markers_removed]}"
+            { success: true }.merge(result)
+          rescue StandardError => e
+            Legion::Logging.error "[somatic_marker] decay failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def somatic_marker_stats(**)
+            stats = store.to_h
+            Legion::Logging.debug "[somatic_marker] stats: markers=#{stats[:marker_count]} " \
+                                  "decisions=#{stats[:decision_count]}"
+            { success: true }.merge(stats)
+          rescue StandardError => e
+            Legion::Logging.error "[somatic_marker] stats failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          private
+
+          def store
+            @store ||= Helpers::MarkerStore.new
+          end
+        end
+      end
+    end
+  end
+end

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

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