lex-motivation 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6cf669a3b751e11795fd50424fec3647cdeee856fbb181667d5125c9d694db98
+  data.tar.gz: 2f3147e4f59ed722387020c994423e39d66a6f0764a2eca6f106425c04a9ee81
+SHA512:
+  metadata.gz: 5f965e9421b730abcdaa5ed951f5804a7fae77df615ef6c0c138316d16207fc0b37c0a47f48a8060a9e1fcf4b379590edc35e8fe957de00c9d0129349a103482
+  data.tar.gz: 9d51bae33770415f66acda673e39235d4828acd302b0c860b986cdeb6c266c72cc8b07332744b55158fa2b5b341138d82e1b40cea711e39df7a8c6e31d20515a

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/motivation/helpers/constants'
+require 'legion/extensions/motivation/helpers/drive_state'
+require 'legion/extensions/motivation/helpers/motivation_store'
+require 'legion/extensions/motivation/runners/motivation'
+
+module Legion
+  module Extensions
+    module Motivation
+      class Client
+        include Runners::Motivation
+
+        attr_reader :motivation_store
+
+        def initialize(motivation_store: nil, **)
+          @motivation_store = motivation_store || Helpers::MotivationStore.new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Motivation
+      module Helpers
+        module Constants
+          # Drive types based on Self-Determination Theory + survival/obligation
+          DRIVE_TYPES = %i[autonomy competence relatedness novelty obligation survival].freeze
+
+          # Motivation operating modes (approach/avoidance model)
+          MOTIVATION_MODES = %i[approach avoidance maintenance dormant].freeze
+
+          # EMA alpha for drive level tracking (slow adaptation)
+          DRIVE_ALPHA = 0.1
+
+          # Intrinsic drives (Self-Determination Theory: autonomy, competence, relatedness + novelty)
+          INTRINSIC_DRIVES = %i[autonomy competence relatedness novelty].freeze
+
+          # Extrinsic drives (external pressure: obligation, survival)
+          EXTRINSIC_DRIVES = %i[obligation survival].freeze
+
+          # Per-tick drive decay rate
+          DRIVE_DECAY_RATE = 0.02
+
+          # Maximum goals tracked simultaneously
+          MAX_GOALS = 50
+
+          # Above this overall level, agent is in approach mode
+          APPROACH_THRESHOLD = 0.6
+
+          # Below this, agent is in avoidance mode
+          AVOIDANCE_THRESHOLD = 0.3
+
+          # Below this across individual drives, drive is in burnout
+          BURNOUT_THRESHOLD = 0.15
+
+          # Below this across ALL drives, agent is amotivated
+          AMOTIVATION_THRESHOLD = 0.2
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/motivation/helpers/drive_state.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Motivation
+      module Helpers
+        class DriveState
+          attr_reader :drives
+
+          def initialize
+            @drives = Constants::DRIVE_TYPES.to_h do |type|
+              [type, { level: 0.5, satisfied: false, last_signal: nil }]
+            end
+          end
+
+          def update_drive(type, signal)
+            return unless Constants::DRIVE_TYPES.include?(type)
+
+            clamped = signal.clamp(0.0, 1.0)
+            current = @drives[type][:level]
+            @drives[type][:level]       = ema(current, clamped, Constants::DRIVE_ALPHA)
+            @drives[type][:satisfied]   = @drives[type][:level] >= 0.6
+            @drives[type][:last_signal] = Time.now.utc
+          end
+
+          def drive_level(type)
+            return 0.0 unless Constants::DRIVE_TYPES.include?(type)
+
+            @drives[type][:level]
+          end
+
+          def satisfied?(type)
+            return false unless Constants::DRIVE_TYPES.include?(type)
+
+            @drives[type][:satisfied]
+          end
+
+          def intrinsic_average
+            levels = Constants::INTRINSIC_DRIVES.map { |d| @drives[d][:level] }
+            mean(levels)
+          end
+
+          def extrinsic_average
+            levels = Constants::EXTRINSIC_DRIVES.map { |d| @drives[d][:level] }
+            mean(levels)
+          end
+
+          def overall_level
+            all_levels = @drives.values.map { |d| d[:level] }
+            mean(all_levels)
+          end
+
+          def current_mode
+            level = overall_level
+            if level >= Constants::APPROACH_THRESHOLD
+              :approach
+            elsif level <= Constants::BURNOUT_THRESHOLD
+              :dormant
+            elsif level <= Constants::AVOIDANCE_THRESHOLD
+              :avoidance
+            else
+              :maintenance
+            end
+          end
+
+          def decay_all
+            @drives.each_key do |type|
+              current = @drives[type][:level]
+              decayed = [current - Constants::DRIVE_DECAY_RATE, 0.0].max
+              @drives[type][:level]     = decayed
+              @drives[type][:satisfied] = decayed >= 0.6
+            end
+          end
+
+          def amotivated?
+            @drives.values.all? { |d| d[:level] < Constants::AMOTIVATION_THRESHOLD }
+          end
+
+          private
+
+          def ema(current, observed, alpha)
+            (current * (1.0 - alpha)) + (observed * alpha)
+          end
+
+          def mean(values)
+            return 0.0 if values.empty?
+
+            values.sum / values.size.to_f
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/motivation/helpers/motivation_store.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Motivation
+      module Helpers
+        class MotivationStore
+          attr_reader :drive_state, :goal_motivations
+
+          def initialize(drive_state: nil)
+            @drive_state      = drive_state || DriveState.new
+            @goal_motivations = {}
+            @low_motivation_ticks = 0
+          end
+
+          def commit_goal(goal_id, drives)
+            valid_drives = Array(drives).select { |d| Constants::DRIVE_TYPES.include?(d) }
+            return false if valid_drives.empty?
+
+            trim_goals
+            @goal_motivations[goal_id] = {
+              drives:       valid_drives,
+              energy:       goal_energy_for(valid_drives),
+              committed:    true,
+              committed_at: Time.now.utc
+            }
+            true
+          end
+
+          def release_goal(goal_id)
+            @goal_motivations.delete(goal_id)
+            true
+          end
+
+          def goal_energy(goal_id)
+            entry = @goal_motivations[goal_id]
+            return 0.0 unless entry
+
+            entry[:energy] = goal_energy_for(entry[:drives])
+            entry[:energy]
+          end
+
+          def most_motivated_goal
+            return nil if @goal_motivations.empty?
+
+            refreshed = @goal_motivations.transform_values do |entry|
+              entry.merge(energy: goal_energy_for(entry[:drives]))
+            end
+
+            best_id, best_entry = refreshed.max_by { |_, v| v[:energy] }
+            return nil unless best_id
+
+            { goal_id: best_id, energy: best_entry[:energy].round(4), drives: best_entry[:drives] }
+          end
+
+          def burnout_check
+            overall = @drive_state.overall_level
+            if overall < Constants::BURNOUT_THRESHOLD
+              @low_motivation_ticks += 1
+            else
+              @low_motivation_ticks = 0
+            end
+
+            {
+              burnout:              @low_motivation_ticks >= 10,
+              low_motivation_ticks: @low_motivation_ticks,
+              overall_level:        overall.round(4)
+            }
+          end
+
+          def stats
+            {
+              overall_level:        @drive_state.overall_level.round(4),
+              current_mode:         @drive_state.current_mode,
+              intrinsic_average:    @drive_state.intrinsic_average.round(4),
+              extrinsic_average:    @drive_state.extrinsic_average.round(4),
+              amotivated:           @drive_state.amotivated?,
+              goal_count:           @goal_motivations.size,
+              low_motivation_ticks: @low_motivation_ticks
+            }
+          end
+
+          private
+
+          def goal_energy_for(drives)
+            return 0.0 if drives.empty?
+
+            total = drives.sum { |d| @drive_state.drive_level(d) }
+            (total / drives.size.to_f).clamp(0.0, 1.0)
+          end
+
+          def trim_goals
+            return unless @goal_motivations.size >= Constants::MAX_GOALS
+
+            oldest_key = @goal_motivations.min_by { |_, v| v[:committed_at] }&.first
+            @goal_motivations.delete(oldest_key) if oldest_key
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Motivation
+      module Runners
+        module Motivation
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def update_motivation(tick_results: {}, **)
+            extract_drive_signals(tick_results)
+            motivation_store.drive_state.decay_all
+            burnout = motivation_store.burnout_check
+            mode    = motivation_store.drive_state.current_mode
+
+            Legion::Logging.debug "[motivation] mode=#{mode} " \
+                                  "overall=#{motivation_store.drive_state.overall_level.round(3)} " \
+                                  "amotivated=#{motivation_store.drive_state.amotivated?}"
+
+            {
+              mode:              mode,
+              overall_level:     motivation_store.drive_state.overall_level.round(4),
+              intrinsic_average: motivation_store.drive_state.intrinsic_average.round(4),
+              extrinsic_average: motivation_store.drive_state.extrinsic_average.round(4),
+              amotivated:        motivation_store.drive_state.amotivated?,
+              burnout:           burnout[:burnout]
+            }
+          end
+
+          def signal_drive(drive:, signal:, **)
+            drive_sym = drive.to_sym
+            return { success: false, error: "unknown drive: #{drive}" } unless Helpers::Constants::DRIVE_TYPES.include?(drive_sym)
+
+            motivation_store.drive_state.update_drive(drive_sym, signal.to_f)
+            level = motivation_store.drive_state.drive_level(drive_sym)
+
+            Legion::Logging.debug "[motivation] drive signal: #{drive_sym}=#{level.round(3)}"
+            { success: true, drive: drive_sym, level: level.round(4) }
+          end
+
+          def commit_to_goal(goal_id:, drives:, **)
+            drive_syms = Array(drives).map(&:to_sym)
+            result = motivation_store.commit_goal(goal_id, drive_syms)
+
+            if result
+              energy = motivation_store.goal_energy(goal_id)
+              Legion::Logging.info "[motivation] committed goal=#{goal_id} energy=#{energy.round(3)}"
+              { success: true, goal_id: goal_id, energy: energy.round(4) }
+            else
+              Legion::Logging.warn "[motivation] commit_goal rejected: no valid drives for #{goal_id}"
+              { success: false, error: 'no valid drives provided' }
+            end
+          end
+
+          def release_goal(goal_id:, **)
+            motivation_store.release_goal(goal_id)
+            Legion::Logging.debug "[motivation] released goal=#{goal_id}"
+            { success: true, goal_id: goal_id }
+          end
+
+          def motivation_for(goal_id:, **)
+            energy = motivation_store.goal_energy(goal_id)
+            Legion::Logging.debug "[motivation] motivation_for goal=#{goal_id} energy=#{energy.round(3)}"
+            { goal_id: goal_id, energy: energy.round(4) }
+          end
+
+          def most_motivated_goal(**)
+            result = motivation_store.most_motivated_goal
+            Legion::Logging.debug "[motivation] most_motivated_goal=#{result&.fetch(:goal_id, nil)}"
+            result || { goal_id: nil, energy: 0.0, drives: [] }
+          end
+
+          def drive_status(**)
+            drives = motivation_store.drive_state.drives.transform_values do |d|
+              { level: d[:level].round(4), satisfied: d[:satisfied] }
+            end
+
+            Legion::Logging.debug '[motivation] drive_status'
+            {
+              drives:  drives,
+              mode:    motivation_store.drive_state.current_mode,
+              overall: motivation_store.drive_state.overall_level.round(4)
+            }
+          end
+
+          def motivation_stats(**)
+            Legion::Logging.debug '[motivation] stats'
+            motivation_store.stats
+          end
+
+          private
+
+          def motivation_store
+            @motivation_store ||= Helpers::MotivationStore.new
+          end
+
+          def extract_drive_signals(tick_results)
+            extract_autonomy_signal(tick_results)
+            extract_competence_signal(tick_results)
+            extract_relatedness_signal(tick_results)
+            extract_novelty_signal(tick_results)
+            extract_obligation_signal(tick_results)
+            extract_survival_signal(tick_results)
+          end
+
+          def extract_autonomy_signal(tick_results)
+            consent_tier = tick_results.dig(:consent, :tier)
+            return unless consent_tier
+
+            signal = case consent_tier
+                     when :autonomous then 1.0
+                     when :collaborate then 0.7
+                     when :consult     then 0.4
+                     else 0.1
+                     end
+            motivation_store.drive_state.update_drive(:autonomy, signal)
+          end
+
+          def extract_competence_signal(tick_results)
+            accuracy = tick_results.dig(:prediction_engine, :accuracy)
+            return unless accuracy
+
+            motivation_store.drive_state.update_drive(:competence, accuracy.to_f)
+          end
+
+          def extract_relatedness_signal(tick_results)
+            trust_level = tick_results.dig(:trust, :overall_level)
+            return unless trust_level
+
+            motivation_store.drive_state.update_drive(:relatedness, trust_level.to_f)
+          end
+
+          def extract_novelty_signal(tick_results)
+            novel = tick_results.dig(:memory_retrieval, :novel_traces)
+            return unless novel
+
+            signal = novel.positive? ? [novel.to_f / 10.0, 1.0].min : 0.1
+            motivation_store.drive_state.update_drive(:novelty, signal)
+          end
+
+          def extract_obligation_signal(tick_results)
+            pending = tick_results.dig(:scheduler, :pending_tasks)
+            return unless pending
+
+            signal = pending.positive? ? [pending.to_f / 20.0, 1.0].min : 0.0
+            motivation_store.drive_state.update_drive(:obligation, signal)
+          end
+
+          def extract_survival_signal(tick_results)
+            extinction_level = tick_results.dig(:extinction, :level)
+            return unless extinction_level
+
+            signal = extinction_level.to_f / 4.0
+            motivation_store.drive_state.update_drive(:survival, signal)
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/motivation.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/motivation/version'
+require 'legion/extensions/motivation/helpers/constants'
+require 'legion/extensions/motivation/helpers/drive_state'
+require 'legion/extensions/motivation/helpers/motivation_store'
+require 'legion/extensions/motivation/runners/motivation'
+require 'legion/extensions/motivation/client'
+
+module Legion
+  module Extensions
+    module Motivation
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined?(:Core)
+    end
+  end
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: lex-motivation
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Matthew Iverson
+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: Models motivational drive states — why the agent acts, what energizes
+  behavior, and how approach vs avoidance tendencies operate
+email:
+- matt@legionIO.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/legion/extensions/motivation.rb
+- lib/legion/extensions/motivation/client.rb
+- lib/legion/extensions/motivation/helpers/constants.rb
+- lib/legion/extensions/motivation/helpers/drive_state.rb
+- lib/legion/extensions/motivation/helpers/motivation_store.rb
+- lib/legion/extensions/motivation/runners/motivation.rb
+- lib/legion/extensions/motivation/version.rb
+homepage: https://github.com/LegionIO/lex-motivation
+licenses:
+- MIT
+metadata:
+  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: Goal-directed motivation and drive states for LegionIO cognitive agents
+test_files: []