lex-prediction 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 40883318ee6a41596e8b2693ba9c154d2191b8566ad39fea5d45c00a4a87d2de
+  data.tar.gz: f75fffc950c49b188aa8904d560e225c70965dd27c8f83874dbf6f7879e7ea0d
+SHA512:
+  metadata.gz: a49a26d11921d15af3613124205478263fc836ca7ce58adcf4506e4de69c3762fe748bfbb6a9a232c2a218bc114891fde42632a2ca623c0ddf3931bd2b864f64
+  data.tar.gz: 2fb9dfe8318de27742d9a67f17145abe63a2b069ef9eeef0be776069dfa672233848d76eddab624c750467bd8e99fb446c154821351fc4b0f6be78677b95079c

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-prediction.gemspec

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

data/lib/legion/extensions/prediction/actors/expire_predictions.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module Prediction
+      module Actor
+        class ExpirePredictions < Legion::Extensions::Actors::Every
+          def runner_class
+            Legion::Extensions::Prediction::Runners::Prediction
+          end
+
+          def runner_function
+            'expire_stale_predictions'
+          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/prediction/client.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/prediction/helpers/modes'
+require 'legion/extensions/prediction/helpers/prediction_store'
+require 'legion/extensions/prediction/runners/prediction'
+
+module Legion
+  module Extensions
+    module Prediction
+      class Client
+        include Runners::Prediction
+
+        def initialize(**)
+          @prediction_store = Helpers::PredictionStore.new
+        end
+
+        private
+
+        attr_reader :prediction_store
+      end
+    end
+  end
+end

data/lib/legion/extensions/prediction/helpers/modes.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Prediction
+      module Helpers
+        module Modes
+          # Four reasoning modes (spec: prediction-engine-spec.md)
+          REASONING_MODES = %i[fault_localization functional_mapping boundary_testing counterfactual].freeze
+
+          PREDICTION_CONFIDENCE_MIN = 0.65
+          MAX_PREDICTIONS_PER_TICK  = 5
+          PREDICTION_HORIZON        = 3600 # 1 hour default lookahead
+
+          module_function
+
+          def valid_mode?(mode)
+            REASONING_MODES.include?(mode)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/prediction/helpers/prediction_store.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Prediction
+      module Helpers
+        class PredictionStore
+          attr_reader :predictions, :outcomes
+
+          def initialize
+            @predictions = {}
+            @outcomes = []
+          end
+
+          def store(prediction)
+            id = prediction[:prediction_id] || SecureRandom.uuid
+            prediction[:prediction_id] = id
+            prediction[:created_at] ||= Time.now.utc
+            prediction[:status] ||= :pending
+            @predictions[id] = prediction
+            id
+          end
+
+          def get(prediction_id)
+            @predictions[prediction_id]
+          end
+
+          def resolve(prediction_id, outcome:, actual: nil)
+            pred = @predictions[prediction_id]
+            return nil unless pred
+
+            pred[:status] = outcome # :correct, :incorrect, :partial, :expired
+            pred[:resolved_at] = Time.now.utc
+            pred[:actual] = actual
+
+            @outcomes << { prediction_id: prediction_id, outcome: outcome, at: Time.now.utc }
+            @outcomes.shift while @outcomes.size > 500
+            pred
+          end
+
+          def pending
+            @predictions.values.select { |p| p[:status] == :pending }
+          end
+
+          def accuracy(window: 100)
+            recent = @outcomes.last(window)
+            return 0.0 if recent.empty?
+
+            correct = recent.count { |o| o[:outcome] == :correct }
+            correct.to_f / recent.size
+          end
+
+          def count
+            @predictions.size
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Prediction
+      module Runners
+        module Prediction
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def predict(mode:, context: {}, confidence: nil, description: nil, **)
+            return { error: :invalid_mode, valid_modes: Helpers::Modes::REASONING_MODES } unless Helpers::Modes.valid_mode?(mode)
+
+            prediction = {
+              prediction_id: SecureRandom.uuid,
+              mode:          mode,
+              context:       context,
+              confidence:    confidence || estimate_confidence(mode, context),
+              description:   description,
+              status:        :pending,
+              created_at:    Time.now.utc,
+              horizon:       Helpers::Modes::PREDICTION_HORIZON
+            }
+
+            prediction_store.store(prediction)
+
+            actionable = prediction[:confidence] >= Helpers::Modes::PREDICTION_CONFIDENCE_MIN
+            Legion::Logging.debug "[prediction] new: mode=#{mode} confidence=#{prediction[:confidence].round(2)} " \
+                                  "actionable=#{actionable} id=#{prediction[:prediction_id][0..7]}"
+
+            {
+              prediction_id: prediction[:prediction_id],
+              mode:          mode,
+              confidence:    prediction[:confidence],
+              actionable:    actionable
+            }
+          end
+
+          def resolve_prediction(prediction_id:, outcome:, actual: nil, **)
+            pred = prediction_store.resolve(prediction_id, outcome: outcome, actual: actual)
+            if pred
+              Legion::Logging.info "[prediction] resolved #{prediction_id[0..7]} outcome=#{outcome}"
+              record_outcome_trace(pred, outcome)
+              { resolved: true, prediction_id: prediction_id, outcome: outcome }
+            else
+              Legion::Logging.debug "[prediction] resolve failed: #{prediction_id[0..7]} not found"
+              { resolved: false, reason: :not_found }
+            end
+          end
+
+          def pending_predictions(**)
+            preds = prediction_store.pending
+            Legion::Logging.debug "[prediction] pending count=#{preds.size}"
+            { predictions: preds, count: preds.size }
+          end
+
+          def prediction_accuracy(window: 100, **)
+            acc = prediction_store.accuracy(window: window)
+            total = prediction_store.outcomes.size
+            Legion::Logging.debug "[prediction] accuracy=#{acc.round(2)} total_outcomes=#{total}"
+            { accuracy: acc, total_outcomes: total }
+          end
+
+          def expire_stale_predictions(**)
+            expired_count = 0
+
+            prediction_store.pending.each do |pred|
+              age = Time.now.utc - pred[:created_at]
+              next unless age > pred[:horizon]
+
+              prediction_store.resolve(pred[:prediction_id], outcome: :expired, actual: nil)
+              expired_count += 1
+            end
+
+            remaining = prediction_store.pending.size
+            Legion::Logging.debug "[prediction] expire sweep: expired=#{expired_count} remaining=#{remaining}"
+
+            { expired_count: expired_count, remaining_pending: remaining }
+          end
+
+          def get_prediction(prediction_id:, **)
+            pred = prediction_store.get(prediction_id)
+            pred ? { found: true, prediction: pred } : { found: false }
+          end
+
+          private
+
+          def prediction_store
+            @prediction_store ||= Helpers::PredictionStore.new
+          end
+
+          def estimate_confidence(mode, context)
+            base = case mode
+                   when :fault_localization then 0.7
+                   when :functional_mapping then 0.6
+                   when :counterfactual     then 0.4
+                   else                          0.5
+                   end
+            richness_bonus = [context.size * 0.02, 0.2].min
+            [base + richness_bonus, 1.0].min
+          end
+
+          def record_outcome_trace(prediction, outcome)
+            return unless defined?(Legion::Extensions::Memory::Runners::Traces)
+
+            trace_params = case outcome
+                           when :correct
+                             { type: :semantic, valence: 0.3, intensity: 0.3, unresolved: false }
+                           when :incorrect
+                             { type: :episodic, valence: -0.5, intensity: 0.6, unresolved: true }
+                           when :partial
+                             { type: :episodic, valence: -0.2, intensity: 0.4, unresolved: true }
+                           else
+                             return
+                           end
+
+            runner = Object.new.extend(Legion::Extensions::Memory::Runners::Traces)
+            runner.store_trace(
+              type:                trace_params[:type],
+              content_payload:     "prediction #{outcome}: mode=#{prediction[:mode]} confidence=#{prediction[:confidence]}",
+              domain_tags:         ['prediction', prediction[:mode].to_s],
+              origin:              :direct_experience,
+              emotional_valence:   trace_params[:valence],
+              emotional_intensity: trace_params[:intensity],
+              unresolved:          trace_params[:unresolved],
+              confidence:          prediction[:confidence]
+            )
+
+            store = runner.send(:default_store)
+            store.flush if store.respond_to?(:flush)
+
+            Legion::Logging.debug "[prediction] created #{trace_params[:type]} trace for #{outcome} prediction"
+          rescue StandardError => e
+            Legion::Logging.warn "[prediction] failed to create outcome trace: #{e.message}"
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/prediction.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/prediction/version'
+require 'legion/extensions/prediction/helpers/modes'
+require 'legion/extensions/prediction/helpers/prediction_store'
+require 'legion/extensions/prediction/runners/prediction'
+
+module Legion
+  module Extensions
+    module Prediction
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

data/spec/legion/extensions/prediction/actors/expire_predictions_spec.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Stub the base class before loading the actor
+module Legion
+  module Extensions
+    module Actors
+      class Every; end # rubocop:disable Lint/EmptyClass
+    end
+  end
+end
+
+$LOADED_FEATURES << 'legion/extensions/actors/every'
+
+require_relative '../../../../../lib/legion/extensions/prediction/actors/expire_predictions'
+
+RSpec.describe Legion::Extensions::Prediction::Actor::ExpirePredictions do
+  subject(:actor) { described_class.new }
+
+  describe '#runner_class' do
+    it { expect(actor.runner_class).to eq Legion::Extensions::Prediction::Runners::Prediction }
+  end
+
+  describe '#runner_function' do
+    it { expect(actor.runner_function).to eq 'expire_stale_predictions' }
+  end
+
+  describe '#time' do
+    it { expect(actor.time).to eq 300 }
+  end
+
+  describe '#run_now?' do
+    it { expect(actor.run_now?).to be false }
+  end
+
+  describe '#use_runner?' do
+    it { expect(actor.use_runner?).to be false }
+  end
+
+  describe '#check_subtask?' do
+    it { expect(actor.check_subtask?).to be false }
+  end
+
+  describe '#generate_task?' do
+    it { expect(actor.generate_task?).to be false }
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/prediction/client'
+
+RSpec.describe Legion::Extensions::Prediction::Client do
+  it 'responds to prediction runner methods' do
+    client = described_class.new
+    expect(client).to respond_to(:predict)
+    expect(client).to respond_to(:resolve_prediction)
+    expect(client).to respond_to(:pending_predictions)
+    expect(client).to respond_to(:prediction_accuracy)
+    expect(client).to respond_to(:get_prediction)
+  end
+end

data/spec/legion/extensions/prediction/helpers/modes_spec.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Prediction::Helpers::Modes do
+  describe 'REASONING_MODES' do
+    it 'is a frozen array of symbols' do
+      expect(described_class::REASONING_MODES).to be_a(Array)
+      expect(described_class::REASONING_MODES).to be_frozen
+    end
+
+    it 'contains exactly four modes' do
+      expect(described_class::REASONING_MODES.size).to eq(4)
+    end
+
+    it 'includes fault_localization' do
+      expect(described_class::REASONING_MODES).to include(:fault_localization)
+    end
+
+    it 'includes functional_mapping' do
+      expect(described_class::REASONING_MODES).to include(:functional_mapping)
+    end
+
+    it 'includes boundary_testing' do
+      expect(described_class::REASONING_MODES).to include(:boundary_testing)
+    end
+
+    it 'includes counterfactual' do
+      expect(described_class::REASONING_MODES).to include(:counterfactual)
+    end
+
+    it 'contains only symbols' do
+      expect(described_class::REASONING_MODES).to all(be_a(Symbol))
+    end
+  end
+
+  describe 'PREDICTION_CONFIDENCE_MIN' do
+    it 'is 0.65' do
+      expect(described_class::PREDICTION_CONFIDENCE_MIN).to eq(0.65)
+    end
+
+    it 'is a float' do
+      expect(described_class::PREDICTION_CONFIDENCE_MIN).to be_a(Float)
+    end
+
+    it 'is in the valid 0.0-1.0 range' do
+      expect(described_class::PREDICTION_CONFIDENCE_MIN).to be_between(0.0, 1.0)
+    end
+  end
+
+  describe 'MAX_PREDICTIONS_PER_TICK' do
+    it 'is 5' do
+      expect(described_class::MAX_PREDICTIONS_PER_TICK).to eq(5)
+    end
+
+    it 'is an integer' do
+      expect(described_class::MAX_PREDICTIONS_PER_TICK).to be_an(Integer)
+    end
+
+    it 'is positive' do
+      expect(described_class::MAX_PREDICTIONS_PER_TICK).to be > 0
+    end
+  end
+
+  describe 'PREDICTION_HORIZON' do
+    it 'is 3600' do
+      expect(described_class::PREDICTION_HORIZON).to eq(3600)
+    end
+
+    it 'is an integer' do
+      expect(described_class::PREDICTION_HORIZON).to be_an(Integer)
+    end
+
+    it 'represents one hour in seconds' do
+      expect(described_class::PREDICTION_HORIZON).to eq(60 * 60)
+    end
+  end
+
+  describe '.valid_mode?' do
+    it 'returns true for fault_localization' do
+      expect(described_class.valid_mode?(:fault_localization)).to be true
+    end
+
+    it 'returns true for functional_mapping' do
+      expect(described_class.valid_mode?(:functional_mapping)).to be true
+    end
+
+    it 'returns true for boundary_testing' do
+      expect(described_class.valid_mode?(:boundary_testing)).to be true
+    end
+
+    it 'returns true for counterfactual' do
+      expect(described_class.valid_mode?(:counterfactual)).to be true
+    end
+
+    it 'returns false for an unknown mode symbol' do
+      expect(described_class.valid_mode?(:neural_network)).to be false
+    end
+
+    it 'returns false for a string form of a valid mode' do
+      expect(described_class.valid_mode?('fault_localization')).to be false
+    end
+
+    it 'returns false for nil' do
+      expect(described_class.valid_mode?(nil)).to be false
+    end
+
+    it 'returns false for an integer' do
+      expect(described_class.valid_mode?(42)).to be false
+    end
+
+    it 'returns true for all REASONING_MODES members' do
+      described_class::REASONING_MODES.each do |mode|
+        expect(described_class.valid_mode?(mode)).to be true
+      end
+    end
+  end
+end

data/spec/legion/extensions/prediction/helpers/prediction_store_spec.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Prediction::Helpers::PredictionStore do
+  subject(:store) { described_class.new }
+
+  let(:basic_prediction) do
+    {
+      mode:        :fault_localization,
+      confidence:  0.75,
+      description: 'disk latency spike incoming',
+      status:      :pending
+    }
+  end
+
+  describe '#initialize' do
+    it 'starts with empty predictions hash' do
+      expect(store.predictions).to eq({})
+    end
+
+    it 'starts with empty outcomes array' do
+      expect(store.outcomes).to eq([])
+    end
+  end
+
+  describe '#store' do
+    it 'returns a UUID string' do
+      id = store.store(basic_prediction.dup)
+      expect(id).to match(/\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/)
+    end
+
+    it 'stores the prediction under the returned id' do
+      id = store.store(basic_prediction.dup)
+      expect(store.predictions[id]).not_to be_nil
+    end
+
+    it 'sets prediction_id on the prediction hash' do
+      prediction = basic_prediction.dup
+      id = store.store(prediction)
+      expect(prediction[:prediction_id]).to eq(id)
+    end
+
+    it 'preserves a caller-supplied prediction_id' do
+      prediction = basic_prediction.merge(prediction_id: 'my-custom-id')
+      returned_id = store.store(prediction)
+      expect(returned_id).to eq('my-custom-id')
+      expect(store.predictions['my-custom-id']).not_to be_nil
+    end
+
+    it 'sets created_at when not supplied' do
+      prediction = basic_prediction.dup
+      before = Time.now.utc
+      store.store(prediction)
+      expect(prediction[:created_at]).to be >= before
+    end
+
+    it 'preserves a caller-supplied created_at' do
+      custom_time = Time.now.utc - 3600
+      prediction  = basic_prediction.merge(created_at: custom_time)
+      store.store(prediction)
+      expect(prediction[:created_at]).to eq(custom_time)
+    end
+
+    it 'sets default status to :pending' do
+      prediction = { mode: :counterfactual, confidence: 0.5 }
+      store.store(prediction)
+      expect(prediction[:status]).to eq(:pending)
+    end
+
+    it 'preserves a caller-supplied status' do
+      prediction = basic_prediction.merge(status: :expired)
+      store.store(prediction)
+      expect(prediction[:status]).to eq(:expired)
+    end
+
+    it 'increments count with each stored prediction' do
+      3.times { store.store(basic_prediction.dup) }
+      expect(store.count).to eq(3)
+    end
+  end
+
+  describe '#get' do
+    it 'retrieves a stored prediction by id' do
+      id = store.store(basic_prediction.dup)
+      result = store.get(id)
+      expect(result[:mode]).to eq(:fault_localization)
+    end
+
+    it 'returns nil for an unknown id' do
+      expect(store.get('no-such-id')).to be_nil
+    end
+  end
+
+  describe '#resolve' do
+    let!(:prediction_id) { store.store(basic_prediction.dup) }
+
+    it 'returns the updated prediction' do
+      result = store.resolve(prediction_id, outcome: :correct)
+      expect(result).to be_a(Hash)
+      expect(result[:prediction_id]).to eq(prediction_id)
+    end
+
+    it 'sets status to the given outcome' do
+      store.resolve(prediction_id, outcome: :incorrect)
+      expect(store.get(prediction_id)[:status]).to eq(:incorrect)
+    end
+
+    it 'sets resolved_at timestamp' do
+      before = Time.now.utc
+      store.resolve(prediction_id, outcome: :correct)
+      expect(store.get(prediction_id)[:resolved_at]).to be >= before
+    end
+
+    it 'stores actual value when provided' do
+      store.resolve(prediction_id, outcome: :partial, actual: 'disk io at 80%')
+      expect(store.get(prediction_id)[:actual]).to eq('disk io at 80%')
+    end
+
+    it 'stores nil actual when not provided' do
+      store.resolve(prediction_id, outcome: :correct)
+      expect(store.get(prediction_id)[:actual]).to be_nil
+    end
+
+    it 'appends to outcomes array' do
+      store.resolve(prediction_id, outcome: :correct)
+      expect(store.outcomes.size).to eq(1)
+    end
+
+    it 'records prediction_id in the outcome entry' do
+      store.resolve(prediction_id, outcome: :correct)
+      expect(store.outcomes.last[:prediction_id]).to eq(prediction_id)
+    end
+
+    it 'records outcome in the outcome entry' do
+      store.resolve(prediction_id, outcome: :incorrect)
+      expect(store.outcomes.last[:outcome]).to eq(:incorrect)
+    end
+
+    it 'returns nil for a non-existent prediction_id' do
+      result = store.resolve('ghost-id', outcome: :correct)
+      expect(result).to be_nil
+    end
+
+    it 'caps outcomes array at 500 entries' do
+      501.times do
+        id = store.store(basic_prediction.dup)
+        store.resolve(id, outcome: :correct)
+      end
+      expect(store.outcomes.size).to eq(500)
+    end
+  end
+
+  describe '#pending' do
+    it 'returns only predictions with status :pending' do
+      id1 = store.store(basic_prediction.dup)
+      id2 = store.store(basic_prediction.dup)
+      store.resolve(id1, outcome: :correct)
+
+      result = store.pending
+      expect(result.size).to eq(1)
+      expect(result.first[:prediction_id]).to eq(id2)
+    end
+
+    it 'returns empty array when no pending predictions' do
+      id = store.store(basic_prediction.dup)
+      store.resolve(id, outcome: :correct)
+      expect(store.pending).to be_empty
+    end
+
+    it 'returns all stored predictions when none are resolved' do
+      3.times { store.store(basic_prediction.dup) }
+      expect(store.pending.size).to eq(3)
+    end
+  end
+
+  describe '#accuracy' do
+    it 'returns 0.0 when no outcomes exist' do
+      expect(store.accuracy).to eq(0.0)
+    end
+
+    it 'returns 1.0 when all outcomes are :correct' do
+      3.times do
+        id = store.store(basic_prediction.dup)
+        store.resolve(id, outcome: :correct)
+      end
+      expect(store.accuracy).to eq(1.0)
+    end
+
+    it 'returns 0.0 when all outcomes are :incorrect' do
+      3.times do
+        id = store.store(basic_prediction.dup)
+        store.resolve(id, outcome: :incorrect)
+      end
+      expect(store.accuracy).to eq(0.0)
+    end
+
+    it 'computes fractional accuracy correctly' do
+      3.times do
+        id = store.store(basic_prediction.dup)
+        store.resolve(id, outcome: :correct)
+      end
+      id = store.store(basic_prediction.dup)
+      store.resolve(id, outcome: :incorrect)
+      expect(store.accuracy).to eq(0.75)
+    end
+
+    it 'defaults window to 100' do
+      102.times do
+        id = store.store(basic_prediction.dup)
+        store.resolve(id, outcome: :incorrect)
+      end
+      2.times do
+        id = store.store(basic_prediction.dup)
+        store.resolve(id, outcome: :correct)
+      end
+      # window=100: last 100 contain 2 correct out of 100 = 0.02
+      expect(store.accuracy(window: 100)).to eq(0.02)
+    end
+
+    it 'accepts a custom window parameter' do
+      5.times do
+        id = store.store(basic_prediction.dup)
+        store.resolve(id, outcome: :incorrect)
+      end
+      5.times do
+        id = store.store(basic_prediction.dup)
+        store.resolve(id, outcome: :correct)
+      end
+      # window=5: last 5 are all :correct
+      expect(store.accuracy(window: 5)).to eq(1.0)
+    end
+
+    it 'ignores non-:correct outcomes in numerator' do
+      id = store.store(basic_prediction.dup)
+      store.resolve(id, outcome: :partial)
+      id = store.store(basic_prediction.dup)
+      store.resolve(id, outcome: :expired)
+      id = store.store(basic_prediction.dup)
+      store.resolve(id, outcome: :correct)
+      expect(store.accuracy).to be_within(0.001).of(1.0 / 3.0)
+    end
+  end
+
+  describe '#count' do
+    it 'returns 0 for a new store' do
+      expect(store.count).to eq(0)
+    end
+
+    it 'returns the total number of stored predictions' do
+      5.times { store.store(basic_prediction.dup) }
+      expect(store.count).to eq(5)
+    end
+
+    it 'counts resolved predictions as well as pending ones' do
+      id = store.store(basic_prediction.dup)
+      store.resolve(id, outcome: :correct)
+      store.store(basic_prediction.dup)
+      expect(store.count).to eq(2)
+    end
+  end
+end

data/spec/legion/extensions/prediction/runners/prediction_spec.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/prediction/client'
+
+RSpec.describe Legion::Extensions::Prediction::Runners::Prediction do
+  let(:client) { Legion::Extensions::Prediction::Client.new }
+
+  describe '#predict' do
+    it 'creates a prediction with valid mode' do
+      result = client.predict(mode: :fault_localization, description: 'test')
+      expect(result[:prediction_id]).to match(/\A[0-9a-f-]{36}\z/)
+      expect(result[:mode]).to eq(:fault_localization)
+    end
+
+    it 'rejects invalid mode' do
+      result = client.predict(mode: :invalid)
+      expect(result[:error]).to eq(:invalid_mode)
+    end
+
+    it 'marks actionable predictions above confidence threshold' do
+      result = client.predict(mode: :fault_localization, confidence: 0.9)
+      expect(result[:actionable]).to be true
+    end
+
+    it 'marks non-actionable predictions below threshold' do
+      result = client.predict(mode: :counterfactual, confidence: 0.3)
+      expect(result[:actionable]).to be false
+    end
+
+    it 'estimates confidence based on mode' do
+      fault = client.predict(mode: :fault_localization)
+      counterfactual = client.predict(mode: :counterfactual)
+      expect(fault[:confidence]).to be > counterfactual[:confidence]
+    end
+  end
+
+  describe '#resolve_prediction' do
+    it 'resolves a pending prediction' do
+      pred = client.predict(mode: :functional_mapping)
+      result = client.resolve_prediction(prediction_id: pred[:prediction_id], outcome: :correct)
+      expect(result[:resolved]).to be true
+    end
+
+    it 'returns not_found for missing prediction' do
+      result = client.resolve_prediction(prediction_id: 'nonexistent', outcome: :correct)
+      expect(result[:resolved]).to be false
+    end
+  end
+
+  describe '#pending_predictions' do
+    it 'lists pending predictions' do
+      client.predict(mode: :fault_localization)
+      client.predict(mode: :boundary_testing)
+      result = client.pending_predictions
+      expect(result[:count]).to eq(2)
+    end
+  end
+
+  describe '#expire_stale_predictions' do
+    it 'returns zero expired when no pending predictions' do
+      result = client.expire_stale_predictions
+      expect(result[:expired_count]).to eq(0)
+      expect(result[:remaining_pending]).to eq(0)
+    end
+
+    it 'expires predictions older than their horizon' do
+      client.predict(mode: :fault_localization)
+      client.predict(mode: :boundary_testing)
+
+      # Simulate staleness by back-dating created_at beyond the horizon
+      store = client.send(:prediction_store)
+      store.predictions.each_value do |pred|
+        pred[:created_at] = Time.now.utc - pred[:horizon] - 1
+      end
+
+      result = client.expire_stale_predictions
+      expect(result[:expired_count]).to eq(2)
+      expect(result[:remaining_pending]).to eq(0)
+    end
+
+    it 'preserves predictions that have not exceeded their horizon' do
+      client.predict(mode: :fault_localization)
+      # created_at is just now, horizon is 3600s — not stale
+      result = client.expire_stale_predictions
+      expect(result[:expired_count]).to eq(0)
+      expect(result[:remaining_pending]).to eq(1)
+    end
+
+    it 'only expires stale predictions when mixed with fresh ones' do
+      client.predict(mode: :fault_localization)
+      stale = client.predict(mode: :boundary_testing)
+
+      store = client.send(:prediction_store)
+      stale_pred = store.predictions[stale[:prediction_id]]
+      stale_pred[:created_at] = Time.now.utc - stale_pred[:horizon] - 1
+
+      result = client.expire_stale_predictions
+      expect(result[:expired_count]).to eq(1)
+      expect(result[:remaining_pending]).to eq(1)
+    end
+  end
+
+  describe '#prediction_accuracy' do
+    it 'computes accuracy' do
+      3.times do
+        pred = client.predict(mode: :fault_localization)
+        client.resolve_prediction(prediction_id: pred[:prediction_id], outcome: :correct)
+      end
+      pred = client.predict(mode: :fault_localization)
+      client.resolve_prediction(prediction_id: pred[:prediction_id], outcome: :incorrect)
+
+      result = client.prediction_accuracy
+      expect(result[:accuracy]).to eq(0.75)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,20 @@
+# 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/prediction'
+
+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,76 @@
+--- !ruby/object:Gem::Specification
+name: lex-prediction
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+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: Forward-model prediction engine (4 reasoning modes) for brain-modeled
+  agentic AI
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-prediction.gemspec
+- lib/legion/extensions/prediction.rb
+- lib/legion/extensions/prediction/actors/expire_predictions.rb
+- lib/legion/extensions/prediction/client.rb
+- lib/legion/extensions/prediction/helpers/modes.rb
+- lib/legion/extensions/prediction/helpers/prediction_store.rb
+- lib/legion/extensions/prediction/runners/prediction.rb
+- lib/legion/extensions/prediction/version.rb
+- spec/legion/extensions/prediction/actors/expire_predictions_spec.rb
+- spec/legion/extensions/prediction/client_spec.rb
+- spec/legion/extensions/prediction/helpers/modes_spec.rb
+- spec/legion/extensions/prediction/helpers/prediction_store_spec.rb
+- spec/legion/extensions/prediction/runners/prediction_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-prediction
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-prediction
+  source_code_uri: https://github.com/LegionIO/lex-prediction
+  documentation_uri: https://github.com/LegionIO/lex-prediction
+  changelog_uri: https://github.com/LegionIO/lex-prediction
+  bug_tracker_uri: https://github.com/LegionIO/lex-prediction/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 Prediction
+test_files: []