lex-mental-simulation 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 062aab32a8aca9c6d7c1bc81ee6384e7be863287e5527498f92b53ba13dcfa56
+  data.tar.gz: 2ca21d491f8b5e39119d673384cbeeb18224bb153196d21a809ca6fe5c58a793
+SHA512:
+  metadata.gz: 3dfeea7fa9ab1a3aadea8dc3e360b44425882140adae59105850133031e12647b8503278e4379b4d90e8f48b0fd3798fe2ff7abede739362060b1a5cff6205d0
+  data.tar.gz: '049a502d61a973870ae10a0a5cef15dd258ae9103cdfc05f620bb7e2f898f6d3666b38405cbd769a2c807146588498d26a7348f2de21f1fdee60ccdf9256f737'

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-mental-simulation.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/mental_simulation/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-mental-simulation'
+  spec.version       = Legion::Extensions::MentalSimulation::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Mental Simulation'
+  spec.description   = 'Forward mental simulation of action sequences — imagine a plan, predict step outcomes, evaluate before executing'
+  spec.homepage      = 'https://github.com/LegionIO/lex-mental-simulation'
+  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-mental-simulation'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-mental-simulation'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-mental-simulation'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-mental-simulation/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-mental-simulation.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

data/lib/legion/extensions/mental_simulation/helpers/client.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module MentalSimulation
+      class Client
+        include Runners::MentalSimulation
+
+        def initialize(**)
+          @engine = Helpers::SimulationEngine.new
+        end
+
+        private
+
+        attr_reader :engine
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module MentalSimulation
+      module Helpers
+        module Constants
+          SIMULATION_STATES = %i[pending running completed failed aborted].freeze
+          STEP_OUTCOMES     = %i[success partial_success failure unknown].freeze
+
+          CONFIDENCE_LABELS = {
+            (0.8..)     => :very_confident,
+            (0.6...0.8) => :confident,
+            (0.4...0.6) => :uncertain,
+            (0.2...0.4) => :doubtful,
+            (..0.2)     => :very_doubtful
+          }.freeze
+
+          RISK_LABELS = {
+            (0.8..)     => :critical,
+            (0.6...0.8) => :high,
+            (0.4...0.6) => :moderate,
+            (0.2...0.4) => :low,
+            (..0.2)     => :negligible
+          }.freeze
+
+          MAX_SIMULATIONS    = 100
+          MAX_STEPS_PER_SIM  = 50
+          MAX_HISTORY        = 500
+
+          DEFAULT_CONFIDENCE       = 0.5
+          CONFIDENCE_BOOST         = 0.1
+          CONFIDENCE_PENALTY       = 0.15
+          RISK_ACCUMULATION_RATE   = 0.1
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/mental_simulation/helpers/simulation.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module MentalSimulation
+      module Helpers
+        class Simulation
+          include Constants
+
+          attr_reader :id, :label, :domain, :steps, :state, :created_at, :completed_at
+
+          def initialize(label:, domain:)
+            @id           = SecureRandom.uuid
+            @label        = label
+            @domain       = domain.to_sym
+            @steps        = []
+            @state        = :pending
+            @created_at   = Time.now.utc
+            @completed_at = nil
+          end
+
+          def add_step(action:, predicted_outcome: :success, confidence: 0.5, risk: 0.1,
+                       preconditions: [], postconditions: [])
+            step = SimulationStep.new(
+              action:            action,
+              predicted_outcome: predicted_outcome,
+              confidence:        confidence,
+              risk:              risk,
+              preconditions:     preconditions,
+              postconditions:    postconditions
+            )
+            @steps << step
+            step
+          end
+
+          def run!
+            @state = :running
+            accumulated_risk = 0.0
+
+            @steps.each do |step|
+              accumulated_risk += step.risk * RISK_ACCUMULATION_RATE
+
+              next unless step.predicted_outcome == :failure && step.confidence > 0.7
+
+              @state = :aborted
+              return self
+            end
+
+            final_state = overall_confidence >= 0.5 && cumulative_risk < 0.6 ? :completed : :failed
+            @state        = final_state
+            @completed_at = Time.now.utc
+            self
+          end
+
+          def abort!
+            @state        = :aborted
+            @completed_at = Time.now.utc
+            self
+          end
+
+          def overall_confidence
+            return 0.0 if @steps.empty?
+
+            @steps.reduce(1.0) { |prod, step| prod * step.confidence }
+          end
+
+          def cumulative_risk
+            return 0.0 if @steps.empty?
+
+            1.0 - @steps.reduce(1.0) { |prod, step| prod * (1.0 - step.risk) }
+          end
+
+          def favorable?
+            @state == :completed && overall_confidence >= 0.5 && cumulative_risk < 0.6
+          end
+
+          def confidence_label
+            CONFIDENCE_LABELS.find { |range, _| range.cover?(overall_confidence) }&.last || :very_doubtful
+          end
+
+          def risk_label
+            RISK_LABELS.find { |range, _| range.cover?(cumulative_risk) }&.last || :negligible
+          end
+
+          def step_count
+            @steps.size
+          end
+
+          def to_h
+            {
+              id:                 @id,
+              label:              @label,
+              domain:             @domain,
+              state:              @state,
+              step_count:         step_count,
+              overall_confidence: overall_confidence,
+              cumulative_risk:    cumulative_risk,
+              confidence_label:   confidence_label,
+              risk_label:         risk_label,
+              favorable:          favorable?,
+              steps:              @steps.map(&:to_h),
+              created_at:         @created_at,
+              completed_at:       @completed_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/mental_simulation/helpers/simulation_engine.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module MentalSimulation
+      module Helpers
+        class SimulationEngine
+          include Constants
+
+          def initialize
+            @simulations = {}
+            @history     = []
+          end
+
+          def create_simulation(label:, domain:)
+            prune_simulations if @simulations.size >= MAX_SIMULATIONS
+            sim = Simulation.new(label: label, domain: domain)
+            @simulations[sim.id] = sim
+            sim
+          end
+
+          def add_simulation_step(simulation_id:, action:, predicted_outcome: :success,
+                                  confidence: 0.5, risk: 0.1, preconditions: [], postconditions: [])
+            sim = @simulations[simulation_id]
+            return { error: :simulation_not_found } unless sim
+
+            return { error: :max_steps_reached, max: MAX_STEPS_PER_SIM } if sim.step_count >= MAX_STEPS_PER_SIM
+
+            step = sim.add_step(
+              action:            action,
+              predicted_outcome: predicted_outcome,
+              confidence:        confidence,
+              risk:              risk,
+              preconditions:     preconditions,
+              postconditions:    postconditions
+            )
+            { added: true, step_id: step.id, step_count: sim.step_count }
+          end
+
+          def run_simulation(simulation_id:)
+            sim = @simulations[simulation_id]
+            return { error: :simulation_not_found } unless sim
+
+            sim.run!
+            archive_simulation(sim)
+
+            {
+              simulation_id:      sim.id,
+              state:              sim.state,
+              overall_confidence: sim.overall_confidence,
+              cumulative_risk:    sim.cumulative_risk,
+              confidence_label:   sim.confidence_label,
+              risk_label:         sim.risk_label,
+              favorable:          sim.favorable?,
+              step_count:         sim.step_count
+            }
+          end
+
+          def abort_simulation(simulation_id:)
+            sim = @simulations[simulation_id]
+            return { error: :simulation_not_found } unless sim
+
+            sim.abort!
+            { simulation_id: sim.id, state: sim.state, aborted: true }
+          end
+
+          def assess_simulation(simulation_id:)
+            sim = @simulations[simulation_id]
+            return { error: :simulation_not_found } unless sim
+
+            {
+              simulation_id:      sim.id,
+              label:              sim.label,
+              domain:             sim.domain,
+              state:              sim.state,
+              step_count:         sim.step_count,
+              overall_confidence: sim.overall_confidence,
+              cumulative_risk:    sim.cumulative_risk,
+              confidence_label:   sim.confidence_label,
+              risk_label:         sim.risk_label,
+              favorable:          sim.favorable?,
+              steps:              sim.steps.map(&:to_h)
+            }
+          end
+
+          def favorable_simulations
+            @simulations.values.select(&:favorable?)
+          end
+
+          def failed_simulations
+            @simulations.values.select { |s| s.state == :failed }
+          end
+
+          def simulations_by_domain(domain:)
+            sym = domain.to_sym
+            @simulations.values.select { |s| s.domain == sym }
+          end
+
+          def riskiest_simulations(limit: 5)
+            @simulations.values
+                        .sort_by { |s| -s.cumulative_risk }
+                        .first(limit)
+          end
+
+          def most_confident(limit: 5)
+            @simulations.values
+                        .sort_by { |s| -s.overall_confidence }
+                        .first(limit)
+          end
+
+          def to_h
+            {
+              total_simulations: @simulations.size,
+              history_size:      @history.size,
+              favorable_count:   favorable_simulations.size,
+              failed_count:      failed_simulations.size,
+              simulations:       @simulations.values.map(&:to_h)
+            }
+          end
+
+          private
+
+          def archive_simulation(sim)
+            @history << { simulation_id: sim.id, state: sim.state, archived_at: Time.now.utc }
+            @history.shift while @history.size > MAX_HISTORY
+          end
+
+          def prune_simulations
+            completed = @simulations.select { |_, s| %i[completed failed aborted].include?(s.state) }
+            oldest = completed.values.min_by(&:created_at)
+            @simulations.delete(oldest.id) if oldest
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/mental_simulation/helpers/simulation_step.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module MentalSimulation
+      module Helpers
+        class SimulationStep
+          attr_reader :id, :action, :predicted_outcome, :confidence, :risk,
+                      :preconditions, :postconditions, :created_at
+
+          def initialize(action:, predicted_outcome: :success, confidence: 0.5, risk: 0.1,
+                         preconditions: [], postconditions: [])
+            @id               = SecureRandom.uuid
+            @action           = action
+            @predicted_outcome = predicted_outcome
+            @confidence       = confidence.clamp(0.0, 1.0)
+            @risk             = risk.clamp(0.0, 1.0)
+            @preconditions    = Array(preconditions)
+            @postconditions   = Array(postconditions)
+            @created_at       = Time.now.utc
+          end
+
+          def favorable?
+            %i[success partial_success].include?(@predicted_outcome) && @confidence >= 0.5
+          end
+
+          def risky?
+            @risk >= 0.6
+          end
+
+          def to_h
+            {
+              id:                @id,
+              action:            @action,
+              predicted_outcome: @predicted_outcome,
+              confidence:        @confidence,
+              risk:              @risk,
+              preconditions:     @preconditions,
+              postconditions:    @postconditions,
+              created_at:        @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module MentalSimulation
+      module Runners
+        module MentalSimulation
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def create_mental_simulation(label:, domain:, **)
+            sim = engine.create_simulation(label: label, domain: domain)
+            Legion::Logging.debug "[mental_simulation] created simulation id=#{sim.id[0..7]} label=#{label} domain=#{domain}"
+            { simulation_id: sim.id, label: sim.label, domain: sim.domain, state: sim.state }
+          end
+
+          def add_simulation_step(simulation_id:, action:, predicted_outcome: :success,
+                                  confidence: 0.5, risk: 0.1, preconditions: [], postconditions: [], **)
+            result = engine.add_simulation_step(
+              simulation_id:     simulation_id,
+              action:            action,
+              predicted_outcome: predicted_outcome,
+              confidence:        confidence,
+              risk:              risk,
+              preconditions:     preconditions,
+              postconditions:    postconditions
+            )
+            Legion::Logging.debug "[mental_simulation] add_step sim=#{simulation_id[0..7]} action=#{action} result=#{result[:added]}"
+            result
+          end
+
+          def run_mental_simulation(simulation_id:, **)
+            result = engine.run_simulation(simulation_id: simulation_id)
+            if result[:error]
+              Legion::Logging.warn "[mental_simulation] run failed: #{result[:error]}"
+            else
+              Legion::Logging.info "[mental_simulation] ran sim=#{simulation_id[0..7]} " \
+                                   "state=#{result[:state]} favorable=#{result[:favorable]}"
+            end
+            result
+          end
+
+          def abort_mental_simulation(simulation_id:, **)
+            result = engine.abort_simulation(simulation_id: simulation_id)
+            Legion::Logging.info "[mental_simulation] aborted sim=#{simulation_id[0..7]}"
+            result
+          end
+
+          def assess_mental_simulation(simulation_id:, **)
+            result = engine.assess_simulation(simulation_id: simulation_id)
+            Legion::Logging.debug "[mental_simulation] assessed sim=#{simulation_id[0..7]} steps=#{result[:step_count]}"
+            result
+          end
+
+          def favorable_simulations_report(**)
+            sims = engine.favorable_simulations
+            Legion::Logging.debug "[mental_simulation] favorable count=#{sims.size}"
+            { simulations: sims.map(&:to_h), count: sims.size }
+          end
+
+          def failed_simulations_report(**)
+            sims = engine.failed_simulations
+            Legion::Logging.debug "[mental_simulation] failed count=#{sims.size}"
+            { simulations: sims.map(&:to_h), count: sims.size }
+          end
+
+          def riskiest_simulations_report(limit: 5, **)
+            sims = engine.riskiest_simulations(limit: limit)
+            Legion::Logging.debug "[mental_simulation] riskiest count=#{sims.size} limit=#{limit}"
+            { simulations: sims.map(&:to_h), count: sims.size }
+          end
+
+          def mental_simulation_stats(**)
+            stats = engine.to_h.except(:simulations)
+            Legion::Logging.debug "[mental_simulation] stats total=#{stats[:total_simulations]}"
+            stats
+          end
+
+          private
+
+          def engine
+            @engine ||= Helpers::SimulationEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/mental_simulation.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/mental_simulation/version'
+require 'legion/extensions/mental_simulation/helpers/constants'
+require 'legion/extensions/mental_simulation/helpers/simulation_step'
+require 'legion/extensions/mental_simulation/helpers/simulation'
+require 'legion/extensions/mental_simulation/helpers/simulation_engine'
+require 'legion/extensions/mental_simulation/runners/mental_simulation'
+require 'legion/extensions/mental_simulation/helpers/client'
+
+module Legion
+  module Extensions
+    module MentalSimulation
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::MentalSimulation::Helpers::Constants do
+  describe 'SIMULATION_STATES' do
+    it 'is frozen' do
+      expect(described_class::SIMULATION_STATES).to be_frozen
+    end
+
+    it 'contains expected states' do
+      expect(described_class::SIMULATION_STATES).to include(:pending, :running, :completed, :failed, :aborted)
+    end
+  end
+
+  describe 'STEP_OUTCOMES' do
+    it 'is frozen' do
+      expect(described_class::STEP_OUTCOMES).to be_frozen
+    end
+
+    it 'contains expected outcomes' do
+      expect(described_class::STEP_OUTCOMES).to include(:success, :partial_success, :failure, :unknown)
+    end
+  end
+
+  describe 'CONFIDENCE_LABELS' do
+    it 'labels 0.9 as very_confident' do
+      match = described_class::CONFIDENCE_LABELS.find { |r, _| r.cover?(0.9) }&.last
+      expect(match).to eq(:very_confident)
+    end
+
+    it 'labels 0.7 as confident' do
+      match = described_class::CONFIDENCE_LABELS.find { |r, _| r.cover?(0.7) }&.last
+      expect(match).to eq(:confident)
+    end
+
+    it 'labels 0.5 as uncertain' do
+      match = described_class::CONFIDENCE_LABELS.find { |r, _| r.cover?(0.5) }&.last
+      expect(match).to eq(:uncertain)
+    end
+
+    it 'labels 0.3 as doubtful' do
+      match = described_class::CONFIDENCE_LABELS.find { |r, _| r.cover?(0.3) }&.last
+      expect(match).to eq(:doubtful)
+    end
+
+    it 'labels 0.1 as very_doubtful' do
+      match = described_class::CONFIDENCE_LABELS.find { |r, _| r.cover?(0.1) }&.last
+      expect(match).to eq(:very_doubtful)
+    end
+  end
+
+  describe 'RISK_LABELS' do
+    it 'labels 0.9 as critical' do
+      match = described_class::RISK_LABELS.find { |r, _| r.cover?(0.9) }&.last
+      expect(match).to eq(:critical)
+    end
+
+    it 'labels 0.7 as high' do
+      match = described_class::RISK_LABELS.find { |r, _| r.cover?(0.7) }&.last
+      expect(match).to eq(:high)
+    end
+
+    it 'labels 0.5 as moderate' do
+      match = described_class::RISK_LABELS.find { |r, _| r.cover?(0.5) }&.last
+      expect(match).to eq(:moderate)
+    end
+
+    it 'labels 0.3 as low' do
+      match = described_class::RISK_LABELS.find { |r, _| r.cover?(0.3) }&.last
+      expect(match).to eq(:low)
+    end
+
+    it 'labels 0.1 as negligible' do
+      match = described_class::RISK_LABELS.find { |r, _| r.cover?(0.1) }&.last
+      expect(match).to eq(:negligible)
+    end
+  end
+
+  describe 'numeric constants' do
+    it 'MAX_SIMULATIONS is 100' do
+      expect(described_class::MAX_SIMULATIONS).to eq(100)
+    end
+
+    it 'MAX_STEPS_PER_SIM is 50' do
+      expect(described_class::MAX_STEPS_PER_SIM).to eq(50)
+    end
+
+    it 'MAX_HISTORY is 500' do
+      expect(described_class::MAX_HISTORY).to eq(500)
+    end
+
+    it 'DEFAULT_CONFIDENCE is 0.5' do
+      expect(described_class::DEFAULT_CONFIDENCE).to eq(0.5)
+    end
+
+    it 'CONFIDENCE_BOOST is 0.1' do
+      expect(described_class::CONFIDENCE_BOOST).to eq(0.1)
+    end
+
+    it 'CONFIDENCE_PENALTY is 0.15' do
+      expect(described_class::CONFIDENCE_PENALTY).to eq(0.15)
+    end
+
+    it 'RISK_ACCUMULATION_RATE is 0.1' do
+      expect(described_class::RISK_ACCUMULATION_RATE).to eq(0.1)
+    end
+  end
+end