lex-prospection 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: de2a689e0894969a5cfa8c7abff2cf2a95273b80886d0a77f52f1f7ef38cf408
+  data.tar.gz: 7d5dbf56573144226f438724b93a26f2c6ec030a893beb3b433554eb54578e6c
+SHA512:
+  metadata.gz: 63e196a84901637427facc533a3d468759c31d3c8e14e3c6b5304fe3263d418e1568bbffe918f4f5028a51ea10e26eebbe76fbfaa76fd714f33d9cb3aa33b67e
+  data.tar.gz: c1a256a883a33ad6af03ce4026c48a2d399ae1af57532318c02f2dd4a9afcc97017f4bb62f21eb1e56b3d1b7de3865f2939d0d411946f337405cf1feddaa48f7

data/README.md

@@ -0,0 +1,58 @@
+# lex-prospection
+
+Mental time travel and future scenario simulation for the LegionIO cognitive architecture. Imagines future events with emotional predictions and tracks forecast accuracy.
+
+## What It Does
+
+Simulates future scenarios with predicted emotional valence and arousal. Applies two cognitive bias corrections: impact bias correction (reduces overestimation of emotional intensity) and focalism discount (reduces confidence when multiple scenarios compete for attention in the same domain). When scenarios are resolved against actual outcomes, forecast accuracy is tracked per domain.
+
+## Usage
+
+```ruby
+client = Legion::Extensions::Prospection::Client.new
+
+# Imagine a future scenario
+scenario = client.imagine_future(
+  domain:            :deployment,
+  description:       'Deploy new service to production',
+  time_horizon:      7,       # days from now
+  predicted_valence: 0.6,     # expecting positive outcome
+  predicted_arousal: 0.7,     # anticipation is high
+  confidence:        0.7
+)
+# => { success: true, scenario_id: '...', label: :positive,
+#      corrected_valence: 0.36, corrected_arousal: 0.42,
+#      confidence: 0.7, confidence_label: :moderate }
+
+# See upcoming scenarios
+client.near_future_scenarios(days: 7)
+client.vivid_scenarios(count: 5)
+
+# Resolve after outcome observed
+client.resolve_future(
+  scenario_id:    scenario[:scenario_id],
+  actual_valence: 0.7,
+  actual_arousal: 0.4
+)
+# => { success: true, forecast_error: 0.17, actual_valence: 0.7, actual_arousal: 0.4 }
+
+# Check forecast accuracy for domain
+client.forecast_accuracy(domain: :deployment)
+# => { success: true, domain: :deployment, accuracy: 0.83 }
+
+# Periodic decay (vividness fades)
+client.update_prospection
+client.prospection_stats
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module Prospection
+      module Actor
+        class Decay < Legion::Extensions::Actors::Every
+          def runner_class
+            Legion::Extensions::Prospection::Runners::Prospection
+          end
+
+          def runner_function
+            'update_prospection'
+          end
+
+          def time
+            300
+          end
+
+          def run_now?
+            false
+          end
+
+          def use_runner?
+            false
+          end
+
+          def check_subtask?
+            false
+          end
+
+          def generate_task?
+            false
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/prospection/helpers/constants'
+require 'legion/extensions/prospection/helpers/scenario'
+require 'legion/extensions/prospection/helpers/prospection_engine'
+require 'legion/extensions/prospection/runners/prospection'
+
+module Legion
+  module Extensions
+    module Prospection
+      class Client
+        include Runners::Prospection
+
+        attr_reader :prospection_engine
+
+        def initialize(prospection_engine: nil, **)
+          @prospection_engine = prospection_engine || Helpers::ProspectionEngine.new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Prospection
+      module Helpers
+        module Constants
+          MAX_SCENARIOS              = 100
+          MAX_FORECASTS_PER_SCENARIO = 10
+          MAX_HISTORY                = 200
+          SCENARIO_DECAY             = 0.01
+          DEFAULT_CONFIDENCE         = 0.4
+          IMPACT_BIAS_CORRECTION     = 0.6
+          FOCALISM_DISCOUNT          = 0.15
+          TEMPORAL_DISCOUNT_RATE     = 0.05
+          MAX_TIME_HORIZON           = 365
+          VIVIDNESS_ALPHA            = 0.1
+          DEFAULT_VIVIDNESS          = 0.5
+
+          VALENCE_LABELS = {
+            (0.6..)      => :positive,
+            (0.2...0.6)  => :neutral,
+            (-0.2...0.2) => :ambivalent,
+            (..-0.2)     => :negative
+          }.freeze
+
+          CONFIDENCE_LABELS = {
+            (0.8..)     => :calibrated,
+            (0.5...0.8) => :moderate,
+            (0.2...0.5) => :rough,
+            (..0.2)     => :speculative
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/prospection/helpers/prospection_engine.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Prospection
+      module Helpers
+        class ProspectionEngine
+          include Constants
+
+          attr_reader :scenarios, :domain_accuracy, :history
+
+          def initialize
+            @scenarios       = {}
+            @domain_accuracy = {}
+            @history         = []
+          end
+
+          def imagine(domain:, description:, time_horizon:, predicted_valence:,
+                      predicted_arousal:, confidence: nil, **)
+            prune_if_full
+            scenario = Scenario.new(
+              domain:            domain,
+              description:       description,
+              time_horizon:      time_horizon,
+              predicted_valence: predicted_valence,
+              predicted_arousal: predicted_arousal,
+              confidence:        confidence
+            )
+            apply_focalism(scenario, domain)
+            @scenarios[scenario.id] = scenario
+            scenario
+          end
+
+          def scenarios_for(domain:)
+            @scenarios.values.select { |s| s.domain == domain && !s.resolved? }
+          end
+
+          def resolve_scenario(id:, actual_valence:, actual_arousal:)
+            scenario = @scenarios[id]
+            return nil unless scenario
+            return nil if scenario.resolved?
+
+            scenario.resolve(actual_valence: actual_valence, actual_arousal: actual_arousal)
+            update_domain_accuracy(scenario)
+            record_history(scenario)
+            scenario
+          end
+
+          def accuracy_for(domain)
+            1.0 - @domain_accuracy.fetch(domain, 0.0)
+          end
+
+          def near_future(days: 7)
+            @scenarios.values.select { |s| !s.resolved? && s.time_horizon <= days }
+          end
+
+          def most_vivid(count: 5)
+            @scenarios.values
+                      .reject(&:resolved?)
+                      .sort_by { |s| -s.vividness }
+                      .first(count)
+          end
+
+          def decay_all
+            @scenarios.each_value(&:decay)
+            @scenarios.reject! { |_, s| s.expired? }
+          end
+
+          def remove_scenario(id:)
+            @scenarios.delete(id)
+          end
+
+          def scenario_count
+            @scenarios.size
+          end
+
+          def domain_count
+            @scenarios.values.map(&:domain).uniq.size
+          end
+
+          def to_h
+            {
+              scenario_count:  scenario_count,
+              domain_count:    domain_count,
+              history_size:    @history.size,
+              domain_accuracy: @domain_accuracy.transform_values { |v| (1.0 - v).round(4) }
+            }
+          end
+
+          private
+
+          def apply_focalism(scenario, domain)
+            active = scenarios_for(domain: domain)
+            scenario.apply_focalism_discount if active.size >= 1
+          end
+
+          def update_domain_accuracy(scenario)
+            error = scenario.forecast_error || 0.0
+            existing = @domain_accuracy.fetch(scenario.domain, error)
+            @domain_accuracy[scenario.domain] = existing + (VIVIDNESS_ALPHA * (error - existing))
+          end
+
+          def record_history(scenario)
+            @history << {
+              scenario_id:    scenario.id,
+              domain:         scenario.domain,
+              forecast_error: scenario.forecast_error,
+              resolved_at:    scenario.resolved_at
+            }
+            @history.shift while @history.size > MAX_HISTORY
+          end
+
+          def prune_if_full
+            return unless @scenarios.size >= MAX_SCENARIOS
+
+            oldest = @scenarios.values
+                               .reject(&:resolved?)
+                               .min_by(&:created_at)
+            @scenarios.delete(oldest.id) if oldest
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/prospection/helpers/scenario.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Prospection
+      module Helpers
+        class Scenario
+          include Constants
+
+          attr_reader :id, :domain, :description, :time_horizon, :predicted_valence,
+                      :predicted_arousal, :confidence, :vividness, :created_at,
+                      :actual_valence, :actual_arousal, :resolved_at
+
+          def initialize(domain:, description:, time_horizon:, predicted_valence:,
+                         predicted_arousal:, confidence: nil, **)
+            @id                = SecureRandom.uuid
+            @domain            = domain
+            @description       = description
+            @time_horizon      = [time_horizon.to_f, MAX_TIME_HORIZON].min
+            @predicted_valence = predicted_valence.clamp(-1.0, 1.0)
+            @predicted_arousal = predicted_arousal.clamp(0.0, 1.0)
+            @confidence        = (confidence || DEFAULT_CONFIDENCE).clamp(0.0, 1.0)
+            @vividness         = DEFAULT_VIVIDNESS
+            @created_at        = Time.now.utc
+            @actual_valence    = nil
+            @actual_arousal    = nil
+            @resolved_at       = nil
+          end
+
+          def temporal_discount
+            1.0 - (TEMPORAL_DISCOUNT_RATE * @time_horizon).clamp(0.0, 0.9)
+          end
+
+          def corrected_valence
+            @predicted_valence * IMPACT_BIAS_CORRECTION * temporal_discount
+          end
+
+          def corrected_arousal
+            @predicted_arousal * IMPACT_BIAS_CORRECTION * temporal_discount
+          end
+
+          def label
+            VALENCE_LABELS.each do |range, lbl|
+              return lbl if range.cover?(corrected_valence)
+            end
+            :ambivalent
+          end
+
+          def confidence_label
+            CONFIDENCE_LABELS.each do |range, lbl|
+              return lbl if range.cover?(@confidence)
+            end
+            :speculative
+          end
+
+          def decay
+            @confidence = (@confidence - SCENARIO_DECAY).clamp(0.0, 1.0)
+            @vividness  = (@vividness - SCENARIO_DECAY).clamp(0.0, 1.0)
+          end
+
+          def reinforce_vividness(amount)
+            @vividness = (@vividness + (VIVIDNESS_ALPHA * amount)).clamp(0.0, 1.0)
+          end
+
+          def apply_focalism_discount
+            @predicted_valence *= (1.0 - FOCALISM_DISCOUNT)
+            @predicted_arousal *= (1.0 - FOCALISM_DISCOUNT)
+          end
+
+          def resolve(actual_valence:, actual_arousal:)
+            @actual_valence = actual_valence.clamp(-1.0, 1.0)
+            @actual_arousal = actual_arousal.clamp(0.0, 1.0)
+            @resolved_at    = Time.now.utc
+          end
+
+          def resolved?
+            !@resolved_at.nil?
+          end
+
+          def forecast_error
+            return nil unless resolved?
+
+            (corrected_valence - @actual_valence).abs
+          end
+
+          def expired?
+            @confidence < 0.01 && @vividness < 0.01
+          end
+
+          def to_h
+            {
+              id:                @id,
+              domain:            @domain,
+              description:       @description,
+              time_horizon:      @time_horizon,
+              predicted_valence: @predicted_valence,
+              predicted_arousal: @predicted_arousal,
+              corrected_valence: corrected_valence.round(4),
+              corrected_arousal: corrected_arousal.round(4),
+              confidence:        @confidence.round(4),
+              confidence_label:  confidence_label,
+              vividness:         @vividness.round(4),
+              label:             label,
+              resolved:          resolved?,
+              forecast_error:    forecast_error&.round(4),
+              created_at:        @created_at,
+              resolved_at:       @resolved_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Prospection
+      module Runners
+        module Prospection
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def imagine_future(domain:, description:, time_horizon:, predicted_valence:,
+                             predicted_arousal:, confidence: nil, **)
+            scenario = prospection_engine.imagine(
+              domain:            domain,
+              description:       description,
+              time_horizon:      time_horizon,
+              predicted_valence: predicted_valence,
+              predicted_arousal: predicted_arousal,
+              confidence:        confidence
+            )
+            Legion::Logging.debug \
+              "[prospection] imagine: domain=#{domain} horizon=#{time_horizon}d " \
+              "valence=#{predicted_valence.round(3)} label=#{scenario.label}"
+            {
+              success:           true,
+              scenario_id:       scenario.id,
+              domain:            scenario.domain,
+              label:             scenario.label,
+              corrected_valence: scenario.corrected_valence.round(4),
+              corrected_arousal: scenario.corrected_arousal.round(4),
+              confidence:        scenario.confidence.round(4),
+              confidence_label:  scenario.confidence_label
+            }
+          end
+
+          def resolve_future(scenario_id:, actual_valence:, actual_arousal:, **)
+            scenario = prospection_engine.resolve_scenario(
+              id:             scenario_id,
+              actual_valence: actual_valence,
+              actual_arousal: actual_arousal
+            )
+            unless scenario
+              Legion::Logging.debug "[prospection] resolve: id=#{scenario_id} not_found_or_already_resolved"
+              return { success: false, reason: :not_found }
+            end
+            Legion::Logging.debug \
+              "[prospection] resolve: id=#{scenario_id} domain=#{scenario.domain} " \
+              "error=#{scenario.forecast_error&.round(3)}"
+            {
+              success:        true,
+              scenario_id:    scenario.id,
+              domain:         scenario.domain,
+              forecast_error: scenario.forecast_error&.round(4),
+              actual_valence: actual_valence,
+              actual_arousal: actual_arousal
+            }
+          end
+
+          def forecast_accuracy(domain: :general, **)
+            accuracy = prospection_engine.accuracy_for(domain)
+            Legion::Logging.debug "[prospection] accuracy: domain=#{domain} accuracy=#{accuracy.round(3)}"
+            { success: true, domain: domain, accuracy: accuracy.round(4) }
+          end
+
+          def near_future_scenarios(days: 7, **)
+            scenarios = prospection_engine.near_future(days: days)
+            Legion::Logging.debug "[prospection] near_future: days=#{days} count=#{scenarios.size}"
+            {
+              success:   true,
+              days:      days,
+              scenarios: scenarios.map(&:to_h),
+              count:     scenarios.size
+            }
+          end
+
+          def vivid_scenarios(count: 5, **)
+            scenarios = prospection_engine.most_vivid(count: count)
+            Legion::Logging.debug "[prospection] vivid: count=#{scenarios.size}"
+            {
+              success:   true,
+              scenarios: scenarios.map(&:to_h),
+              count:     scenarios.size
+            }
+          end
+
+          def scenarios_in_domain(domain:, **)
+            scenarios = prospection_engine.scenarios_for(domain: domain)
+            Legion::Logging.debug "[prospection] domain_scenarios: domain=#{domain} count=#{scenarios.size}"
+            {
+              success:   true,
+              domain:    domain,
+              scenarios: scenarios.map(&:to_h),
+              count:     scenarios.size
+            }
+          end
+
+          def update_prospection(**)
+            prospection_engine.decay_all
+            stats = prospection_engine.to_h
+            Legion::Logging.debug \
+              "[prospection] tick: scenarios=#{stats[:scenario_count]} " \
+              "domains=#{stats[:domain_count]} history=#{stats[:history_size]}"
+            { success: true }.merge(stats)
+          end
+
+          def prospection_stats(**)
+            stats = prospection_engine.to_h
+            Legion::Logging.debug \
+              "[prospection] stats: scenarios=#{stats[:scenario_count]} " \
+              "domains=#{stats[:domain_count]}"
+            { success: true, stats: stats }
+          end
+
+          private
+
+          def prospection_engine
+            @prospection_engine ||= Helpers::ProspectionEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/prospection.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'legion/extensions/prospection/version'
+require 'legion/extensions/prospection/helpers/constants'
+require 'legion/extensions/prospection/helpers/scenario'
+require 'legion/extensions/prospection/helpers/prospection_engine'
+require 'legion/extensions/prospection/runners/prospection'
+require 'legion/extensions/prospection/client'
+
+module Legion
+  module Extensions
+    module Prospection
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: lex-prospection
+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: 'Future-oriented mental simulation: imagines future scenarios, predicts
+  their emotional impact, tracks impact bias and focalism corrections, and calibrates
+  forecast accuracy over time. Based on Gilbert & Wilson affective forecasting research.'
+email:
+- matt@iverson.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/legion/extensions/prospection.rb
+- lib/legion/extensions/prospection/actors/decay.rb
+- lib/legion/extensions/prospection/client.rb
+- lib/legion/extensions/prospection/helpers/constants.rb
+- lib/legion/extensions/prospection/helpers/prospection_engine.rb
+- lib/legion/extensions/prospection/helpers/scenario.rb
+- lib/legion/extensions/prospection/runners/prospection.rb
+- lib/legion/extensions/prospection/version.rb
+homepage: https://github.com/LegionIO/lex-prospection
+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: Affective forecasting and mental time travel for LegionIO
+test_files: []