lex-prospective-memory 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6f9b96274e56e32c5e49088b65443551c071b613f3b299535d4456125ea924d9
+  data.tar.gz: 41224c4bc01e0b66da4d25ba71c3451150002099fe94ae4572d1855561c98d0d
+SHA512:
+  metadata.gz: 46f6902aeb852cf1733825242cd35347e2e5dcc2e8febdc83d123702171648a3b6474070fa755af91fc39be2f9f84aa7b301d6197e266b8d6450c095425d1ef1
+  data.tar.gz: 4fe8ce5afa4afec96fe2aab1475f8b3b3bd69c79d54b62f09f2d949ab2903555600a9a604cf016c6b01ec2c5e0cdd2b3c819259f838db66f0a2130cf5018e26a

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-prospective-memory.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/prospective_memory/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-prospective-memory'
+  spec.version       = Legion::Extensions::ProspectiveMemory::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Prospective Memory'
+  spec.description   = 'Prospective memory engine: manages intentions, monitors trigger conditions, and executes when conditions are met'
+  spec.homepage      = 'https://github.com/LegionIO/lex-prospective-memory'
+  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-prospective-memory'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-prospective-memory'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-prospective-memory'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-prospective-memory/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-prospective-memory.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/prospective_memory/helpers/constants'
+require 'legion/extensions/prospective_memory/helpers/intention'
+require 'legion/extensions/prospective_memory/helpers/prospective_engine'
+require 'legion/extensions/prospective_memory/runners/prospective_memory'
+
+module Legion
+  module Extensions
+    module ProspectiveMemory
+      class Client
+        include Runners::ProspectiveMemory
+
+        def initialize(**)
+          @prospective_engine = Helpers::ProspectiveEngine.new
+        end
+
+        private
+
+        attr_reader :prospective_engine
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module ProspectiveMemory
+      module Helpers
+        module Constants
+          MAX_INTENTIONS   = 300
+          DEFAULT_URGENCY  = 0.5
+          URGENCY_DECAY    = 0.01
+          URGENCY_BOOST    = 0.1
+          CHECK_INTERVAL   = 60
+
+          URGENCY_LABELS = {
+            (0.8..)     => :critical,
+            (0.6...0.8) => :high,
+            (0.4...0.6) => :moderate,
+            (0.2...0.4) => :low,
+            (..0.2)     => :deferred
+          }.freeze
+
+          STATUS_TYPES  = %i[pending monitoring triggered executed expired cancelled].freeze
+          TRIGGER_TYPES = %i[time_based event_based context_based activity_based].freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/prospective_memory/helpers/intention.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module ProspectiveMemory
+      module Helpers
+        class Intention
+          attr_reader :id, :description, :trigger_type, :trigger_condition,
+                      :domain, :created_at, :triggered_at, :executed_at, :expires_at, :status
+
+          attr_accessor :urgency
+
+          def initialize(description:, trigger_type:, trigger_condition:, urgency: Constants::DEFAULT_URGENCY,
+                         domain: nil, expires_at: nil)
+            @id                = SecureRandom.uuid
+            @description       = description
+            @trigger_type      = trigger_type
+            @trigger_condition = trigger_condition
+            @urgency           = urgency.clamp(0.0, 1.0)
+            @domain            = domain
+            @status            = :pending
+            @created_at        = Time.now.utc
+            @triggered_at      = nil
+            @executed_at       = nil
+            @expires_at        = expires_at
+          end
+
+          def monitor!
+            @status = :monitoring
+          end
+
+          def trigger!
+            @status       = :triggered
+            @triggered_at = Time.now.utc
+          end
+
+          def execute!
+            @status      = :executed
+            @executed_at = Time.now.utc
+          end
+
+          def expire!
+            @status = :expired
+          end
+
+          def cancel!
+            @status = :cancelled
+          end
+
+          def expired?
+            return false unless @expires_at
+
+            Time.now.utc > @expires_at
+          end
+
+          def boost_urgency!(amount: Constants::URGENCY_BOOST)
+            @urgency = (@urgency + amount).clamp(0.0, 1.0).round(10)
+          end
+
+          def decay_urgency!
+            @urgency = (@urgency - Constants::URGENCY_DECAY).clamp(0.0, 1.0).round(10)
+          end
+
+          def urgency_label
+            Constants::URGENCY_LABELS.find { |range, _label| range.cover?(@urgency) }&.last || :deferred
+          end
+
+          def to_h
+            {
+              id:                @id,
+              description:       @description,
+              trigger_type:      @trigger_type,
+              trigger_condition: @trigger_condition,
+              urgency:           @urgency,
+              urgency_label:     urgency_label,
+              status:            @status,
+              domain:            @domain,
+              created_at:        @created_at,
+              triggered_at:      @triggered_at,
+              executed_at:       @executed_at,
+              expires_at:        @expires_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/prospective_memory/helpers/prospective_engine.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module ProspectiveMemory
+      module Helpers
+        class ProspectiveEngine
+          attr_reader :intentions
+
+          def initialize
+            @intentions = {}
+          end
+
+          def create_intention(description:, trigger_type:, trigger_condition:,
+                               urgency: Constants::DEFAULT_URGENCY, domain: nil, expires_at: nil)
+            evict_oldest! if @intentions.size >= Constants::MAX_INTENTIONS
+
+            intention = Intention.new(
+              description:       description,
+              trigger_type:      trigger_type,
+              trigger_condition: trigger_condition,
+              urgency:           urgency,
+              domain:            domain,
+              expires_at:        expires_at
+            )
+            @intentions[intention.id] = intention
+            intention
+          end
+
+          def monitor_intention(intention_id:)
+            intention = fetch(intention_id)
+            return nil unless intention
+
+            intention.monitor!
+            intention
+          end
+
+          def trigger_intention(intention_id:)
+            intention = fetch(intention_id)
+            return nil unless intention
+
+            intention.trigger!
+            intention
+          end
+
+          def execute_intention(intention_id:)
+            intention = fetch(intention_id)
+            return nil unless intention
+
+            intention.execute!
+            intention
+          end
+
+          def cancel_intention(intention_id:)
+            intention = fetch(intention_id)
+            return nil unless intention
+
+            intention.cancel!
+            intention
+          end
+
+          def check_expirations
+            expired_count = 0
+            @intentions.each_value do |intention|
+              next unless %i[pending monitoring].include?(intention.status) && intention.expired?
+
+              intention.expire!
+              expired_count += 1
+            end
+            expired_count
+          end
+
+          def pending_intentions
+            by_status(:pending)
+          end
+
+          def monitoring_intentions
+            by_status(:monitoring)
+          end
+
+          def triggered_intentions
+            by_status(:triggered)
+          end
+
+          def by_domain(domain:)
+            @intentions.values.select { |i| i.domain == domain }
+          end
+
+          def by_urgency(min_urgency: 0.5)
+            @intentions.values.select { |i| i.urgency >= min_urgency }
+          end
+
+          def most_urgent(limit: 5)
+            active = @intentions.values.reject { |i| %i[executed expired cancelled].include?(i.status) }
+            active.sort_by { |i| -i.urgency }.first(limit)
+          end
+
+          def decay_all_urgency
+            @intentions.each_value do |intention|
+              next unless %i[pending monitoring].include?(intention.status)
+
+              intention.decay_urgency!
+            end
+          end
+
+          def execution_rate
+            terminal = @intentions.values.select { |i| %i[executed expired cancelled].include?(i.status) }
+            return 0.0 if terminal.empty?
+
+            executed = terminal.count { |i| i.status == :executed }
+            (executed.to_f / terminal.size).round(10)
+          end
+
+          def intention_report
+            all    = @intentions.values
+            counts = Constants::STATUS_TYPES.to_h do |s|
+              [s, all.count { |i| i.status == s }]
+            end
+            {
+              total:          all.size,
+              by_status:      counts,
+              execution_rate: execution_rate,
+              most_urgent:    most_urgent(limit: 5).map(&:to_h)
+            }
+          end
+
+          def to_h
+            {
+              intentions:      @intentions.transform_values(&:to_h),
+              intention_count: @intentions.size,
+              execution_rate:  execution_rate
+            }
+          end
+
+          private
+
+          def fetch(intention_id)
+            @intentions[intention_id]
+          end
+
+          def by_status(status)
+            @intentions.values.select { |i| i.status == status }
+          end
+
+          def evict_oldest!
+            oldest_id = @intentions.min_by { |_id, i| i.created_at }&.first
+            @intentions.delete(oldest_id) if oldest_id
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module ProspectiveMemory
+      module Runners
+        module ProspectiveMemory
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def create_intention(description:, trigger_type:, trigger_condition:,
+                               urgency: Helpers::Constants::DEFAULT_URGENCY,
+                               domain: nil, expires_at: nil, **)
+            unless Helpers::Constants::TRIGGER_TYPES.include?(trigger_type)
+              return { error: :invalid_trigger_type, valid_types: Helpers::Constants::TRIGGER_TYPES }
+            end
+
+            intention = prospective_engine.create_intention(
+              description:       description,
+              trigger_type:      trigger_type,
+              trigger_condition: trigger_condition,
+              urgency:           urgency,
+              domain:            domain,
+              expires_at:        expires_at
+            )
+
+            Legion::Logging.debug "[prospective_memory] created intention id=#{intention.id[0..7]} " \
+                                  "type=#{trigger_type} urgency=#{intention.urgency.round(2)}"
+
+            { created: true, intention: intention.to_h }
+          end
+
+          def monitor_intention(intention_id:, **)
+            intention = prospective_engine.monitor_intention(intention_id: intention_id)
+            if intention
+              Legion::Logging.debug "[prospective_memory] monitoring intention id=#{intention_id[0..7]}"
+              { updated: true, intention: intention.to_h }
+            else
+              { updated: false, reason: :not_found }
+            end
+          end
+
+          def trigger_intention(intention_id:, **)
+            intention = prospective_engine.trigger_intention(intention_id: intention_id)
+            if intention
+              Legion::Logging.info "[prospective_memory] triggered intention id=#{intention_id[0..7]}"
+              { updated: true, intention: intention.to_h }
+            else
+              { updated: false, reason: :not_found }
+            end
+          end
+
+          def execute_intention(intention_id:, **)
+            intention = prospective_engine.execute_intention(intention_id: intention_id)
+            if intention
+              Legion::Logging.info "[prospective_memory] executed intention id=#{intention_id[0..7]}"
+              { updated: true, intention: intention.to_h }
+            else
+              { updated: false, reason: :not_found }
+            end
+          end
+
+          def cancel_intention(intention_id:, **)
+            intention = prospective_engine.cancel_intention(intention_id: intention_id)
+            if intention
+              Legion::Logging.debug "[prospective_memory] cancelled intention id=#{intention_id[0..7]}"
+              { updated: true, intention: intention.to_h }
+            else
+              { updated: false, reason: :not_found }
+            end
+          end
+
+          def check_expirations(**)
+            expired_count = prospective_engine.check_expirations
+            Legion::Logging.debug "[prospective_memory] expiration check expired=#{expired_count}"
+            { expired_count: expired_count }
+          end
+
+          def pending_intentions(**)
+            intentions = prospective_engine.pending_intentions
+            Legion::Logging.debug "[prospective_memory] pending count=#{intentions.size}"
+            { intentions: intentions.map(&:to_h), count: intentions.size }
+          end
+
+          def monitoring_intentions(**)
+            intentions = prospective_engine.monitoring_intentions
+            Legion::Logging.debug "[prospective_memory] monitoring count=#{intentions.size}"
+            { intentions: intentions.map(&:to_h), count: intentions.size }
+          end
+
+          def triggered_intentions(**)
+            intentions = prospective_engine.triggered_intentions
+            Legion::Logging.debug "[prospective_memory] triggered count=#{intentions.size}"
+            { intentions: intentions.map(&:to_h), count: intentions.size }
+          end
+
+          def intentions_by_domain(domain:, **)
+            intentions = prospective_engine.by_domain(domain: domain)
+            Legion::Logging.debug "[prospective_memory] by_domain domain=#{domain} count=#{intentions.size}"
+            { intentions: intentions.map(&:to_h), count: intentions.size, domain: domain }
+          end
+
+          def intentions_by_urgency(min_urgency: 0.5, **)
+            intentions = prospective_engine.by_urgency(min_urgency: min_urgency)
+            Legion::Logging.debug "[prospective_memory] by_urgency min=#{min_urgency} count=#{intentions.size}"
+            { intentions: intentions.map(&:to_h), count: intentions.size }
+          end
+
+          def most_urgent_intentions(limit: 5, **)
+            intentions = prospective_engine.most_urgent(limit: limit)
+            Legion::Logging.debug "[prospective_memory] most_urgent limit=#{limit} found=#{intentions.size}"
+            { intentions: intentions.map(&:to_h), count: intentions.size }
+          end
+
+          def decay_urgency(**)
+            prospective_engine.decay_all_urgency
+            Legion::Logging.debug '[prospective_memory] urgency decay cycle complete'
+            { decayed: true }
+          end
+
+          def execution_rate(**)
+            rate = prospective_engine.execution_rate
+            Legion::Logging.debug "[prospective_memory] execution_rate=#{rate.round(4)}"
+            { execution_rate: rate }
+          end
+
+          def intention_report(**)
+            report = prospective_engine.intention_report
+            Legion::Logging.debug "[prospective_memory] report total=#{report[:total]}"
+            report
+          end
+
+          private
+
+          def prospective_engine
+            @prospective_engine ||= Helpers::ProspectiveEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/prospective_memory.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/prospective_memory/version'
+require 'legion/extensions/prospective_memory/helpers/constants'
+require 'legion/extensions/prospective_memory/helpers/intention'
+require 'legion/extensions/prospective_memory/helpers/prospective_engine'
+require 'legion/extensions/prospective_memory/runners/prospective_memory'
+require 'legion/extensions/prospective_memory/client'
+
+module Legion
+  module Extensions
+    module ProspectiveMemory
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/prospective_memory/client'
+
+RSpec.describe Legion::Extensions::ProspectiveMemory::Client do
+  it 'responds to all runner methods' do
+    client = described_class.new
+    expect(client).to respond_to(:create_intention)
+    expect(client).to respond_to(:monitor_intention)
+    expect(client).to respond_to(:trigger_intention)
+    expect(client).to respond_to(:execute_intention)
+    expect(client).to respond_to(:cancel_intention)
+    expect(client).to respond_to(:check_expirations)
+    expect(client).to respond_to(:pending_intentions)
+    expect(client).to respond_to(:monitoring_intentions)
+    expect(client).to respond_to(:triggered_intentions)
+    expect(client).to respond_to(:intentions_by_domain)
+    expect(client).to respond_to(:intentions_by_urgency)
+    expect(client).to respond_to(:most_urgent_intentions)
+    expect(client).to respond_to(:decay_urgency)
+    expect(client).to respond_to(:execution_rate)
+    expect(client).to respond_to(:intention_report)
+  end
+end

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::ProspectiveMemory::Helpers::Constants do
+  describe 'MAX_INTENTIONS' do
+    it 'is 300' do
+      expect(described_class::MAX_INTENTIONS).to eq(300)
+    end
+  end
+
+  describe 'DEFAULT_URGENCY' do
+    it 'is 0.5' do
+      expect(described_class::DEFAULT_URGENCY).to eq(0.5)
+    end
+  end
+
+  describe 'URGENCY_DECAY' do
+    it 'is 0.01' do
+      expect(described_class::URGENCY_DECAY).to eq(0.01)
+    end
+  end
+
+  describe 'URGENCY_BOOST' do
+    it 'is 0.1' do
+      expect(described_class::URGENCY_BOOST).to eq(0.1)
+    end
+  end
+
+  describe 'CHECK_INTERVAL' do
+    it 'is 60' do
+      expect(described_class::CHECK_INTERVAL).to eq(60)
+    end
+  end
+
+  describe 'URGENCY_LABELS' do
+    it 'maps 0.9 to :critical' do
+      label = described_class::URGENCY_LABELS.find { |range, _| range.cover?(0.9) }&.last
+      expect(label).to eq(:critical)
+    end
+
+    it 'maps 0.7 to :high' do
+      label = described_class::URGENCY_LABELS.find { |range, _| range.cover?(0.7) }&.last
+      expect(label).to eq(:high)
+    end
+
+    it 'maps 0.5 to :moderate' do
+      label = described_class::URGENCY_LABELS.find { |range, _| range.cover?(0.5) }&.last
+      expect(label).to eq(:moderate)
+    end
+
+    it 'maps 0.3 to :low' do
+      label = described_class::URGENCY_LABELS.find { |range, _| range.cover?(0.3) }&.last
+      expect(label).to eq(:low)
+    end
+
+    it 'maps 0.1 to :deferred' do
+      label = described_class::URGENCY_LABELS.find { |range, _| range.cover?(0.1) }&.last
+      expect(label).to eq(:deferred)
+    end
+
+    it 'is frozen' do
+      expect(described_class::URGENCY_LABELS).to be_frozen
+    end
+  end
+
+  describe 'STATUS_TYPES' do
+    it 'includes all expected statuses' do
+      expect(described_class::STATUS_TYPES).to include(:pending, :monitoring, :triggered, :executed, :expired, :cancelled)
+    end
+
+    it 'is frozen' do
+      expect(described_class::STATUS_TYPES).to be_frozen
+    end
+  end
+
+  describe 'TRIGGER_TYPES' do
+    it 'includes all expected trigger types' do
+      expect(described_class::TRIGGER_TYPES).to include(:time_based, :event_based, :context_based, :activity_based)
+    end
+
+    it 'is frozen' do
+      expect(described_class::TRIGGER_TYPES).to be_frozen
+    end
+  end
+end