lex-predictive-processing 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0b2a81f552ab46d8107dcadb31234489978d943358698284842e2513c06ee7f4
+  data.tar.gz: 83fdf31810c065a1b6b48db9572807362fb46a34ca14a1b4d86e028cd6d8085b
+SHA512:
+  metadata.gz: c0710af7f0b991c387797a3ed494232eb3a7a96d687dc0a362b8a99f3e58321e912305a405e58b834c3c4afc675ddb3c81e634c0456499ba2699dcb841055cd1
+  data.tar.gz: 33ac74d6a364efdac1d5fe23d31991090b14bc9a14e2bce7501b1d17ec717a41aff8d6d0b994b82b4c06dd6053625ad78326b62fc0638327796da0dc30bcdfab

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-predictive-processing.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/predictive_processing/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-predictive-processing'
+  spec.version       = Legion::Extensions::PredictiveProcessing::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Predictive Processing'
+  spec.description   = "Andy Clark's Predictive Processing / Active Inference for brain-modeled agentic AI: " \
+                       'generative models, precision-weighting, active inference, and free energy minimization'
+  spec.homepage      = 'https://github.com/LegionIO/lex-predictive-processing'
+  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-predictive-processing'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-predictive-processing'
+  spec.metadata['changelog_uri']     = 'https://github.com/LegionIO/lex-predictive-processing'
+  spec.metadata['bug_tracker_uri']   = 'https://github.com/LegionIO/lex-predictive-processing/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-predictive-processing.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/predictive_processing/helpers/constants'
+require 'legion/extensions/predictive_processing/helpers/generative_model'
+require 'legion/extensions/predictive_processing/helpers/predictive_processor'
+require 'legion/extensions/predictive_processing/runners/predictive_processing'
+
+module Legion
+  module Extensions
+    module PredictiveProcessing
+      class Client
+        include Runners::PredictiveProcessing
+
+        def initialize(processor: nil)
+          @default_processor = processor || Helpers::PredictiveProcessor.new
+        end
+
+        private
+
+        attr_reader :default_processor
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module PredictiveProcessing
+      module Helpers
+        module Constants
+          MAX_MODELS                  = 20
+          MAX_PREDICTIONS_PER_MODEL   = 50
+          MAX_HISTORY                 = 200
+          DEFAULT_PRECISION           = 0.5
+          PRECISION_FLOOR             = 0.05
+          PRECISION_DECAY             = 0.02
+          MODEL_CONFIDENCE_FLOOR      = 0.1
+          FREE_ENERGY_THRESHOLD       = 0.7
+          ACTIVE_INFERENCE_THRESHOLD  = 0.5
+          LEARNING_RATE               = 0.1
+          INFERENCE_MODES             = %i[perceptual active hybrid].freeze
+          MODEL_STATES                = %i[stable updating exploring surprised].freeze
+          PRECISION_LABELS            = {
+            (0.8..)     => :certain,
+            (0.6...0.8) => :confident,
+            (0.4...0.6) => :uncertain,
+            (0.2...0.4) => :vague,
+            (..0.2)     => :noise
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/predictive_processing/helpers/generative_model.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module PredictiveProcessing
+      module Helpers
+        class GenerativeModel
+          include Constants
+
+          attr_reader :id, :domain, :confidence, :precision, :prediction_error, :state,
+                      :last_prediction, :created_at, :updated_at
+
+          def initialize(domain:)
+            @id               = SecureRandom.uuid
+            @domain           = domain
+            @confidence       = DEFAULT_PRECISION
+            @precision        = DEFAULT_PRECISION
+            @prediction_error = 0.0
+            @state            = :stable
+            @history          = []
+            @last_prediction  = nil
+            @created_at       = Time.now.utc
+            @updated_at       = Time.now.utc
+          end
+
+          def predict(context: {})
+            richness     = context_richness(context)
+            expected_val = (confidence + richness).clamp(0.0, 1.0)
+            @last_prediction = {
+              expected_value: expected_val,
+              confidence:     confidence,
+              precision:      precision,
+              domain:         @domain,
+              context_size:   context.size,
+              predicted_at:   Time.now.utc
+            }
+          end
+
+          def observe(actual:, predicted:)
+            @prediction_error = compute_error(actual, predicted)
+            update_history(@prediction_error)
+            update_confidence
+            update_state
+            @updated_at = Time.now.utc
+            @prediction_error
+          end
+
+          # Free energy (surprise): high when errors are large relative to precision.
+          # Uses a formula that can exceed FREE_ENERGY_THRESHOLD (0.7) with sustained errors.
+          def free_energy
+            return 0.0 if @history.empty?
+
+            recent    = @history.last(10)
+            avg_error = recent.sum.to_f / recent.size
+            raw       = avg_error * (1.5 - (precision * 0.5))
+            raw.clamp(0.0, 1.0)
+          end
+
+          def update_model(error:)
+            adjustment = error * LEARNING_RATE * precision
+            @confidence = (@confidence - adjustment).clamp(MODEL_CONFIDENCE_FLOOR, 1.0)
+            @state      = :updating
+            @updated_at = Time.now.utc
+          end
+
+          def stable?
+            free_energy <= FREE_ENERGY_THRESHOLD
+          end
+
+          def surprised?
+            free_energy > FREE_ENERGY_THRESHOLD
+          end
+
+          def decay
+            @precision = [@precision - PRECISION_DECAY, PRECISION_FLOOR].max
+            @updated_at = Time.now.utc
+          end
+
+          def precision_label
+            PRECISION_LABELS.find { |range, _label| range.cover?(precision) }&.last || :noise
+          end
+
+          def to_h
+            {
+              id:               @id,
+              domain:           @domain,
+              confidence:       confidence,
+              precision:        precision,
+              prediction_error: @prediction_error,
+              free_energy:      free_energy,
+              state:            @state,
+              precision_label:  precision_label,
+              stable:           stable?,
+              surprised:        surprised?,
+              history_size:     @history.size,
+              created_at:       @created_at,
+              updated_at:       @updated_at
+            }
+          end
+
+          private
+
+          def context_richness(context)
+            [context.size * 0.02, 0.2].min
+          end
+
+          def compute_error(actual, predicted)
+            return 0.0 unless actual.is_a?(Numeric) && predicted.is_a?(Numeric)
+
+            (actual - predicted).abs.clamp(0.0, 1.0)
+          end
+
+          def update_history(error)
+            @history << error
+            @history.shift while @history.size > MAX_HISTORY
+          end
+
+          def update_confidence
+            delta = -@prediction_error * LEARNING_RATE
+            @confidence = (@confidence + delta).clamp(MODEL_CONFIDENCE_FLOOR, 1.0)
+          end
+
+          def update_state
+            @state = if surprised?
+                       :surprised
+                     elsif @history.size < 5
+                       :exploring
+                     else
+                       :stable
+                     end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/predictive_processing/helpers/predictive_processor.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module PredictiveProcessing
+      module Helpers
+        class PredictiveProcessor
+          include Constants
+
+          attr_reader :models
+
+          def initialize
+            @models = {}
+          end
+
+          def add_model(domain:)
+            return { added: false, reason: :limit_reached } if @models.size >= MAX_MODELS
+            return { added: false, reason: :already_exists } if @models.key?(domain)
+
+            model = GenerativeModel.new(domain: domain)
+            @models[domain] = model
+            { added: true, domain: domain, model_id: model.id }
+          end
+
+          def predict(domain:, context: {})
+            model = find_or_create(domain)
+            model.predict(context: context)
+          end
+
+          def observe(domain:, actual:, predicted:)
+            model = @models[domain]
+            return { observed: false, reason: :domain_not_found } unless model
+
+            error = model.observe(actual: actual, predicted: predicted)
+            mode  = inference_mode(domain)
+
+            model.update_model(error: error) if %i[perceptual hybrid].include?(mode)
+
+            {
+              observed:         true,
+              domain:           domain,
+              prediction_error: error,
+              inference_mode:   mode,
+              free_energy:      model.free_energy,
+              state:            model.state
+            }
+          end
+
+          def inference_mode(domain)
+            model = @models[domain]
+            return :perceptual unless model
+
+            fe = model.free_energy
+            determine_mode(fe, model.precision)
+          end
+
+          def free_energy_for(domain)
+            model = @models[domain]
+            model&.free_energy
+          end
+
+          def global_free_energy
+            return 0.0 if @models.empty?
+
+            total = @models.values.sum(&:free_energy)
+            total / @models.size
+          end
+
+          def precision_weight(domain)
+            model = @models[domain]
+            model ? model.precision : DEFAULT_PRECISION
+          end
+
+          def models_needing_update
+            @models.select { |_d, m| m.surprised? }.transform_values(&:to_h)
+          end
+
+          def stable_models
+            @models.select { |_d, m| m.stable? }.transform_values(&:to_h)
+          end
+
+          def active_inference_candidates
+            @models.select { |_d, m| m.free_energy > ACTIVE_INFERENCE_THRESHOLD }
+                   .keys
+          end
+
+          def tick
+            @models.each_value(&:decay)
+          end
+
+          def to_h
+            {
+              model_count:              @models.size,
+              global_free_energy:       global_free_energy,
+              models_needing_update:    models_needing_update.size,
+              stable_model_count:       stable_models.size,
+              active_inference_domains: active_inference_candidates.size,
+              models:                   @models.transform_values(&:to_h)
+            }
+          end
+
+          private
+
+          def find_or_create(domain)
+            @models[domain] ||= begin
+              model           = GenerativeModel.new(domain: domain)
+              @models[domain] = model if @models.size < MAX_MODELS
+              model
+            end
+          end
+
+          def determine_mode(free_energy, precision)
+            if free_energy > FREE_ENERGY_THRESHOLD && precision >= ACTIVE_INFERENCE_THRESHOLD
+              :hybrid
+            elsif free_energy > ACTIVE_INFERENCE_THRESHOLD
+              :active
+            else
+              :perceptual
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module PredictiveProcessing
+      module Runners
+        module PredictiveProcessing
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def add_generative_model(domain:, **)
+            return { added: false, reason: :missing_domain } if domain.nil? || domain.to_s.strip.empty?
+
+            result = default_processor.add_model(domain: domain.to_sym)
+            Legion::Logging.debug "[predictive_processing] add_model domain=#{domain} added=#{result[:added]}"
+            result
+          end
+
+          def predict_from_model(domain:, context: {}, **)
+            return { predicted: false, reason: :missing_domain } if domain.nil?
+
+            prediction = default_processor.predict(domain: domain.to_sym, context: context)
+            Legion::Logging.debug "[predictive_processing] predict domain=#{domain} " \
+                                  "expected=#{prediction[:expected_value]&.round(3)}"
+            { predicted: true, domain: domain, prediction: prediction }
+          end
+
+          def observe_outcome(domain:, actual:, predicted:, **)
+            return { observed: false, reason: :missing_domain } if domain.nil?
+
+            result = default_processor.observe(
+              domain:    domain.to_sym,
+              actual:    actual,
+              predicted: predicted
+            )
+            log_observe(domain, result)
+            result
+          end
+
+          def inference_mode(domain:, **)
+            return { mode: nil, reason: :missing_domain } if domain.nil?
+
+            mode = default_processor.inference_mode(domain.to_sym)
+            Legion::Logging.debug "[predictive_processing] inference_mode domain=#{domain} mode=#{mode}"
+            { domain: domain, mode: mode }
+          end
+
+          def free_energy(domain: nil, **)
+            if domain
+              fe = default_processor.free_energy_for(domain.to_sym)
+              return { domain: domain, free_energy: nil, reason: :domain_not_found } if fe.nil?
+
+              { domain: domain, free_energy: fe }
+            else
+              { global_free_energy: default_processor.global_free_energy }
+            end
+          end
+
+          def models_needing_update(**)
+            needing = default_processor.models_needing_update
+            Legion::Logging.debug "[predictive_processing] models_needing_update count=#{needing.size}"
+            { count: needing.size, models: needing }
+          end
+
+          def active_inference_candidates(**)
+            candidates = default_processor.active_inference_candidates
+            Legion::Logging.debug "[predictive_processing] active_inference_candidates count=#{candidates.size}"
+            { count: candidates.size, domains: candidates }
+          end
+
+          def update_predictive_processing(**)
+            default_processor.tick
+            Legion::Logging.debug '[predictive_processing] tick: precision decayed on all models'
+            { ticked: true, model_count: default_processor.models.size }
+          end
+
+          def predictive_processing_stats(**)
+            stats = default_processor.to_h
+            Legion::Logging.debug "[predictive_processing] stats global_fe=#{stats[:global_free_energy]&.round(3)}"
+            { success: true, stats: stats }
+          end
+
+          private
+
+          def default_processor
+            @default_processor ||= Helpers::PredictiveProcessor.new
+          end
+
+          def log_observe(domain, result)
+            return unless result[:observed]
+
+            Legion::Logging.debug "[predictive_processing] observe domain=#{domain} " \
+                                  "error=#{result[:prediction_error]&.round(3)} " \
+                                  "mode=#{result[:inference_mode]}"
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/predictive_processing.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/predictive_processing/version'
+require 'legion/extensions/predictive_processing/helpers/constants'
+require 'legion/extensions/predictive_processing/helpers/generative_model'
+require 'legion/extensions/predictive_processing/helpers/predictive_processor'
+require 'legion/extensions/predictive_processing/runners/predictive_processing'
+
+module Legion
+  module Extensions
+    module PredictiveProcessing
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::PredictiveProcessing::Client do
+  subject(:client) { described_class.new }
+
+  describe '#initialize' do
+    it 'creates a client with a default processor' do
+      expect(client).to be_a(described_class)
+    end
+
+    it 'accepts an injected processor' do
+      processor = Legion::Extensions::PredictiveProcessing::Helpers::PredictiveProcessor.new
+      injected  = described_class.new(processor: processor)
+      result    = injected.predictive_processing_stats
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe 'full workflow: add -> predict -> observe -> stats' do
+    it 'completes a full predictive processing cycle' do
+      client.add_generative_model(domain: :workflow)
+      prediction = client.predict_from_model(domain: :workflow, context: { step: 1 })
+      expect(prediction[:predicted]).to be true
+
+      expected_val = prediction[:prediction][:expected_value]
+      obs          = client.observe_outcome(domain: :workflow, actual: 0.8, predicted: expected_val)
+      expect(obs[:observed]).to be true
+
+      stats = client.predictive_processing_stats
+      expect(stats[:stats][:model_count]).to eq(1)
+    end
+
+    it 'accumulates free energy after repeated high errors' do
+      client.add_generative_model(domain: :stress)
+      5.times { client.observe_outcome(domain: :stress, actual: 1.0, predicted: 0.0) }
+      fe = client.free_energy(domain: :stress)
+      expect(fe[:free_energy]).to be > 0.0
+    end
+
+    it 'identifies active inference candidate after surprise' do
+      client.add_generative_model(domain: :act_candidate)
+      5.times { client.observe_outcome(domain: :act_candidate, actual: 1.0, predicted: 0.0) }
+      result = client.active_inference_candidates
+      expect(result[:domains]).to include(:act_candidate)
+    end
+
+    it 'tick decays precision over time' do
+      client.add_generative_model(domain: :decaying)
+      initial_weight = client.instance_variable_get(:@default_processor).precision_weight(:decaying)
+      client.update_predictive_processing
+      after_weight = client.instance_variable_get(:@default_processor).precision_weight(:decaying)
+      expect(after_weight).to be < initial_weight
+    end
+  end
+
+  describe 'constants' do
+    it 'exposes INFERENCE_MODES' do
+      expect(Legion::Extensions::PredictiveProcessing::Helpers::Constants::INFERENCE_MODES)
+        .to eq(%i[perceptual active hybrid])
+    end
+
+    it 'exposes MODEL_STATES' do
+      expect(Legion::Extensions::PredictiveProcessing::Helpers::Constants::MODEL_STATES)
+        .to eq(%i[stable updating exploring surprised])
+    end
+
+    it 'exposes FREE_ENERGY_THRESHOLD' do
+      expect(Legion::Extensions::PredictiveProcessing::Helpers::Constants::FREE_ENERGY_THRESHOLD)
+        .to eq(0.7)
+    end
+
+    it 'exposes ACTIVE_INFERENCE_THRESHOLD' do
+      expect(Legion::Extensions::PredictiveProcessing::Helpers::Constants::ACTIVE_INFERENCE_THRESHOLD)
+        .to eq(0.5)
+    end
+
+    it 'exposes all PRECISION_LABELS keys as ranges' do
+      labels = Legion::Extensions::PredictiveProcessing::Helpers::Constants::PRECISION_LABELS
+      expect(labels.values).to include(:certain, :confident, :uncertain, :vague, :noise)
+    end
+  end
+end

data/spec/legion/extensions/predictive_processing/helpers/generative_model_spec.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::PredictiveProcessing::Helpers::GenerativeModel do
+  subject(:model) { described_class.new(domain: :test_domain) }
+
+  describe '#initialize' do
+    it 'assigns a unique id' do
+      expect(model.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets domain' do
+      expect(model.domain).to eq(:test_domain)
+    end
+
+    it 'sets default confidence' do
+      expect(model.confidence).to eq(described_class::DEFAULT_PRECISION)
+    end
+
+    it 'sets default precision' do
+      expect(model.precision).to eq(described_class::DEFAULT_PRECISION)
+    end
+
+    it 'starts with zero prediction error' do
+      expect(model.prediction_error).to eq(0.0)
+    end
+
+    it 'starts in stable state' do
+      expect(model.state).to eq(:stable)
+    end
+
+    it 'records created_at timestamp' do
+      expect(model.created_at).to be_a(Time)
+    end
+
+    it 'records updated_at timestamp' do
+      expect(model.updated_at).to be_a(Time)
+    end
+  end
+
+  describe '#predict' do
+    it 'returns a prediction hash' do
+      result = model.predict(context: {})
+      expect(result).to be_a(Hash)
+    end
+
+    it 'includes expected_value' do
+      result = model.predict(context: {})
+      expect(result[:expected_value]).to be_a(Float)
+    end
+
+    it 'includes confidence' do
+      result = model.predict(context: {})
+      expect(result[:confidence]).to eq(model.confidence)
+    end
+
+    it 'includes domain' do
+      result = model.predict(context: {})
+      expect(result[:domain]).to eq(:test_domain)
+    end
+
+    it 'applies context richness bonus' do
+      sparse_pred = model.predict(context: {})
+      rich_pred   = model.predict(context: { a: 1, b: 2, c: 3, d: 4, e: 5 })
+      expect(rich_pred[:expected_value]).to be >= sparse_pred[:expected_value]
+    end
+
+    it 'caps expected_value at 1.0' do
+      result = model.predict(context: (1..20).to_h { |i| [i, i] })
+      expect(result[:expected_value]).to be <= 1.0
+    end
+
+    it 'stores the prediction as last_prediction' do
+      model.predict(context: { key: :val })
+      expect(model.last_prediction).not_to be_nil
+    end
+
+    it 'uses default empty context when none provided' do
+      result = model.predict
+      expect(result[:context_size]).to eq(0)
+    end
+  end
+
+  describe '#observe' do
+    it 'returns a numeric error magnitude' do
+      error = model.observe(actual: 0.8, predicted: 0.5)
+      expect(error).to be_a(Float)
+    end
+
+    it 'computes absolute difference' do
+      error = model.observe(actual: 0.8, predicted: 0.5)
+      expect(error).to be_within(0.01).of(0.3)
+    end
+
+    it 'clamps error to 0..1' do
+      error = model.observe(actual: 5.0, predicted: 0.0)
+      expect(error).to eq(1.0)
+    end
+
+    it 'returns 0.0 for non-numeric inputs' do
+      error = model.observe(actual: 'abc', predicted: 0.5)
+      expect(error).to eq(0.0)
+    end
+
+    it 'updates updated_at' do
+      before = model.updated_at
+      sleep(0.01)
+      model.observe(actual: 0.9, predicted: 0.1)
+      expect(model.updated_at).to be >= before
+    end
+  end
+
+  describe '#free_energy' do
+    it 'returns 0.0 with no history' do
+      expect(model.free_energy).to eq(0.0)
+    end
+
+    it 'returns a positive value after observations' do
+      model.observe(actual: 1.0, predicted: 0.0)
+      expect(model.free_energy).to be >= 0.0
+    end
+
+    it 'returns higher free energy for larger errors' do
+      low_model  = described_class.new(domain: :low)
+      high_model = described_class.new(domain: :high)
+      low_model.observe(actual: 0.51, predicted: 0.5)
+      high_model.observe(actual: 1.0, predicted: 0.0)
+      expect(high_model.free_energy).to be > low_model.free_energy
+    end
+  end
+
+  describe '#stable?' do
+    it 'returns true when free_energy is low' do
+      expect(model.stable?).to be true
+    end
+
+    it 'returns false when surprised' do
+      5.times { model.observe(actual: 1.0, predicted: 0.0) }
+      expect(model.stable?).to be false
+    end
+  end
+
+  describe '#surprised?' do
+    it 'returns false initially' do
+      expect(model.surprised?).to be false
+    end
+
+    it 'returns true after repeated large errors' do
+      5.times { model.observe(actual: 1.0, predicted: 0.0) }
+      expect(model.surprised?).to be true
+    end
+  end
+
+  describe '#update_model' do
+    it 'adjusts confidence downward on positive error' do
+      before = model.confidence
+      model.update_model(error: 0.5)
+      expect(model.confidence).to be < before
+    end
+
+    it 'does not drop confidence below MODEL_CONFIDENCE_FLOOR' do
+      10.times { model.update_model(error: 1.0) }
+      expect(model.confidence).to be >= described_class::MODEL_CONFIDENCE_FLOOR
+    end
+
+    it 'sets state to updating' do
+      model.update_model(error: 0.3)
+      expect(model.state).to eq(:updating)
+    end
+  end
+
+  describe '#decay' do
+    it 'reduces precision' do
+      before = model.precision
+      model.decay
+      expect(model.precision).to be < before
+    end
+
+    it 'does not drop precision below PRECISION_FLOOR' do
+      100.times { model.decay }
+      expect(model.precision).to be >= described_class::PRECISION_FLOOR
+    end
+  end
+
+  describe '#precision_label' do
+    it 'returns :uncertain for default precision (0.5)' do
+      expect(model.precision_label).to eq(:uncertain)
+    end
+
+    it 'returns :certain for high precision' do
+      allow(model).to receive(:precision).and_return(0.9)
+      expect(model.precision_label).to eq(:certain)
+    end
+
+    it 'returns :noise for very low precision' do
+      allow(model).to receive(:precision).and_return(0.1)
+      expect(model.precision_label).to eq(:noise)
+    end
+
+    it 'returns :vague for precision around 0.3' do
+      allow(model).to receive(:precision).and_return(0.3)
+      expect(model.precision_label).to eq(:vague)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with all required keys' do
+      h = model.to_h
+      %i[id domain confidence precision prediction_error free_energy state
+         precision_label stable surprised history_size created_at updated_at].each do |key|
+        expect(h).to have_key(key)
+      end
+    end
+
+    it 'reflects current model state' do
+      model.observe(actual: 0.8, predicted: 0.3)
+      h = model.to_h
+      expect(h[:history_size]).to eq(1)
+    end
+  end
+end

data/spec/legion/extensions/predictive_processing/helpers/predictive_processor_spec.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::PredictiveProcessing::Helpers::PredictiveProcessor do
+  subject(:processor) { described_class.new }
+
+  describe '#add_model' do
+    it 'adds a new model for a domain' do
+      result = processor.add_model(domain: :perception)
+      expect(result[:added]).to be true
+      expect(result[:domain]).to eq(:perception)
+    end
+
+    it 'returns model_id on success' do
+      result = processor.add_model(domain: :cognition)
+      expect(result[:model_id]).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'rejects duplicate domains' do
+      processor.add_model(domain: :dup)
+      result = processor.add_model(domain: :dup)
+      expect(result[:added]).to be false
+      expect(result[:reason]).to eq(:already_exists)
+    end
+
+    it 'rejects when at model limit' do
+      20.times { |i| processor.add_model(domain: :"domain_#{i}") }
+      result = processor.add_model(domain: :overflow)
+      expect(result[:added]).to be false
+      expect(result[:reason]).to eq(:limit_reached)
+    end
+  end
+
+  describe '#predict' do
+    it 'returns a prediction hash for a known domain' do
+      processor.add_model(domain: :action)
+      result = processor.predict(domain: :action, context: { urgency: 0.8 })
+      expect(result[:expected_value]).to be_a(Float)
+    end
+
+    it 'auto-creates model for unknown domain (within limit)' do
+      result = processor.predict(domain: :new_domain, context: {})
+      expect(result[:expected_value]).to be_a(Float)
+    end
+
+    it 'includes domain in prediction' do
+      result = processor.predict(domain: :emotion, context: {})
+      expect(result[:domain]).to eq(:emotion)
+    end
+  end
+
+  describe '#observe' do
+    before { processor.add_model(domain: :vision) }
+
+    it 'returns observed: true for known domain' do
+      result = processor.observe(domain: :vision, actual: 0.7, predicted: 0.5)
+      expect(result[:observed]).to be true
+    end
+
+    it 'returns prediction_error' do
+      result = processor.observe(domain: :vision, actual: 0.8, predicted: 0.5)
+      expect(result[:prediction_error]).to be_a(Float)
+    end
+
+    it 'returns inference_mode' do
+      result = processor.observe(domain: :vision, actual: 0.8, predicted: 0.5)
+      expect(described_class::INFERENCE_MODES).to include(result[:inference_mode])
+    end
+
+    it 'returns observed: false for unknown domain' do
+      result = processor.observe(domain: :unknown, actual: 0.5, predicted: 0.5)
+      expect(result[:observed]).to be false
+      expect(result[:reason]).to eq(:domain_not_found)
+    end
+
+    it 'returns free_energy after observation' do
+      result = processor.observe(domain: :vision, actual: 1.0, predicted: 0.0)
+      expect(result[:free_energy]).to be_a(Float)
+    end
+  end
+
+  describe '#inference_mode' do
+    it 'returns :perceptual for unknown domain' do
+      expect(processor.inference_mode(:nonexistent)).to eq(:perceptual)
+    end
+
+    it 'returns a valid inference mode for known domain' do
+      processor.add_model(domain: :memory)
+      mode = processor.inference_mode(:memory)
+      expect(described_class::INFERENCE_MODES).to include(mode)
+    end
+
+    it 'returns :active or :hybrid when free energy is high' do
+      processor.add_model(domain: :surprise)
+      5.times { processor.observe(domain: :surprise, actual: 1.0, predicted: 0.0) }
+      mode = processor.inference_mode(:surprise)
+      expect(%i[active hybrid]).to include(mode)
+    end
+  end
+
+  describe '#free_energy_for' do
+    it 'returns nil for unknown domain' do
+      expect(processor.free_energy_for(:unknown)).to be_nil
+    end
+
+    it 'returns a float for known domain' do
+      processor.add_model(domain: :planning)
+      expect(processor.free_energy_for(:planning)).to be_a(Float)
+    end
+  end
+
+  describe '#global_free_energy' do
+    it 'returns 0.0 with no models' do
+      expect(processor.global_free_energy).to eq(0.0)
+    end
+
+    it 'returns average free energy across models' do
+      processor.add_model(domain: :d1)
+      processor.add_model(domain: :d2)
+      expect(processor.global_free_energy).to be_a(Float)
+    end
+  end
+
+  describe '#precision_weight' do
+    it 'returns DEFAULT_PRECISION for unknown domain' do
+      expect(processor.precision_weight(:unknown)).to eq(described_class::DEFAULT_PRECISION)
+    end
+
+    it 'returns model precision for known domain' do
+      processor.add_model(domain: :known)
+      expect(processor.precision_weight(:known)).to be_a(Float)
+    end
+  end
+
+  describe '#models_needing_update' do
+    it 'returns empty hash when all models are stable' do
+      expect(processor.models_needing_update).to be_empty
+    end
+
+    it 'returns domains with high free energy' do
+      processor.add_model(domain: :erratic)
+      5.times { processor.observe(domain: :erratic, actual: 1.0, predicted: 0.0) }
+      needing = processor.models_needing_update
+      expect(needing).to have_key(:erratic)
+    end
+  end
+
+  describe '#stable_models' do
+    it 'returns all models initially (all stable)' do
+      processor.add_model(domain: :calm)
+      expect(processor.stable_models).to have_key(:calm)
+    end
+
+    it 'excludes surprised models' do
+      processor.add_model(domain: :upset)
+      5.times { processor.observe(domain: :upset, actual: 1.0, predicted: 0.0) }
+      expect(processor.stable_models).not_to have_key(:upset)
+    end
+  end
+
+  describe '#active_inference_candidates' do
+    it 'returns empty array when all models have low free energy' do
+      expect(processor.active_inference_candidates).to be_empty
+    end
+
+    it 'returns domains exceeding active inference threshold' do
+      processor.add_model(domain: :high_fe)
+      5.times { processor.observe(domain: :high_fe, actual: 1.0, predicted: 0.0) }
+      expect(processor.active_inference_candidates).to include(:high_fe)
+    end
+  end
+
+  describe '#tick' do
+    it 'decays precision on all models' do
+      processor.add_model(domain: :tickable)
+      before = processor.models[:tickable].precision
+      processor.tick
+      expect(processor.models[:tickable].precision).to be < before
+    end
+
+    it 'does not raise with no models' do
+      expect { processor.tick }.not_to raise_error
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes model_count' do
+      processor.add_model(domain: :counted)
+      expect(processor.to_h[:model_count]).to eq(1)
+    end
+
+    it 'includes global_free_energy' do
+      expect(processor.to_h[:global_free_energy]).to be_a(Float)
+    end
+
+    it 'includes models hash' do
+      processor.add_model(domain: :listed)
+      expect(processor.to_h[:models]).to have_key(:listed)
+    end
+
+    it 'includes counts for needing update and stable' do
+      h = processor.to_h
+      expect(h).to have_key(:models_needing_update)
+      expect(h).to have_key(:stable_model_count)
+    end
+  end
+end

data/spec/legion/extensions/predictive_processing/runners/predictive_processing_spec.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::PredictiveProcessing::Runners::PredictiveProcessing do
+  let(:client) { Legion::Extensions::PredictiveProcessing::Client.new }
+
+  describe '#add_generative_model' do
+    it 'adds a model for a valid domain' do
+      result = client.add_generative_model(domain: :perception)
+      expect(result[:added]).to be true
+      expect(result[:domain]).to eq(:perception)
+    end
+
+    it 'returns error for nil domain' do
+      result = client.add_generative_model(domain: nil)
+      expect(result[:added]).to be false
+      expect(result[:reason]).to eq(:missing_domain)
+    end
+
+    it 'returns error for empty string domain' do
+      result = client.add_generative_model(domain: '')
+      expect(result[:added]).to be false
+      expect(result[:reason]).to eq(:missing_domain)
+    end
+
+    it 'returns model_id on success' do
+      result = client.add_generative_model(domain: :with_id)
+      expect(result[:model_id]).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'rejects duplicate domain' do
+      client.add_generative_model(domain: :dup)
+      result = client.add_generative_model(domain: :dup)
+      expect(result[:added]).to be false
+      expect(result[:reason]).to eq(:already_exists)
+    end
+  end
+
+  describe '#predict_from_model' do
+    before { client.add_generative_model(domain: :action) }
+
+    it 'returns a prediction for known domain' do
+      result = client.predict_from_model(domain: :action, context: {})
+      expect(result[:predicted]).to be true
+    end
+
+    it 'includes domain in result' do
+      result = client.predict_from_model(domain: :action)
+      expect(result[:domain]).to eq(:action)
+    end
+
+    it 'includes prediction hash' do
+      result = client.predict_from_model(domain: :action, context: { val: 1 })
+      expect(result[:prediction]).to be_a(Hash)
+      expect(result[:prediction][:expected_value]).to be_a(Float)
+    end
+
+    it 'returns error for nil domain' do
+      result = client.predict_from_model(domain: nil)
+      expect(result[:predicted]).to be false
+      expect(result[:reason]).to eq(:missing_domain)
+    end
+
+    it 'auto-creates model for unknown domain' do
+      result = client.predict_from_model(domain: :auto_created, context: {})
+      expect(result[:predicted]).to be true
+    end
+  end
+
+  describe '#observe_outcome' do
+    before { client.add_generative_model(domain: :vision) }
+
+    it 'returns observed: true for known domain' do
+      result = client.observe_outcome(domain: :vision, actual: 0.7, predicted: 0.5)
+      expect(result[:observed]).to be true
+    end
+
+    it 'includes inference_mode' do
+      result = client.observe_outcome(domain: :vision, actual: 0.6, predicted: 0.5)
+      expect(Legion::Extensions::PredictiveProcessing::Helpers::Constants::INFERENCE_MODES)
+        .to include(result[:inference_mode])
+    end
+
+    it 'returns error for nil domain' do
+      result = client.observe_outcome(domain: nil, actual: 0.5, predicted: 0.5)
+      expect(result[:observed]).to be false
+      expect(result[:reason]).to eq(:missing_domain)
+    end
+
+    it 'returns false for unknown domain' do
+      result = client.observe_outcome(domain: :unknown_x, actual: 0.5, predicted: 0.5)
+      expect(result[:observed]).to be false
+    end
+
+    it 'includes free_energy in result' do
+      result = client.observe_outcome(domain: :vision, actual: 0.9, predicted: 0.1)
+      expect(result[:free_energy]).to be_a(Float)
+    end
+  end
+
+  describe '#inference_mode' do
+    it 'returns mode for known domain' do
+      client.add_generative_model(domain: :motor)
+      result = client.inference_mode(domain: :motor)
+      expect(result[:domain]).to eq(:motor)
+      expect(Legion::Extensions::PredictiveProcessing::Helpers::Constants::INFERENCE_MODES)
+        .to include(result[:mode])
+    end
+
+    it 'returns error for nil domain' do
+      result = client.inference_mode(domain: nil)
+      expect(result[:mode]).to be_nil
+      expect(result[:reason]).to eq(:missing_domain)
+    end
+
+    it 'returns :perceptual for unknown domain' do
+      result = client.inference_mode(domain: :unregistered)
+      expect(result[:mode]).to eq(:perceptual)
+    end
+  end
+
+  describe '#free_energy' do
+    it 'returns global free energy when no domain given' do
+      result = client.free_energy
+      expect(result).to have_key(:global_free_energy)
+    end
+
+    it 'returns domain free energy when domain given' do
+      client.add_generative_model(domain: :fe_domain)
+      result = client.free_energy(domain: :fe_domain)
+      expect(result[:domain]).to eq(:fe_domain)
+      expect(result[:free_energy]).to be_a(Float)
+    end
+
+    it 'returns not_found for unknown domain' do
+      result = client.free_energy(domain: :no_such)
+      expect(result[:reason]).to eq(:domain_not_found)
+    end
+  end
+
+  describe '#models_needing_update' do
+    it 'returns count and models hash' do
+      result = client.models_needing_update
+      expect(result).to have_key(:count)
+      expect(result).to have_key(:models)
+    end
+
+    it 'returns 0 when no models exist' do
+      expect(client.models_needing_update[:count]).to eq(0)
+    end
+
+    it 'returns surprised models' do
+      client.add_generative_model(domain: :volatile)
+      5.times { client.observe_outcome(domain: :volatile, actual: 1.0, predicted: 0.0) }
+      result = client.models_needing_update
+      expect(result[:count]).to be >= 1
+    end
+  end
+
+  describe '#active_inference_candidates' do
+    it 'returns count and domains array' do
+      result = client.active_inference_candidates
+      expect(result).to have_key(:count)
+      expect(result).to have_key(:domains)
+    end
+
+    it 'returns 0 when no high-free-energy models' do
+      expect(client.active_inference_candidates[:count]).to eq(0)
+    end
+
+    it 'includes domains with high free energy' do
+      client.add_generative_model(domain: :erratic)
+      5.times { client.observe_outcome(domain: :erratic, actual: 1.0, predicted: 0.0) }
+      result = client.active_inference_candidates
+      expect(result[:domains]).to include(:erratic)
+    end
+  end
+
+  describe '#update_predictive_processing' do
+    it 'ticks the processor' do
+      result = client.update_predictive_processing
+      expect(result[:ticked]).to be true
+    end
+
+    it 'reports model count' do
+      client.add_generative_model(domain: :tracked)
+      result = client.update_predictive_processing
+      expect(result[:model_count]).to eq(1)
+    end
+  end
+
+  describe '#predictive_processing_stats' do
+    it 'returns success: true' do
+      result = client.predictive_processing_stats
+      expect(result[:success]).to be true
+    end
+
+    it 'returns stats hash' do
+      result = client.predictive_processing_stats
+      expect(result[:stats]).to be_a(Hash)
+    end
+
+    it 'includes global_free_energy in stats' do
+      result = client.predictive_processing_stats
+      expect(result[:stats]).to have_key(:global_free_energy)
+    end
+
+    it 'reflects added models in stats' do
+      client.add_generative_model(domain: :counted)
+      result = client.predictive_processing_stats
+      expect(result[:stats][:model_count]).to eq(1)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/predictive_processing/helpers/constants'
+require 'legion/extensions/predictive_processing/helpers/generative_model'
+require 'legion/extensions/predictive_processing/helpers/predictive_processor'
+require 'legion/extensions/predictive_processing/runners/predictive_processing'
+require 'legion/extensions/predictive_processing/client'
+
+module Legion
+  module Extensions
+    module Helpers
+      module Lex; end
+    end
+  end
+end
+
+module Legion
+  module Logging
+    def self.method_missing(*); end
+
+    def self.respond_to_missing?(*) = true
+  end
+end
+
+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-predictive-processing
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Esity
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: legion-gaia
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 'Andy Clark''s Predictive Processing / Active Inference for brain-modeled
+  agentic AI: generative models, precision-weighting, active inference, and free energy
+  minimization'
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-predictive-processing.gemspec
+- lib/legion/extensions/predictive_processing.rb
+- lib/legion/extensions/predictive_processing/client.rb
+- lib/legion/extensions/predictive_processing/helpers/constants.rb
+- lib/legion/extensions/predictive_processing/helpers/generative_model.rb
+- lib/legion/extensions/predictive_processing/helpers/predictive_processor.rb
+- lib/legion/extensions/predictive_processing/runners/predictive_processing.rb
+- lib/legion/extensions/predictive_processing/version.rb
+- spec/legion/extensions/predictive_processing/client_spec.rb
+- spec/legion/extensions/predictive_processing/helpers/generative_model_spec.rb
+- spec/legion/extensions/predictive_processing/helpers/predictive_processor_spec.rb
+- spec/legion/extensions/predictive_processing/runners/predictive_processing_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-predictive-processing
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-predictive-processing
+  source_code_uri: https://github.com/LegionIO/lex-predictive-processing
+  documentation_uri: https://github.com/LegionIO/lex-predictive-processing
+  changelog_uri: https://github.com/LegionIO/lex-predictive-processing
+  bug_tracker_uri: https://github.com/LegionIO/lex-predictive-processing/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 Predictive Processing
+test_files: []