lex-temporal-discounting 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 21a237076ed20a409650645d82f97cc71d6ebb19887c1086292784145ea76d70
+  data.tar.gz: f5d63d9514bca73170da0ca88625129e6d5f1d3cb7f40f6bee93b29de14d49d1
+SHA512:
+  metadata.gz: a583760854c89b814f44f51e70f63fa1300e36a7ce5c3604865b78fe4721f8209f9a1aded7eeabaaa2606e9262b8b8ad19387daa5a6130d50c61f16be48c9051
+  data.tar.gz: b0e1c81d05ce3ad7a101a7be8a2d04ac5dd206927eb77265fed9a573d6a71b220b2c17b443f085d13d112e53fd70ef0b11319406a2561876c16c757f09c514dc

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-temporal-discounting.gemspec

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

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/temporal_discounting/helpers/constants'
+require 'legion/extensions/temporal_discounting/helpers/reward'
+require 'legion/extensions/temporal_discounting/helpers/discounting_engine'
+require 'legion/extensions/temporal_discounting/runners/temporal_discounting'
+
+module Legion
+  module Extensions
+    module TemporalDiscounting
+      class Client
+        include Runners::TemporalDiscounting
+
+        def engine
+          @engine ||= Helpers::DiscountingEngine.new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module TemporalDiscounting
+      module Helpers
+        DEFAULT_DISCOUNT_RATE = 0.1
+        MIN_DISCOUNT_RATE     = 0.01
+        MAX_DISCOUNT_RATE     = 1.0
+        MAX_REWARDS           = 500
+        DEFAULT_DELAY         = 1.0
+
+        IMPULSIVITY_LABELS = {
+          (0.0...0.05)  => :patient,
+          (0.05...0.15) => :moderate,
+          (0.15...0.3)  => :impulsive,
+          (0.3...0.6)   => :very_impulsive,
+          (0.6..1.0)    => :extreme
+        }.freeze
+
+        VALUE_LABELS = {
+          (0.8..)     => :full_value,
+          (0.6...0.8) => :high_value,
+          (0.4...0.6) => :moderate_value,
+          (0.2...0.4) => :low_value,
+          (..0.2)     => :negligible
+        }.freeze
+      end
+    end
+  end
+end

data/lib/legion/extensions/temporal_discounting/helpers/discounting_engine.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module TemporalDiscounting
+      module Helpers
+        class DiscountingEngine
+          attr_reader :rewards, :domain_rates
+
+          def initialize
+            @rewards      = {}
+            @domain_rates = {}
+          end
+
+          def create_reward(label:, amount:, delay:, domain: :general, discount_rate: nil)
+            rate = discount_rate || get_domain_rate(domain)
+            reward = Reward.new(label: label, amount: amount, delay: delay, domain: domain, discount_rate: rate)
+            @rewards[reward.id] = reward
+            @rewards.shift while @rewards.size > MAX_REWARDS
+            reward
+          end
+
+          def compare_rewards(reward_a_id:, reward_b_id:)
+            a = @rewards.fetch(reward_a_id, nil)
+            b = @rewards.fetch(reward_b_id, nil)
+            return { error: :not_found, missing: missing_ids(reward_a_id, reward_b_id) } if a.nil? || b.nil?
+
+            delta = (a.subjective_value - b.subjective_value).round(10)
+            preferred = if delta.positive?
+                          reward_a_id
+                        elsif delta.negative?
+                          reward_b_id
+                        else
+                          :tied
+                        end
+
+            {
+              preferred:      preferred,
+              delta:          delta.abs,
+              reward_a_value: a.subjective_value,
+              reward_b_value: b.subjective_value
+            }
+          end
+
+          def worth_waiting_for?(reward_id:, threshold: 0.3)
+            reward = @rewards.fetch(reward_id, nil)
+            return { error: :not_found } if reward.nil?
+
+            { reward_id: reward_id, worth_waiting: reward.worth_waiting?(threshold: threshold),
+              subjective_value: reward.subjective_value, threshold: threshold }
+          end
+
+          def set_domain_rate(domain:, rate:)
+            @domain_rates[domain] = rate.clamp(MIN_DISCOUNT_RATE, MAX_DISCOUNT_RATE)
+          end
+
+          def get_domain_rate(domain)
+            @domain_rates.fetch(domain, DEFAULT_DISCOUNT_RATE)
+          end
+
+          def immediate_vs_delayed(immediate_amount:, delayed_amount:, delay:, domain: :general)
+            k = get_domain_rate(domain)
+            delayed_sv = (delayed_amount / (1.0 + (k * delay.to_f))).round(10)
+            immediate_sv = immediate_amount.to_f.clamp(0.0, 1.0).round(10)
+
+            preferred = immediate_sv >= delayed_sv ? :immediate : :delayed
+
+            {
+              preferred:       preferred,
+              immediate_value: immediate_sv,
+              delayed_value:   delayed_sv,
+              delta:           (immediate_sv - delayed_sv).abs.round(10),
+              discount_rate:   k
+            }
+          end
+
+          def optimal_delay(reward_id:, min_value: 0.5)
+            reward = @rewards.fetch(reward_id, nil)
+            return { error: :not_found } if reward.nil?
+
+            k = reward.discount_rate
+            a = reward.amount
+            return { error: :threshold_too_high } if min_value > a
+
+            max_delay = ((a / min_value) - 1.0) / k
+            {
+              reward_id:     reward_id,
+              max_delay:     max_delay.round(10),
+              min_value:     min_value,
+              amount:        a,
+              discount_rate: k
+            }
+          end
+
+          def patience_report
+            return empty_patience_report if @rewards.empty?
+
+            values        = @rewards.values
+            avg_rate      = (values.sum(&:discount_rate) / values.size).round(10)
+            avg_sv        = (values.sum(&:subjective_value) / values.size).round(10)
+            distribution  = build_impulsivity_distribution(values)
+
+            {
+              total_rewards:            @rewards.size,
+              avg_discount_rate:        avg_rate,
+              avg_subjective_value:     avg_sv,
+              impulsivity_distribution: distribution
+            }
+          end
+
+          def rewards_by_domain(domain:)
+            @rewards.values.select { |r| r.domain == domain }
+          end
+
+          def most_valuable(limit: 5)
+            @rewards.values
+                    .sort_by { |r| -r.subjective_value }
+                    .first(limit)
+          end
+
+          def prune_expired(min_value: 0.05)
+            before = @rewards.size
+            @rewards.reject! { |_, r| r.subjective_value < min_value }
+            { pruned: before - @rewards.size, remaining: @rewards.size }
+          end
+
+          def to_h
+            {
+              total_rewards: @rewards.size,
+              domain_rates:  @domain_rates,
+              patience:      patience_report
+            }
+          end
+
+          private
+
+          def missing_ids(id_a, id_b)
+            missing = []
+            missing << id_a unless @rewards.key?(id_a)
+            missing << id_b unless @rewards.key?(id_b)
+            missing
+          end
+
+          def empty_patience_report
+            {
+              total_rewards:            0,
+              avg_discount_rate:        0.0,
+              avg_subjective_value:     0.0,
+              impulsivity_distribution: {}
+            }
+          end
+
+          def build_impulsivity_distribution(values)
+            distribution = Hash.new(0)
+            values.each { |r| distribution[r.impulsivity_label] += 1 }
+            distribution
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/temporal_discounting/helpers/reward.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module TemporalDiscounting
+      module Helpers
+        class Reward
+          attr_reader :id, :label, :amount, :delay, :domain, :discount_rate, :created_at
+
+          def initialize(label:, amount:, delay:, domain: :general, discount_rate: DEFAULT_DISCOUNT_RATE)
+            @id            = SecureRandom.uuid
+            @label         = label
+            @amount        = amount.clamp(0.0, 1.0)
+            @delay         = delay.to_f
+            @domain        = domain
+            @discount_rate = discount_rate.clamp(MIN_DISCOUNT_RATE, MAX_DISCOUNT_RATE)
+            @created_at    = Time.now.utc
+          end
+
+          def subjective_value
+            (@amount / (1.0 + (@discount_rate * @delay))).round(10)
+          end
+
+          def value_ratio
+            return 0.0 if @amount.zero?
+
+            (subjective_value / @amount).round(10)
+          end
+
+          def value_label
+            ratio = value_ratio
+            VALUE_LABELS.each do |range, label|
+              return label if range.cover?(ratio)
+            end
+            :negligible
+          end
+
+          def impulsivity_label
+            k = @discount_rate
+            IMPULSIVITY_LABELS.each do |range, label|
+              return label if range.cover?(k)
+            end
+            :extreme
+          end
+
+          def worth_waiting?(threshold: 0.3)
+            subjective_value >= threshold
+          end
+
+          def adjust_delay!(new_delay:)
+            @delay = new_delay.to_f
+          end
+
+          def adjust_discount_rate!(new_rate:)
+            @discount_rate = new_rate.clamp(MIN_DISCOUNT_RATE, MAX_DISCOUNT_RATE)
+          end
+
+          def to_h
+            {
+              id:                @id,
+              label:             @label,
+              amount:            @amount,
+              delay:             @delay,
+              domain:            @domain,
+              discount_rate:     @discount_rate,
+              subjective_value:  subjective_value,
+              value_ratio:       value_ratio,
+              value_label:       value_label,
+              impulsivity_label: impulsivity_label,
+              worth_waiting:     worth_waiting?,
+              created_at:        @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module TemporalDiscounting
+      module Runners
+        module TemporalDiscounting
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def create_temporal_reward(label:, amount:, delay:, domain: :general, discount_rate: nil, **)
+            reward = engine.create_reward(label: label, amount: amount, delay: delay,
+                                          domain: domain, discount_rate: discount_rate)
+            Legion::Logging.debug "[temporal_discounting] created reward id=#{reward.id[0..7]} " \
+                                  "sv=#{reward.subjective_value.round(4)} label=#{label}"
+            { success: true, reward: reward.to_h }
+          rescue StandardError => e
+            Legion::Logging.warn "[temporal_discounting] create_temporal_reward failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def compare_temporal_rewards(reward_a_id:, reward_b_id:, **)
+            result = engine.compare_rewards(reward_a_id: reward_a_id, reward_b_id: reward_b_id)
+            Legion::Logging.debug "[temporal_discounting] compare preferred=#{result[:preferred]}"
+            { success: !result.key?(:error), **result }
+          rescue StandardError => e
+            Legion::Logging.warn "[temporal_discounting] compare_temporal_rewards failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def check_worth_waiting(reward_id:, threshold: 0.3, **)
+            result = engine.worth_waiting_for?(reward_id: reward_id, threshold: threshold)
+            Legion::Logging.debug "[temporal_discounting] worth_waiting=#{result[:worth_waiting]} id=#{reward_id[0..7]}"
+            { success: !result.key?(:error), **result }
+          rescue StandardError => e
+            Legion::Logging.warn "[temporal_discounting] check_worth_waiting failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def immediate_vs_delayed_comparison(immediate_amount:, delayed_amount:, delay:, domain: :general, **)
+            result = engine.immediate_vs_delayed(
+              immediate_amount: immediate_amount,
+              delayed_amount:   delayed_amount,
+              delay:            delay,
+              domain:           domain
+            )
+            Legion::Logging.debug "[temporal_discounting] imm_vs_delayed preferred=#{result[:preferred]}"
+            { success: true, **result }
+          rescue StandardError => e
+            Legion::Logging.warn "[temporal_discounting] immediate_vs_delayed_comparison failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def compute_optimal_delay(reward_id:, min_value: 0.5, **)
+            result = engine.optimal_delay(reward_id: reward_id, min_value: min_value)
+            Legion::Logging.debug "[temporal_discounting] optimal_delay=#{result[:max_delay]} id=#{reward_id[0..7]}"
+            { success: !result.key?(:error), **result }
+          rescue StandardError => e
+            Legion::Logging.warn "[temporal_discounting] compute_optimal_delay failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def temporal_patience_report(**)
+            report = engine.patience_report
+            Legion::Logging.debug "[temporal_discounting] patience_report total=#{report[:total_rewards]}"
+            { success: true, **report }
+          rescue StandardError => e
+            Legion::Logging.warn "[temporal_discounting] temporal_patience_report failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def set_domain_discount_rate(domain:, rate:, **)
+            engine.set_domain_rate(domain: domain, rate: rate)
+            Legion::Logging.debug "[temporal_discounting] set domain=#{domain} rate=#{rate}"
+            { success: true, domain: domain, rate: engine.get_domain_rate(domain) }
+          rescue StandardError => e
+            Legion::Logging.warn "[temporal_discounting] set_domain_discount_rate failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def most_valuable_rewards(limit: 5, **)
+            rewards = engine.most_valuable(limit: limit)
+            Legion::Logging.debug "[temporal_discounting] most_valuable count=#{rewards.size}"
+            { success: true, rewards: rewards.map(&:to_h), count: rewards.size }
+          rescue StandardError => e
+            Legion::Logging.warn "[temporal_discounting] most_valuable_rewards failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def update_temporal_discounting(min_value: 0.05, **)
+            prune_result = engine.prune_expired(min_value: min_value)
+            stats = engine.to_h
+            Legion::Logging.debug "[temporal_discounting] update pruned=#{prune_result[:pruned]} " \
+                                  "remaining=#{prune_result[:remaining]}"
+            { success: true, pruned: prune_result[:pruned], remaining: prune_result[:remaining], stats: stats }
+          rescue StandardError => e
+            Legion::Logging.warn "[temporal_discounting] update_temporal_discounting failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def temporal_discounting_stats(**)
+            stats = engine.to_h
+            Legion::Logging.debug "[temporal_discounting] stats total=#{stats[:total_rewards]}"
+            { success: true, **stats }
+          rescue StandardError => e
+            Legion::Logging.warn "[temporal_discounting] temporal_discounting_stats failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          private
+
+          def engine
+            @engine ||= Helpers::DiscountingEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/temporal_discounting.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/temporal_discounting/version'
+require 'legion/extensions/temporal_discounting/helpers/constants'
+require 'legion/extensions/temporal_discounting/helpers/reward'
+require 'legion/extensions/temporal_discounting/helpers/discounting_engine'
+require 'legion/extensions/temporal_discounting/runners/temporal_discounting'
+
+module Legion
+  module Extensions
+    module TemporalDiscounting
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/temporal_discounting/client'
+
+RSpec.describe Legion::Extensions::TemporalDiscounting::Client do
+  subject(:client) { described_class.new }
+
+  it 'includes the TemporalDiscounting runner' do
+    expect(client).to respond_to(:create_temporal_reward)
+    expect(client).to respond_to(:compare_temporal_rewards)
+    expect(client).to respond_to(:temporal_patience_report)
+  end
+
+  it 'exposes the discounting engine' do
+    expect(client.engine).to be_a(Legion::Extensions::TemporalDiscounting::Helpers::DiscountingEngine)
+  end
+
+  it 'shares the same engine instance across calls' do
+    expect(client.engine).to equal(client.engine)
+  end
+
+  it 'creates different engine instances per client' do
+    c2 = described_class.new
+    expect(client.engine).not_to equal(c2.engine)
+  end
+end

data/spec/legion/extensions/temporal_discounting/helpers/discounting_engine_spec.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/temporal_discounting/client'
+
+RSpec.describe Legion::Extensions::TemporalDiscounting::Helpers::DiscountingEngine do
+  subject(:engine) { described_class.new }
+
+  describe '#create_reward' do
+    it 'creates and stores a reward' do
+      reward = engine.create_reward(label: 'bonus', amount: 0.7, delay: 3.0)
+      expect(reward).to be_a(Legion::Extensions::TemporalDiscounting::Helpers::Reward)
+      expect(engine.rewards).to have_key(reward.id)
+    end
+
+    it 'uses domain rate when no discount_rate given' do
+      engine.set_domain_rate(domain: :financial, rate: 0.25)
+      reward = engine.create_reward(label: 'fin', amount: 0.5, delay: 2.0, domain: :financial)
+      expect(reward.discount_rate).to eq(0.25)
+    end
+
+    it 'uses explicit discount_rate over domain rate' do
+      engine.set_domain_rate(domain: :financial, rate: 0.25)
+      reward = engine.create_reward(label: 'fin', amount: 0.5, delay: 2.0, domain: :financial, discount_rate: 0.05)
+      expect(reward.discount_rate).to eq(0.05)
+    end
+  end
+
+  describe '#compare_rewards' do
+    it 'returns preferred reward and delta' do
+      a = engine.create_reward(label: 'a', amount: 0.9, delay: 1.0, discount_rate: 0.1)
+      b = engine.create_reward(label: 'b', amount: 0.3, delay: 1.0, discount_rate: 0.1)
+      result = engine.compare_rewards(reward_a_id: a.id, reward_b_id: b.id)
+      expect(result[:preferred]).to eq(a.id)
+      expect(result[:delta]).to be > 0
+    end
+
+    it 'returns tied when values are equal' do
+      a = engine.create_reward(label: 'a', amount: 0.5, delay: 0.0, discount_rate: 0.1)
+      b = engine.create_reward(label: 'b', amount: 0.5, delay: 0.0, discount_rate: 0.1)
+      result = engine.compare_rewards(reward_a_id: a.id, reward_b_id: b.id)
+      expect(result[:preferred]).to eq(:tied)
+    end
+
+    it 'returns error for missing reward' do
+      a = engine.create_reward(label: 'a', amount: 0.5, delay: 1.0)
+      result = engine.compare_rewards(reward_a_id: a.id, reward_b_id: 'missing')
+      expect(result[:error]).to eq(:not_found)
+    end
+  end
+
+  describe '#worth_waiting_for?' do
+    it 'returns true when subjective_value >= threshold' do
+      r = engine.create_reward(label: 'x', amount: 0.9, delay: 0.5, discount_rate: 0.1)
+      result = engine.worth_waiting_for?(reward_id: r.id, threshold: 0.3)
+      expect(result[:worth_waiting]).to be true
+    end
+
+    it 'returns error for unknown reward' do
+      result = engine.worth_waiting_for?(reward_id: 'nope')
+      expect(result[:error]).to eq(:not_found)
+    end
+  end
+
+  describe '#set_domain_rate / #get_domain_rate' do
+    it 'stores and retrieves domain rate' do
+      engine.set_domain_rate(domain: :health, rate: 0.3)
+      expect(engine.get_domain_rate(:health)).to eq(0.3)
+    end
+
+    it 'returns DEFAULT_DISCOUNT_RATE for unknown domain' do
+      expect(engine.get_domain_rate(:unknown)).to eq(Legion::Extensions::TemporalDiscounting::Helpers::DEFAULT_DISCOUNT_RATE)
+    end
+
+    it 'clamps domain rate to MAX' do
+      engine.set_domain_rate(domain: :test, rate: 5.0)
+      expect(engine.get_domain_rate(:test)).to eq(Legion::Extensions::TemporalDiscounting::Helpers::MAX_DISCOUNT_RATE)
+    end
+  end
+
+  describe '#immediate_vs_delayed' do
+    it 'prefers immediate when immediate_amount > delayed discounted value' do
+      result = engine.immediate_vs_delayed(immediate_amount: 0.8, delayed_amount: 0.9, delay: 100.0)
+      expect(result[:preferred]).to eq(:immediate)
+    end
+
+    it 'prefers delayed when delayed discounted value > immediate' do
+      result = engine.immediate_vs_delayed(immediate_amount: 0.1, delayed_amount: 0.9, delay: 0.1)
+      expect(result[:preferred]).to eq(:delayed)
+    end
+
+    it 'uses domain rate in computation' do
+      engine.set_domain_rate(domain: :social, rate: 0.5)
+      result = engine.immediate_vs_delayed(immediate_amount: 0.4, delayed_amount: 0.9, delay: 2.0, domain: :social)
+      expect(result[:discount_rate]).to eq(0.5)
+    end
+
+    it 'returns delta between values' do
+      result = engine.immediate_vs_delayed(immediate_amount: 0.5, delayed_amount: 0.8, delay: 5.0)
+      expect(result[:delta]).to be >= 0
+    end
+  end
+
+  describe '#optimal_delay' do
+    it 'computes maximum delay before value drops below threshold' do
+      r = engine.create_reward(label: 'x', amount: 0.8, delay: 1.0, discount_rate: 0.1)
+      result = engine.optimal_delay(reward_id: r.id, min_value: 0.4)
+      # D = (A/V - 1) / k = (0.8/0.4 - 1) / 0.1 = 1/0.1 = 10
+      expect(result[:max_delay]).to be_within(1e-9).of(10.0)
+    end
+
+    it 'returns error when reward not found' do
+      result = engine.optimal_delay(reward_id: 'none')
+      expect(result[:error]).to eq(:not_found)
+    end
+
+    it 'returns error when min_value > amount' do
+      r = engine.create_reward(label: 'x', amount: 0.3, delay: 1.0)
+      result = engine.optimal_delay(reward_id: r.id, min_value: 0.5)
+      expect(result[:error]).to eq(:threshold_too_high)
+    end
+  end
+
+  describe '#patience_report' do
+    it 'returns empty report when no rewards' do
+      report = engine.patience_report
+      expect(report[:total_rewards]).to eq(0)
+      expect(report[:avg_discount_rate]).to eq(0.0)
+    end
+
+    it 'computes avg discount rate and subjective value' do
+      engine.create_reward(label: 'a', amount: 0.8, delay: 2.0, discount_rate: 0.1)
+      engine.create_reward(label: 'b', amount: 0.6, delay: 2.0, discount_rate: 0.3)
+      report = engine.patience_report
+      expect(report[:total_rewards]).to eq(2)
+      expect(report[:avg_discount_rate]).to be_within(1e-9).of(0.2)
+      expect(report[:avg_subjective_value]).to be > 0
+    end
+
+    it 'includes impulsivity distribution' do
+      engine.create_reward(label: 'a', amount: 0.8, delay: 1.0, discount_rate: 0.02)
+      engine.create_reward(label: 'b', amount: 0.8, delay: 1.0, discount_rate: 0.5)
+      report = engine.patience_report
+      expect(report[:impulsivity_distribution]).to have_key(:patient)
+      expect(report[:impulsivity_distribution]).to have_key(:very_impulsive)
+    end
+  end
+
+  describe '#rewards_by_domain' do
+    it 'filters rewards by domain' do
+      engine.create_reward(label: 'fin', amount: 0.5, delay: 1.0, domain: :financial)
+      engine.create_reward(label: 'hth', amount: 0.5, delay: 1.0, domain: :health)
+      engine.create_reward(label: 'fin2', amount: 0.7, delay: 1.0, domain: :financial)
+      result = engine.rewards_by_domain(domain: :financial)
+      expect(result.size).to eq(2)
+      expect(result.all? { |r| r.domain == :financial }).to be true
+    end
+  end
+
+  describe '#most_valuable' do
+    it 'returns top rewards by subjective_value' do
+      engine.create_reward(label: 'low', amount: 0.1, delay: 100.0, discount_rate: 1.0)
+      engine.create_reward(label: 'high', amount: 0.9, delay: 0.1, discount_rate: 0.01)
+      result = engine.most_valuable(limit: 1)
+      expect(result.first.label).to eq('high')
+    end
+
+    it 'limits the result set' do
+      5.times { |i| engine.create_reward(label: "r#{i}", amount: 0.5, delay: i.to_f + 1.0) }
+      expect(engine.most_valuable(limit: 3).size).to eq(3)
+    end
+  end
+
+  describe '#prune_expired' do
+    it 'removes rewards below min_value threshold' do
+      engine.create_reward(label: 'dead', amount: 0.05, delay: 1000.0, discount_rate: 1.0)
+      engine.create_reward(label: 'alive', amount: 0.9, delay: 0.1, discount_rate: 0.01)
+      result = engine.prune_expired(min_value: 0.05)
+      expect(result[:pruned]).to be >= 1
+      expect(result[:remaining]).to be >= 1
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns engine stats hash' do
+      engine.create_reward(label: 'x', amount: 0.5, delay: 1.0)
+      h = engine.to_h
+      expect(h[:total_rewards]).to eq(1)
+      expect(h[:domain_rates]).to be_a(Hash)
+      expect(h[:patience]).to be_a(Hash)
+    end
+  end
+end

data/spec/legion/extensions/temporal_discounting/helpers/reward_spec.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/temporal_discounting/client'
+
+RSpec.describe Legion::Extensions::TemporalDiscounting::Helpers::Reward do
+  subject(:reward) do
+    described_class.new(label: 'test', amount: 0.8, delay: 5.0, domain: :financial, discount_rate: 0.1)
+  end
+
+  describe '#initialize' do
+    it 'assigns a UUID id' do
+      expect(reward.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores the label' do
+      expect(reward.label).to eq('test')
+    end
+
+    it 'clamps amount to [0, 1]' do
+      r = described_class.new(label: 'x', amount: 1.5, delay: 1.0)
+      expect(r.amount).to eq(1.0)
+    end
+
+    it 'clamps amount below 0 to 0' do
+      r = described_class.new(label: 'x', amount: -0.5, delay: 1.0)
+      expect(r.amount).to eq(0.0)
+    end
+
+    it 'clamps discount_rate to MIN' do
+      r = described_class.new(label: 'x', amount: 0.5, delay: 1.0, discount_rate: 0.0)
+      expect(r.discount_rate).to eq(Legion::Extensions::TemporalDiscounting::Helpers::MIN_DISCOUNT_RATE)
+    end
+
+    it 'clamps discount_rate to MAX' do
+      r = described_class.new(label: 'x', amount: 0.5, delay: 1.0, discount_rate: 2.0)
+      expect(r.discount_rate).to eq(Legion::Extensions::TemporalDiscounting::Helpers::MAX_DISCOUNT_RATE)
+    end
+
+    it 'records created_at' do
+      expect(reward.created_at).to be_a(Time)
+    end
+  end
+
+  describe '#subjective_value' do
+    it 'computes hyperbolic discount formula V = A / (1 + k*D)' do
+      # A=0.8, k=0.1, D=5.0 => 0.8 / (1 + 0.5) = 0.8 / 1.5
+      expected = 0.8 / (1.0 + (0.1 * 5.0))
+      expect(reward.subjective_value).to be_within(1e-9).of(expected)
+    end
+
+    it 'equals amount when delay is 0' do
+      r = described_class.new(label: 'x', amount: 0.6, delay: 0.0)
+      expect(r.subjective_value).to be_within(1e-9).of(0.6)
+    end
+
+    it 'approaches zero as delay grows large' do
+      r = described_class.new(label: 'x', amount: 1.0, delay: 10_000.0, discount_rate: 1.0)
+      expect(r.subjective_value).to be < 0.001
+    end
+
+    it 'is lower with higher discount rate' do
+      r_low  = described_class.new(label: 'x', amount: 0.9, delay: 10.0, discount_rate: 0.05)
+      r_high = described_class.new(label: 'x', amount: 0.9, delay: 10.0, discount_rate: 0.5)
+      expect(r_low.subjective_value).to be > r_high.subjective_value
+    end
+  end
+
+  describe '#value_ratio' do
+    it 'returns subjective_value / amount' do
+      expected = reward.subjective_value / reward.amount
+      expect(reward.value_ratio).to be_within(1e-9).of(expected)
+    end
+
+    it 'returns 0.0 when amount is 0' do
+      r = described_class.new(label: 'x', amount: 0.0, delay: 1.0)
+      expect(r.value_ratio).to eq(0.0)
+    end
+
+    it 'is 1.0 when delay is 0' do
+      r = described_class.new(label: 'x', amount: 0.7, delay: 0.0)
+      expect(r.value_ratio).to be_within(1e-9).of(1.0)
+    end
+  end
+
+  describe '#value_label' do
+    it 'returns :full_value when ratio >= 0.8' do
+      r = described_class.new(label: 'x', amount: 0.9, delay: 0.0)
+      expect(r.value_label).to eq(:full_value)
+    end
+
+    it 'returns :negligible when ratio < 0.2' do
+      r = described_class.new(label: 'x', amount: 0.5, delay: 100.0, discount_rate: 1.0)
+      expect(r.value_label).to eq(:negligible)
+    end
+
+    it 'returns :moderate_value for mid-range ratio' do
+      # A=0.5, k=0.1, D=10 => sv = 0.5/2 = 0.25, ratio = 0.5 => moderate_value
+      r = described_class.new(label: 'x', amount: 0.5, delay: 10.0, discount_rate: 0.1)
+      ratio = r.value_ratio
+      expect(ratio).to be_between(0.4, 0.6)
+      expect(r.value_label).to eq(:moderate_value)
+    end
+  end
+
+  describe '#impulsivity_label' do
+    it 'returns :patient for k < 0.05' do
+      r = described_class.new(label: 'x', amount: 0.5, delay: 1.0, discount_rate: 0.02)
+      expect(r.impulsivity_label).to eq(:patient)
+    end
+
+    it 'returns :moderate for k in [0.05, 0.15)' do
+      r = described_class.new(label: 'x', amount: 0.5, delay: 1.0, discount_rate: 0.1)
+      expect(r.impulsivity_label).to eq(:moderate)
+    end
+
+    it 'returns :impulsive for k in [0.15, 0.3)' do
+      r = described_class.new(label: 'x', amount: 0.5, delay: 1.0, discount_rate: 0.2)
+      expect(r.impulsivity_label).to eq(:impulsive)
+    end
+
+    it 'returns :very_impulsive for k in [0.3, 0.6)' do
+      r = described_class.new(label: 'x', amount: 0.5, delay: 1.0, discount_rate: 0.4)
+      expect(r.impulsivity_label).to eq(:very_impulsive)
+    end
+
+    it 'returns :extreme for k in [0.6, 1.0]' do
+      r = described_class.new(label: 'x', amount: 0.5, delay: 1.0, discount_rate: 0.8)
+      expect(r.impulsivity_label).to eq(:extreme)
+    end
+  end
+
+  describe '#worth_waiting?' do
+    it 'returns true when subjective_value >= default threshold 0.3' do
+      r = described_class.new(label: 'x', amount: 0.9, delay: 0.5, discount_rate: 0.1)
+      expect(r.worth_waiting?).to be true
+    end
+
+    it 'returns false when subjective_value < threshold' do
+      r = described_class.new(label: 'x', amount: 0.1, delay: 100.0, discount_rate: 1.0)
+      expect(r.worth_waiting?).to be false
+    end
+
+    it 'accepts custom threshold' do
+      r = described_class.new(label: 'x', amount: 0.8, delay: 2.0, discount_rate: 0.1)
+      sv = r.subjective_value
+      expect(r.worth_waiting?(threshold: sv - 0.01)).to be true
+      expect(r.worth_waiting?(threshold: sv + 0.01)).to be false
+    end
+  end
+
+  describe '#adjust_delay!' do
+    it 'updates delay and changes subjective_value' do
+      original_sv = reward.subjective_value
+      reward.adjust_delay!(new_delay: 50.0)
+      expect(reward.delay).to eq(50.0)
+      expect(reward.subjective_value).to be < original_sv
+    end
+  end
+
+  describe '#adjust_discount_rate!' do
+    it 'updates discount_rate clamped to [MIN, MAX]' do
+      reward.adjust_discount_rate!(new_rate: 0.5)
+      expect(reward.discount_rate).to eq(0.5)
+    end
+
+    it 'clamps below MIN_DISCOUNT_RATE' do
+      reward.adjust_discount_rate!(new_rate: 0.0)
+      expect(reward.discount_rate).to eq(Legion::Extensions::TemporalDiscounting::Helpers::MIN_DISCOUNT_RATE)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a complete hash' do
+      h = reward.to_h
+      expect(h[:id]).to eq(reward.id)
+      expect(h[:label]).to eq('test')
+      expect(h[:amount]).to eq(0.8)
+      expect(h[:delay]).to eq(5.0)
+      expect(h[:domain]).to eq(:financial)
+      expect(h[:discount_rate]).to eq(0.1)
+      expect(h[:subjective_value]).to be_a(Float)
+      expect(h[:value_ratio]).to be_a(Float)
+      expect(h[:value_label]).to be_a(Symbol)
+      expect(h[:impulsivity_label]).to be_a(Symbol)
+      expect(h[:worth_waiting]).to be(true).or be(false)
+      expect(h[:created_at]).to be_a(Time)
+    end
+  end
+end

data/spec/legion/extensions/temporal_discounting/runners/temporal_discounting_spec.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/temporal_discounting/client'
+
+RSpec.describe Legion::Extensions::TemporalDiscounting::Runners::TemporalDiscounting do
+  let(:client) { Legion::Extensions::TemporalDiscounting::Client.new }
+
+  describe '#create_temporal_reward' do
+    it 'creates a reward and returns success' do
+      result = client.create_temporal_reward(label: 'test', amount: 0.7, delay: 5.0)
+      expect(result[:success]).to be true
+      expect(result[:reward][:id]).to match(/\A[0-9a-f-]{36}\z/)
+      expect(result[:reward][:label]).to eq('test')
+    end
+
+    it 'stores the reward in the engine' do
+      result = client.create_temporal_reward(label: 'x', amount: 0.5, delay: 2.0)
+      id = result[:reward][:id]
+      expect(client.engine.rewards).to have_key(id)
+    end
+
+    it 'passes domain and discount_rate through' do
+      result = client.create_temporal_reward(
+        label: 'fin', amount: 0.8, delay: 10.0, domain: :financial, discount_rate: 0.25
+      )
+      expect(result[:reward][:domain]).to eq(:financial)
+      expect(result[:reward][:discount_rate]).to eq(0.25)
+    end
+  end
+
+  describe '#compare_temporal_rewards' do
+    it 'compares two rewards' do
+      a = client.create_temporal_reward(label: 'a', amount: 0.9, delay: 1.0, discount_rate: 0.1)
+      b = client.create_temporal_reward(label: 'b', amount: 0.2, delay: 1.0, discount_rate: 0.1)
+      result = client.compare_temporal_rewards(reward_a_id: a[:reward][:id], reward_b_id: b[:reward][:id])
+      expect(result[:success]).to be true
+      expect(result[:preferred]).to eq(a[:reward][:id])
+    end
+
+    it 'returns not_found error for missing reward' do
+      r = client.create_temporal_reward(label: 'x', amount: 0.5, delay: 1.0)
+      result = client.compare_temporal_rewards(reward_a_id: r[:reward][:id], reward_b_id: 'missing')
+      expect(result[:error]).to eq(:not_found)
+    end
+  end
+
+  describe '#check_worth_waiting' do
+    it 'returns worth_waiting true for high-value reward' do
+      r = client.create_temporal_reward(label: 'x', amount: 0.9, delay: 0.5, discount_rate: 0.1)
+      result = client.check_worth_waiting(reward_id: r[:reward][:id])
+      expect(result[:success]).to be true
+      expect(result[:worth_waiting]).to be true
+    end
+
+    it 'returns not_found error for missing id' do
+      result = client.check_worth_waiting(reward_id: 'missing')
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq(:not_found)
+    end
+  end
+
+  describe '#immediate_vs_delayed_comparison' do
+    it 'returns preferred option' do
+      result = client.immediate_vs_delayed_comparison(
+        immediate_amount: 0.8, delayed_amount: 0.9, delay: 100.0
+      )
+      expect(result[:success]).to be true
+      expect(result[:preferred]).to be_a(Symbol)
+    end
+
+    it 'includes discount_rate in result' do
+      result = client.immediate_vs_delayed_comparison(
+        immediate_amount: 0.3, delayed_amount: 0.9, delay: 5.0
+      )
+      expect(result[:discount_rate]).to be_a(Float)
+    end
+  end
+
+  describe '#compute_optimal_delay' do
+    it 'returns max_delay for a given min_value' do
+      r = client.create_temporal_reward(label: 'x', amount: 0.8, delay: 1.0, discount_rate: 0.1)
+      result = client.compute_optimal_delay(reward_id: r[:reward][:id], min_value: 0.4)
+      expect(result[:success]).to be true
+      expect(result[:max_delay]).to be_within(1e-9).of(10.0)
+    end
+
+    it 'returns not_found for missing reward' do
+      result = client.compute_optimal_delay(reward_id: 'none')
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq(:not_found)
+    end
+  end
+
+  describe '#temporal_patience_report' do
+    it 'returns report with success' do
+      client.create_temporal_reward(label: 'a', amount: 0.8, delay: 2.0, discount_rate: 0.1)
+      result = client.temporal_patience_report
+      expect(result[:success]).to be true
+      expect(result[:total_rewards]).to eq(1)
+      expect(result[:avg_discount_rate]).to be_a(Float)
+    end
+  end
+
+  describe '#set_domain_discount_rate' do
+    it 'sets and confirms domain rate' do
+      result = client.set_domain_discount_rate(domain: :health, rate: 0.2)
+      expect(result[:success]).to be true
+      expect(result[:domain]).to eq(:health)
+      expect(result[:rate]).to eq(0.2)
+    end
+  end
+
+  describe '#most_valuable_rewards' do
+    it 'returns top rewards by subjective_value' do
+      client.create_temporal_reward(label: 'low', amount: 0.1, delay: 100.0, discount_rate: 1.0)
+      client.create_temporal_reward(label: 'high', amount: 0.9, delay: 0.0, discount_rate: 0.1)
+      result = client.most_valuable_rewards(limit: 1)
+      expect(result[:success]).to be true
+      expect(result[:rewards].first[:label]).to eq('high')
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#update_temporal_discounting' do
+    it 'prunes low-value rewards and returns stats' do
+      client.create_temporal_reward(label: 'dead', amount: 0.02, delay: 1000.0, discount_rate: 1.0)
+      client.create_temporal_reward(label: 'alive', amount: 0.9, delay: 0.1, discount_rate: 0.01)
+      result = client.update_temporal_discounting(min_value: 0.05)
+      expect(result[:success]).to be true
+      expect(result[:pruned]).to be >= 1
+      expect(result[:stats]).to be_a(Hash)
+    end
+  end
+
+  describe '#temporal_discounting_stats' do
+    it 'returns engine stats' do
+      client.create_temporal_reward(label: 'x', amount: 0.5, delay: 1.0)
+      result = client.temporal_discounting_stats
+      expect(result[:success]).to be true
+      expect(result[:total_rewards]).to eq(1)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,23 @@
+# 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/temporal_discounting'
+
+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,75 @@
+--- !ruby/object:Gem::Specification
+name: lex-temporal-discounting
+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: Hyperbolic temporal discounting model for brain-modeled agentic AI planning
+  and impulse control
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-temporal-discounting.gemspec
+- lib/legion/extensions/temporal_discounting.rb
+- lib/legion/extensions/temporal_discounting/client.rb
+- lib/legion/extensions/temporal_discounting/helpers/constants.rb
+- lib/legion/extensions/temporal_discounting/helpers/discounting_engine.rb
+- lib/legion/extensions/temporal_discounting/helpers/reward.rb
+- lib/legion/extensions/temporal_discounting/runners/temporal_discounting.rb
+- lib/legion/extensions/temporal_discounting/version.rb
+- spec/legion/extensions/temporal_discounting/client_spec.rb
+- spec/legion/extensions/temporal_discounting/helpers/discounting_engine_spec.rb
+- spec/legion/extensions/temporal_discounting/helpers/reward_spec.rb
+- spec/legion/extensions/temporal_discounting/runners/temporal_discounting_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-temporal-discounting
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-temporal-discounting
+  source_code_uri: https://github.com/LegionIO/lex-temporal-discounting
+  documentation_uri: https://github.com/LegionIO/lex-temporal-discounting
+  changelog_uri: https://github.com/LegionIO/lex-temporal-discounting
+  bug_tracker_uri: https://github.com/LegionIO/lex-temporal-discounting/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 Temporal Discounting
+test_files: []