lex-predictive-coding 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: be107566fcfb814bdea9f4857e1023b4cbf47ca1d2959126f28e518bf909b7f3
+  data.tar.gz: 9ce453e5312273b215249a6b2bf77456dfec0e2ec252e48bf60bf0e7377d34db
+SHA512:
+  metadata.gz: 2f79dd0c0450927598f12c3f16e15001feeadf8f5582817420634579259d40d6be233491dff9d3546a3435f1ad5d0236b55ec44bff64ac313c3d936031cac84a
+  data.tar.gz: d5c4493f99c551d3ce1bcd9062f8cc78e62bf775ef9ad61581be8acc405d6d8845a9b3cf2e751afedd6cbca0292a627800661dfea9b68854346bb3cd4e2fb1b4

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/predictive_coding/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-predictive-coding'
+  spec.version       = Legion::Extensions::PredictiveCoding::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Predictive Coding'
+  spec.description   = "Karl Friston's Free Energy Principle / Predictive Processing framework for brain-modeled agentic AI"
+  spec.homepage      = 'https://github.com/LegionIO/lex-predictive-coding'
+  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-coding'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-predictive-coding'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-predictive-coding'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-predictive-coding/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-predictive-coding.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/predictive_coding/helpers/constants'
+require 'legion/extensions/predictive_coding/helpers/prediction_error'
+require 'legion/extensions/predictive_coding/helpers/generative_model'
+require 'legion/extensions/predictive_coding/runners/predictive_coding'
+
+module Legion
+  module Extensions
+    module PredictiveCoding
+      class Client
+        include Runners::PredictiveCoding
+
+        def initialize(generative_model: nil, **)
+          @generative_model = generative_model || Helpers::GenerativeModel.new
+        end
+
+        private
+
+        attr_reader :generative_model
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module PredictiveCoding
+      module Helpers
+        module Constants
+          MAX_PREDICTIONS    = 200
+          MAX_ERROR_HISTORY  = 500
+          MAX_MODELS         = 20
+          DEFAULT_PRECISION  = 0.5
+          PRECISION_FLOOR    = 0.05
+          PRECISION_ALPHA    = 0.12  # EMA for precision updates
+          ERROR_ALPHA        = 0.15  # EMA for prediction error smoothing
+          MODEL_LEARNING_RATE = 0.1
+          FREE_ENERGY_ALPHA  = 0.1   # EMA for free energy tracking
+          COMPLEXITY_PENALTY = 0.05  # penalizes overly complex models
+          PREDICTION_DECAY   = 0.01
+          PRECISION_DECAY    = 0.005
+          MAX_ACTIVE_INFERENCES = 50
+          SURPRISE_THRESHOLD = 0.7   # above this, prediction error is "surprising"
+
+          PREDICTION_ERROR_LEVELS = {
+            negligible: 0.0..0.1,
+            low:        0.1..0.3,
+            moderate:   0.3..0.5,
+            high:       0.5..0.7,
+            surprising: 0.7..1.0
+          }.freeze
+
+          FREE_ENERGY_LEVELS = {
+            minimal:  0.0..0.2,
+            low:      0.2..0.4,
+            moderate: 0.4..0.6,
+            elevated: 0.6..0.8,
+            critical: 0.8..Float::INFINITY
+          }.freeze
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module PredictiveCoding
+      module Helpers
+        class GenerativeModel
+          attr_reader :model_id, :created_at
+
+          def initialize(model_id: nil)
+            @model_id        = model_id || SecureRandom.uuid
+            @created_at      = Time.now.utc
+            @predictions     = {}    # domain -> { value, confidence, updated_at }
+            @error_history   = []    # array of PredictionError objects (capped)
+            @precisions      = {}    # domain -> float (0..1)
+            @free_energy_ema = 0.0
+            @domain_models   = {}    # domain -> simple weighted mean tracker
+          end
+
+          def predict(domain:, context: {})
+            prior = @domain_models[domain]
+            if prior
+              confidence = @precisions.fetch(domain, Constants::DEFAULT_PRECISION)
+              value      = prior[:mean]
+            else
+              confidence = Constants::DEFAULT_PRECISION
+              value      = context[:expected] || context[:baseline] || 0.5
+            end
+
+            @predictions[domain] = { value: value, confidence: confidence, updated_at: Time.now.utc }
+
+            { domain: domain, predicted: value, confidence: confidence }
+          end
+
+          def update(domain:, predicted:, actual:)
+            precision = @precisions.fetch(domain, Constants::DEFAULT_PRECISION)
+            error     = PredictionError.new(domain: domain, predicted: predicted, actual: actual, precision: precision)
+
+            record_error(error)
+            update_precision(domain, error.error_magnitude)
+            update_domain_model(domain, actual)
+            update_free_energy(error.error_magnitude)
+
+            error
+          end
+
+          def precision_for(domain:)
+            @precisions.fetch(domain, Constants::DEFAULT_PRECISION)
+          end
+
+          def free_energy
+            prediction_error_term = average_weighted_error
+            complexity_term       = @domain_models.size * Constants::COMPLEXITY_PENALTY
+            @free_energy_ema      = ema(@free_energy_ema, prediction_error_term + complexity_term, Constants::FREE_ENERGY_ALPHA)
+            @free_energy_ema
+          end
+
+          def free_energy_level
+            fe = free_energy
+            Constants::FREE_ENERGY_LEVELS.find { |_k, range| range.cover?(fe) }&.first || :unknown
+          end
+
+          def active_inference_candidates
+            @domain_models.keys.select do |domain|
+              precision = @precisions.fetch(domain, Constants::DEFAULT_PRECISION)
+              recent_errors = recent_errors_for(domain)
+              next false if recent_errors.empty?
+
+              avg_error = recent_errors.sum(&:error_magnitude) / recent_errors.size
+              avg_error > Constants::SURPRISE_THRESHOLD && precision < 0.6
+            end
+          end
+
+          def surprising_errors
+            @error_history.select(&:surprising?)
+          end
+
+          def all_errors
+            @error_history
+          end
+
+          def decay_all
+            @precisions.each_key do |domain|
+              current = @precisions[domain]
+              decayed = [current - Constants::PRECISION_DECAY, Constants::PRECISION_FLOOR].max
+              @precisions[domain] = decayed
+            end
+
+            prune_old_errors
+          end
+
+          def domain_count
+            @domain_models.size
+          end
+
+          def error_count
+            @error_history.size
+          end
+
+          def to_h
+            {
+              model_id:          @model_id,
+              created_at:        @created_at,
+              domain_count:      @domain_models.size,
+              error_count:       @error_history.size,
+              free_energy:       free_energy.round(4),
+              free_energy_level: free_energy_level,
+              surprising_count:  surprising_errors.size,
+              domains:           domain_stats
+            }
+          end
+
+          private
+
+          def record_error(error)
+            @error_history << error
+            @error_history.shift while @error_history.size > Constants::MAX_ERROR_HISTORY
+          end
+
+          def update_precision(domain, error_magnitude)
+            current   = @precisions.fetch(domain, Constants::DEFAULT_PRECISION)
+            # High error -> precision decreases; low error -> precision increases
+            signal    = 1.0 - error_magnitude
+            updated   = ema(current, signal, Constants::PRECISION_ALPHA)
+            @precisions[domain] = [updated, Constants::PRECISION_FLOOR].max
+          end
+
+          def update_domain_model(domain, actual)
+            if @domain_models[domain]
+              model = @domain_models[domain]
+              model[:count] += 1
+              model[:mean] = ema(model[:mean], actual.to_f, Constants::MODEL_LEARNING_RATE)
+            else
+              @domain_models[domain] = { mean: actual.to_f, count: 1 }
+            end
+
+            return unless @domain_models.size > Constants::MAX_MODELS
+
+            oldest_domain = @domain_models.keys.first
+            @domain_models.delete(oldest_domain)
+            @precisions.delete(oldest_domain)
+          end
+
+          def update_free_energy(error_magnitude)
+            complexity = @domain_models.size * Constants::COMPLEXITY_PENALTY
+            raw        = error_magnitude + complexity
+            @free_energy_ema = ema(@free_energy_ema, raw, Constants::FREE_ENERGY_ALPHA)
+          end
+
+          def average_weighted_error
+            return 0.0 if @error_history.empty?
+
+            recent = @error_history.last(50)
+            recent.sum(&:weighted_error) / recent.size
+          end
+
+          def recent_errors_for(domain)
+            @error_history.select { |e| e.domain == domain }.last(10)
+          end
+
+          def prune_old_errors
+            @error_history.shift while @error_history.size > Constants::MAX_ERROR_HISTORY
+          end
+
+          def ema(current, new_value, alpha)
+            (alpha * new_value) + ((1.0 - alpha) * current)
+          end
+
+          def domain_stats
+            @domain_models.map do |domain, model|
+              {
+                domain:    domain,
+                mean:      model[:mean].round(4),
+                count:     model[:count],
+                precision: @precisions.fetch(domain, Constants::DEFAULT_PRECISION).round(4)
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/predictive_coding/helpers/prediction_error.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module PredictiveCoding
+      module Helpers
+        class PredictionError
+          attr_reader :domain, :predicted, :actual, :error_magnitude, :precision, :weighted_error, :timestamp
+
+          def initialize(domain:, predicted:, actual:, precision: Constants::DEFAULT_PRECISION)
+            @domain          = domain
+            @predicted       = predicted
+            @actual          = actual
+            @error_magnitude = compute_error_magnitude(predicted, actual)
+            @precision       = precision
+            @weighted_error  = @error_magnitude * @precision
+            @timestamp       = Time.now.utc
+          end
+
+          def surprising?
+            @error_magnitude >= Constants::SURPRISE_THRESHOLD
+          end
+
+          def level
+            Constants::PREDICTION_ERROR_LEVELS.find { |_k, range| range.cover?(@error_magnitude) }&.first || :unknown
+          end
+
+          def to_h
+            {
+              domain:          @domain,
+              predicted:       @predicted,
+              actual:          @actual,
+              error_magnitude: @error_magnitude,
+              precision:       @precision,
+              weighted_error:  @weighted_error,
+              surprising:      surprising?,
+              level:           level,
+              timestamp:       @timestamp
+            }
+          end
+
+          private
+
+          def compute_error_magnitude(predicted, actual)
+            if predicted.is_a?(Numeric) && actual.is_a?(Numeric)
+              (predicted - actual).abs.clamp(0.0, 1.0)
+            else
+              predicted == actual ? 0.0 : 1.0
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module PredictiveCoding
+      module Runners
+        module PredictiveCoding
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def generate_prediction(domain:, context: {}, **)
+            prediction = generative_model.predict(domain: domain, context: context)
+            Legion::Logging.debug "[predictive_coding] generate_prediction domain=#{domain} " \
+                                  "predicted=#{prediction[:predicted]} confidence=#{prediction[:confidence].round(3)}"
+            { success: true, domain: domain, predicted: prediction[:predicted], confidence: prediction[:confidence] }
+          end
+
+          def report_outcome(domain:, predicted:, actual:, **)
+            error = generative_model.update(domain: domain, predicted: predicted, actual: actual)
+            Legion::Logging.debug "[predictive_coding] report_outcome domain=#{domain} " \
+                                  "error_magnitude=#{error.error_magnitude.round(3)} surprising=#{error.surprising?}"
+            {
+              success:         true,
+              domain:          domain,
+              error_magnitude: error.error_magnitude,
+              weighted_error:  error.weighted_error,
+              precision:       error.precision,
+              surprising:      error.surprising?,
+              level:           error.level
+            }
+          end
+
+          def precision_for(domain:, **)
+            value = generative_model.precision_for(domain: domain)
+            Legion::Logging.debug "[predictive_coding] precision_for domain=#{domain} precision=#{value.round(3)}"
+            { success: true, domain: domain, precision: value }
+          end
+
+          def surprising_errors(**)
+            errors = generative_model.surprising_errors
+            Legion::Logging.debug "[predictive_coding] surprising_errors count=#{errors.size}"
+            { success: true, errors: errors.map(&:to_h), count: errors.size }
+          end
+
+          def free_energy_status(**)
+            fe    = generative_model.free_energy
+            level = generative_model.free_energy_level
+            Legion::Logging.debug "[predictive_coding] free_energy_status fe=#{fe.round(3)} level=#{level}"
+            {
+              success:     true,
+              free_energy: fe,
+              level:       level,
+              model_stats: generative_model.to_h
+            }
+          end
+
+          def active_inference_candidates(**)
+            candidates = generative_model.active_inference_candidates
+            Legion::Logging.debug "[predictive_coding] active_inference_candidates count=#{candidates.size}"
+            { success: true, candidates: candidates, count: candidates.size }
+          end
+
+          def register_active_inference(domain:, action:, expected_outcome:, **)
+            inference_id = SecureRandom.uuid
+            active_inferences[inference_id] = {
+              inference_id:     inference_id,
+              domain:           domain,
+              action:           action,
+              expected_outcome: expected_outcome,
+              status:           :pending,
+              registered_at:    Time.now.utc
+            }
+
+            prune_active_inferences
+
+            Legion::Logging.debug "[predictive_coding] register_active_inference domain=#{domain} id=#{inference_id[0..7]}"
+            { success: true, inference_id: inference_id, domain: domain, status: :pending }
+          end
+
+          def resolve_active_inference(domain:, action:, actual_outcome:, inference_id: nil, **)
+            record = find_inference(domain, action, inference_id)
+            unless record
+              Legion::Logging.debug "[predictive_coding] resolve_active_inference not found domain=#{domain}"
+              return { success: false, reason: :not_found }
+            end
+
+            expected = record[:expected_outcome]
+            error    = generative_model.update(
+              domain:    domain,
+              predicted: expected,
+              actual:    actual_outcome
+            )
+
+            record[:status]           = :resolved
+            record[:actual_outcome]   = actual_outcome
+            record[:resolved_at]      = Time.now.utc
+            record[:error_magnitude]  = error.error_magnitude
+
+            Legion::Logging.info "[predictive_coding] resolve_active_inference domain=#{domain} " \
+                                 "error=#{error.error_magnitude.round(3)} id=#{record[:inference_id][0..7]}"
+
+            {
+              success:         true,
+              inference_id:    record[:inference_id],
+              domain:          domain,
+              error_magnitude: error.error_magnitude,
+              action_helpful:  error.error_magnitude < Legion::Extensions::PredictiveCoding::Helpers::Constants::SURPRISE_THRESHOLD
+            }
+          end
+
+          def update_predictive_coding(**)
+            generative_model.decay_all
+            pruned = prune_resolved_inferences
+            Legion::Logging.debug "[predictive_coding] update_predictive_coding pruned_inferences=#{pruned}"
+            { success: true, pruned_inferences: pruned }
+          end
+
+          def predictive_coding_stats(**)
+            {
+              success:            true,
+              model:              generative_model.to_h,
+              active_inferences:  active_inferences.size,
+              pending_inferences: active_inferences.count { |_, v| v[:status] == :pending }
+            }
+          end
+
+          private
+
+          def generative_model
+            @generative_model ||= Helpers::GenerativeModel.new
+          end
+
+          def active_inferences
+            @active_inferences ||= {}
+          end
+
+          def prune_active_inferences
+            max = Legion::Extensions::PredictiveCoding::Helpers::Constants::MAX_ACTIVE_INFERENCES
+            return unless active_inferences.size > max
+
+            sorted    = active_inferences.sort_by { |_, v| v[:registered_at] }
+            ids       = sorted.first(active_inferences.size - max).map(&:first)
+            ids.each { |id| active_inferences.delete(id) }
+          end
+
+          def prune_resolved_inferences
+            resolved = active_inferences.select { |_, v| v[:status] == :resolved }.keys
+            resolved.each { |id| active_inferences.delete(id) }
+            resolved.size
+          end
+
+          def find_inference(domain, action, inference_id)
+            if inference_id
+              active_inferences[inference_id]
+            else
+              active_inferences.values.find do |r|
+                r[:domain] == domain && r[:action] == action && r[:status] == :pending
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/predictive_coding.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'legion/extensions/predictive_coding/version'
+require 'legion/extensions/predictive_coding/helpers/constants'
+require 'legion/extensions/predictive_coding/helpers/prediction_error'
+require 'legion/extensions/predictive_coding/helpers/generative_model'
+require 'legion/extensions/predictive_coding/runners/predictive_coding'
+
+module Legion
+  module Extensions
+    module PredictiveCoding
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/predictive_coding/client'
+
+RSpec.describe Legion::Extensions::PredictiveCoding::Client do
+  subject(:client) { described_class.new }
+
+  it 'responds to all runner methods' do
+    expect(client).to respond_to(:generate_prediction)
+    expect(client).to respond_to(:report_outcome)
+    expect(client).to respond_to(:precision_for)
+    expect(client).to respond_to(:surprising_errors)
+    expect(client).to respond_to(:free_energy_status)
+    expect(client).to respond_to(:active_inference_candidates)
+    expect(client).to respond_to(:register_active_inference)
+    expect(client).to respond_to(:resolve_active_inference)
+    expect(client).to respond_to(:update_predictive_coding)
+    expect(client).to respond_to(:predictive_coding_stats)
+  end
+
+  it 'accepts an injected generative_model' do
+    model = Legion::Extensions::PredictiveCoding::Helpers::GenerativeModel.new
+    custom_client = described_class.new(generative_model: model)
+    expect(custom_client).to respond_to(:generate_prediction)
+  end
+
+  it 'isolates state between separate client instances' do
+    client_a = described_class.new
+    client_b = described_class.new
+
+    client_a.report_outcome(domain: :x, predicted: 0.0, actual: 1.0)
+    result_b = client_b.surprising_errors
+
+    expect(result_b[:count]).to eq(0)
+  end
+
+  describe 'full predictive coding lifecycle' do
+    it 'predicts, reports outcome, then updates stats correctly' do
+      prediction = client.generate_prediction(domain: :proprioception, context: { expected: 0.6 })
+      expect(prediction[:success]).to be true
+
+      outcome = client.report_outcome(domain: :proprioception, predicted: prediction[:predicted], actual: 0.65)
+      expect(outcome[:success]).to be true
+
+      status = client.free_energy_status
+      expect(status[:free_energy]).to be_a(Float)
+
+      stats = client.predictive_coding_stats
+      expect(stats[:model][:domain_count]).to eq(1)
+    end
+
+    it 'runs a full active inference cycle' do
+      reg = client.register_active_inference(
+        domain:           :motor_cortex,
+        action:           :amplify_signal,
+        expected_outcome: 0.75
+      )
+
+      expect(reg[:status]).to eq(:pending)
+
+      resolved = client.resolve_active_inference(
+        domain:         :motor_cortex,
+        action:         :amplify_signal,
+        actual_outcome: 0.78,
+        inference_id:   reg[:inference_id]
+      )
+
+      expect(resolved[:success]).to be true
+
+      after_update = client.update_predictive_coding
+      expect(after_update[:pruned_inferences]).to eq(1)
+    end
+  end
+end

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

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::PredictiveCoding::Helpers::GenerativeModel do
+  let(:model) { described_class.new }
+  let(:constants) { Legion::Extensions::PredictiveCoding::Helpers::Constants }
+
+  describe '#initialize' do
+    it 'assigns a model_id' do
+      expect(model.model_id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'starts with zero domain models' do
+      expect(model.domain_count).to eq(0)
+    end
+
+    it 'starts with zero errors' do
+      expect(model.error_count).to eq(0)
+    end
+
+    it 'accepts an explicit model_id' do
+      m = described_class.new(model_id: 'custom-id')
+      expect(m.model_id).to eq('custom-id')
+    end
+  end
+
+  describe '#predict' do
+    it 'returns a prediction hash with domain and confidence' do
+      result = model.predict(domain: :vision)
+      expect(result[:domain]).to eq(:vision)
+      expect(result[:predicted]).to be_a(Numeric)
+      expect(result[:confidence]).to be_a(Float)
+    end
+
+    it 'uses DEFAULT_PRECISION for an unknown domain' do
+      result = model.predict(domain: :new_domain)
+      expect(result[:confidence]).to eq(constants::DEFAULT_PRECISION)
+    end
+
+    it 'uses context[:expected] as initial value for unknown domain' do
+      result = model.predict(domain: :touch, context: { expected: 0.9 })
+      expect(result[:predicted]).to be_within(0.001).of(0.9)
+    end
+
+    it 'improves prediction after learning from updates' do
+      5.times { model.update(domain: :sensor, predicted: 0.5, actual: 0.8) }
+      result = model.predict(domain: :sensor)
+      expect(result[:predicted]).to be > 0.5
+    end
+  end
+
+  describe '#update' do
+    it 'returns a PredictionError object' do
+      error = model.update(domain: :vision, predicted: 0.5, actual: 0.9)
+      expect(error).to be_a(Legion::Extensions::PredictiveCoding::Helpers::PredictionError)
+    end
+
+    it 'increments error count' do
+      model.update(domain: :vision, predicted: 0.5, actual: 0.9)
+      expect(model.error_count).to eq(1)
+    end
+
+    it 'creates a domain model entry' do
+      model.update(domain: :vision, predicted: 0.5, actual: 0.9)
+      expect(model.domain_count).to eq(1)
+    end
+
+    it 'adjusts precision downward on high error' do
+      initial = model.precision_for(domain: :vision)
+      model.update(domain: :vision, predicted: 0.0, actual: 1.0)
+      expect(model.precision_for(domain: :vision)).to be < initial
+    end
+
+    it 'adjusts precision upward on zero error' do
+      # First update to initialize the domain
+      model.update(domain: :vision, predicted: 0.5, actual: 0.5)
+      # Second perfect prediction should raise precision
+      after_init = model.precision_for(domain: :vision)
+      model.update(domain: :vision, predicted: 0.5, actual: 0.5)
+      expect(model.precision_for(domain: :vision)).to be >= after_init
+    end
+  end
+
+  describe '#precision_for' do
+    it 'returns DEFAULT_PRECISION for unknown domain' do
+      expect(model.precision_for(domain: :unknown)).to eq(constants::DEFAULT_PRECISION)
+    end
+
+    it 'returns updated precision after updates' do
+      model.update(domain: :motor, predicted: 0.5, actual: 0.5)
+      expect(model.precision_for(domain: :motor)).to be_a(Float)
+    end
+  end
+
+  describe '#free_energy' do
+    it 'returns a float' do
+      expect(model.free_energy).to be_a(Float)
+    end
+
+    it 'increases after surprising errors' do
+      initial = model.free_energy
+      5.times { model.update(domain: :x, predicted: 0.0, actual: 1.0) }
+      expect(model.free_energy).to be > initial
+    end
+  end
+
+  describe '#free_energy_level' do
+    it 'returns a symbol' do
+      expect(model.free_energy_level).to be_a(Symbol)
+    end
+
+    it 'returns :minimal for a fresh model' do
+      expect(model.free_energy_level).to eq(:minimal)
+    end
+  end
+
+  describe '#active_inference_candidates' do
+    it 'returns an empty array for a fresh model' do
+      expect(model.active_inference_candidates).to eq([])
+    end
+
+    it 'returns domains with high error and low precision' do
+      10.times { model.update(domain: :faulty, predicted: 0.0, actual: 1.0) }
+      candidates = model.active_inference_candidates
+      expect(candidates).to include(:faulty)
+    end
+  end
+
+  describe '#surprising_errors' do
+    it 'returns an empty array when no surprising errors' do
+      model.update(domain: :x, predicted: 0.5, actual: 0.5)
+      expect(model.surprising_errors).to be_empty
+    end
+
+    it 'returns errors above the surprise threshold' do
+      model.update(domain: :x, predicted: 0.0, actual: 1.0)
+      expect(model.surprising_errors).not_to be_empty
+    end
+  end
+
+  describe '#decay_all' do
+    it 'decreases precision for all known domains' do
+      model.update(domain: :vision, predicted: 0.8, actual: 0.9)
+      before = model.precision_for(domain: :vision)
+      model.decay_all
+      expect(model.precision_for(domain: :vision)).to be <= before
+    end
+
+    it 'does not drop precision below PRECISION_FLOOR' do
+      50.times { model.decay_all }
+      model.update(domain: :x, predicted: 0.5, actual: 0.5)
+      50.times { model.decay_all }
+      expect(model.precision_for(domain: :x)).to be >= constants::PRECISION_FLOOR
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a summary hash' do
+      h = model.to_h
+      expect(h[:model_id]).to eq(model.model_id)
+      expect(h[:domain_count]).to be_a(Integer)
+      expect(h[:error_count]).to be_a(Integer)
+      expect(h[:free_energy]).to be_a(Float)
+      expect(h[:free_energy_level]).to be_a(Symbol)
+      expect(h[:domains]).to be_an(Array)
+    end
+
+    it 'includes domain stats after updates' do
+      model.update(domain: :vision, predicted: 0.5, actual: 0.7)
+      h = model.to_h
+      expect(h[:domain_count]).to eq(1)
+      vision_stat = h[:domains].find { |d| d[:domain] == :vision }
+      expect(vision_stat).not_to be_nil
+      expect(vision_stat[:mean]).to be_a(Float)
+    end
+  end
+
+  describe 'MAX_MODELS eviction' do
+    it 'does not exceed MAX_MODELS domains' do
+      (constants::MAX_MODELS + 5).times do |i|
+        model.update(domain: :"domain_#{i}", predicted: 0.5, actual: 0.5)
+      end
+      expect(model.domain_count).to be <= constants::MAX_MODELS
+    end
+  end
+
+  describe 'MAX_ERROR_HISTORY cap' do
+    it 'caps error history at MAX_ERROR_HISTORY' do
+      (constants::MAX_ERROR_HISTORY + 10).times do
+        model.update(domain: :x, predicted: 0.5, actual: 0.5)
+      end
+      expect(model.error_count).to be <= constants::MAX_ERROR_HISTORY
+    end
+  end
+end

data/spec/legion/extensions/predictive_coding/helpers/prediction_error_spec.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::PredictiveCoding::Helpers::PredictionError do
+  let(:constants) { Legion::Extensions::PredictiveCoding::Helpers::Constants }
+
+  describe '#initialize' do
+    it 'stores domain, predicted, actual' do
+      error = described_class.new(domain: :vision, predicted: 0.8, actual: 0.9)
+      expect(error.domain).to eq(:vision)
+      expect(error.predicted).to eq(0.8)
+      expect(error.actual).to eq(0.9)
+    end
+
+    it 'stores a timestamp' do
+      error = described_class.new(domain: :vision, predicted: 0.5, actual: 0.5)
+      expect(error.timestamp).to be_a(Time)
+    end
+
+    it 'uses DEFAULT_PRECISION when none provided' do
+      error = described_class.new(domain: :vision, predicted: 0.5, actual: 0.5)
+      expect(error.precision).to eq(constants::DEFAULT_PRECISION)
+    end
+
+    it 'accepts explicit precision' do
+      error = described_class.new(domain: :vision, predicted: 0.5, actual: 0.5, precision: 0.9)
+      expect(error.precision).to eq(0.9)
+    end
+  end
+
+  describe '#error_magnitude' do
+    it 'computes absolute difference for numeric values' do
+      error = described_class.new(domain: :x, predicted: 0.3, actual: 0.8)
+      expect(error.error_magnitude).to be_within(0.001).of(0.5)
+    end
+
+    it 'clamps error magnitude to 1.0 for values differing by more than 1' do
+      error = described_class.new(domain: :x, predicted: 0.0, actual: 2.0)
+      expect(error.error_magnitude).to eq(1.0)
+    end
+
+    it 'returns 0.0 when predicted equals actual for numeric values' do
+      error = described_class.new(domain: :x, predicted: 0.5, actual: 0.5)
+      expect(error.error_magnitude).to eq(0.0)
+    end
+
+    it 'returns 0.0 when predicted equals actual for non-numeric values' do
+      error = described_class.new(domain: :x, predicted: :foo, actual: :foo)
+      expect(error.error_magnitude).to eq(0.0)
+    end
+
+    it 'returns 1.0 when non-numeric predicted differs from actual' do
+      error = described_class.new(domain: :x, predicted: :foo, actual: :bar)
+      expect(error.error_magnitude).to eq(1.0)
+    end
+  end
+
+  describe '#weighted_error' do
+    it 'equals error_magnitude * precision' do
+      error = described_class.new(domain: :x, predicted: 0.2, actual: 0.6, precision: 0.8)
+      expected = (0.6 - 0.2).abs * 0.8
+      expect(error.weighted_error).to be_within(0.001).of(expected)
+    end
+  end
+
+  describe '#surprising?' do
+    it 'returns true when error_magnitude >= SURPRISE_THRESHOLD' do
+      error = described_class.new(domain: :x, predicted: 0.0, actual: 1.0)
+      expect(error.surprising?).to be true
+    end
+
+    it 'returns false when error_magnitude < SURPRISE_THRESHOLD' do
+      error = described_class.new(domain: :x, predicted: 0.5, actual: 0.55)
+      expect(error.surprising?).to be false
+    end
+  end
+
+  describe '#level' do
+    it 'returns :negligible for very small errors' do
+      error = described_class.new(domain: :x, predicted: 0.5, actual: 0.505)
+      expect(error.level).to eq(:negligible)
+    end
+
+    it 'returns :surprising for large errors' do
+      error = described_class.new(domain: :x, predicted: 0.0, actual: 1.0)
+      expect(error.level).to eq(:surprising)
+    end
+
+    it 'returns :moderate for mid-range errors' do
+      error = described_class.new(domain: :x, predicted: 0.0, actual: 0.4)
+      expect(error.level).to eq(:moderate)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with all fields' do
+      error = described_class.new(domain: :vision, predicted: 0.3, actual: 0.7, precision: 0.6)
+      h = error.to_h
+      expect(h[:domain]).to eq(:vision)
+      expect(h[:predicted]).to eq(0.3)
+      expect(h[:actual]).to eq(0.7)
+      expect(h[:error_magnitude]).to be_a(Float)
+      expect(h[:precision]).to eq(0.6)
+      expect(h[:weighted_error]).to be_a(Float)
+      expect(h[:surprising]).to be(true).or be(false)
+      expect(h[:level]).to be_a(Symbol)
+      expect(h[:timestamp]).to be_a(Time)
+    end
+  end
+end

data/spec/legion/extensions/predictive_coding/runners/predictive_coding_spec.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/predictive_coding/client'
+
+RSpec.describe Legion::Extensions::PredictiveCoding::Runners::PredictiveCoding do
+  let(:client) { Legion::Extensions::PredictiveCoding::Client.new }
+
+  describe '#generate_prediction' do
+    it 'returns success with domain and prediction' do
+      result = client.generate_prediction(domain: :vision)
+      expect(result[:success]).to be true
+      expect(result[:domain]).to eq(:vision)
+      expect(result[:predicted]).to be_a(Numeric)
+      expect(result[:confidence]).to be_a(Float)
+    end
+
+    it 'passes context to the generative model' do
+      result = client.generate_prediction(domain: :audio, context: { expected: 0.7 })
+      expect(result[:success]).to be true
+      expect(result[:predicted]).to be_within(0.001).of(0.7)
+    end
+
+    it 'accepts extra keyword arguments without error' do
+      expect { client.generate_prediction(domain: :x, extra: :ignored) }.not_to raise_error
+    end
+  end
+
+  describe '#report_outcome' do
+    it 'returns success with error details' do
+      result = client.report_outcome(domain: :vision, predicted: 0.5, actual: 0.9)
+      expect(result[:success]).to be true
+      expect(result[:error_magnitude]).to be_a(Float)
+      expect(result[:weighted_error]).to be_a(Float)
+      expect(result[:precision]).to be_a(Float)
+      expect(result[:surprising]).to be(true).or be(false)
+      expect(result[:level]).to be_a(Symbol)
+    end
+
+    it 'marks zero-error outcomes as non-surprising' do
+      result = client.report_outcome(domain: :x, predicted: 0.5, actual: 0.5)
+      expect(result[:surprising]).to be false
+      expect(result[:error_magnitude]).to eq(0.0)
+    end
+
+    it 'marks large-error outcomes as surprising' do
+      result = client.report_outcome(domain: :x, predicted: 0.0, actual: 1.0)
+      expect(result[:surprising]).to be true
+    end
+  end
+
+  describe '#precision_for' do
+    it 'returns DEFAULT_PRECISION for unknown domain' do
+      result = client.precision_for(domain: :unknown_domain_xyz)
+      expect(result[:success]).to be true
+      expect(result[:precision]).to eq(Legion::Extensions::PredictiveCoding::Helpers::Constants::DEFAULT_PRECISION)
+    end
+
+    it 'returns updated precision after reporting outcomes' do
+      client.report_outcome(domain: :sensor, predicted: 0.5, actual: 0.5)
+      result = client.precision_for(domain: :sensor)
+      expect(result[:precision]).to be_a(Float)
+    end
+  end
+
+  describe '#surprising_errors' do
+    it 'returns empty list when no surprising errors' do
+      result = client.surprising_errors
+      expect(result[:success]).to be true
+      expect(result[:errors]).to be_an(Array)
+      expect(result[:count]).to eq(0)
+    end
+
+    it 'returns errors above surprise threshold' do
+      client.report_outcome(domain: :x, predicted: 0.0, actual: 1.0)
+      result = client.surprising_errors
+      expect(result[:count]).to be >= 1
+      expect(result[:errors].first[:surprising]).to be true
+    end
+  end
+
+  describe '#free_energy_status' do
+    it 'returns free energy value and level' do
+      result = client.free_energy_status
+      expect(result[:success]).to be true
+      expect(result[:free_energy]).to be_a(Float)
+      expect(result[:level]).to be_a(Symbol)
+      expect(result[:model_stats]).to be_a(Hash)
+    end
+
+    it 'reflects accumulated errors in free energy' do
+      initial = client.free_energy_status[:free_energy]
+      5.times { client.report_outcome(domain: :x, predicted: 0.0, actual: 1.0) }
+      elevated = client.free_energy_status[:free_energy]
+      expect(elevated).to be > initial
+    end
+  end
+
+  describe '#active_inference_candidates' do
+    it 'returns empty list for fresh client' do
+      result = client.active_inference_candidates
+      expect(result[:success]).to be true
+      expect(result[:candidates]).to be_an(Array)
+    end
+
+    it 'includes domains with persistent high errors' do
+      10.times { client.report_outcome(domain: :faulty, predicted: 0.0, actual: 1.0) }
+      result = client.active_inference_candidates
+      expect(result[:candidates]).to include(:faulty)
+    end
+  end
+
+  describe '#register_active_inference' do
+    it 'registers and returns an inference_id' do
+      result = client.register_active_inference(domain: :motor, action: :increase_gain, expected_outcome: 0.8)
+      expect(result[:success]).to be true
+      expect(result[:inference_id]).to match(/\A[0-9a-f-]{36}\z/)
+      expect(result[:status]).to eq(:pending)
+    end
+
+    it 'accepts extra keyword arguments' do
+      expect do
+        client.register_active_inference(domain: :x, action: :test, expected_outcome: 0.5, extra: :ignored)
+      end.not_to raise_error
+    end
+  end
+
+  describe '#resolve_active_inference' do
+    it 'resolves a registered inference and returns error details' do
+      reg = client.register_active_inference(domain: :motor, action: :increase_gain, expected_outcome: 0.8)
+      result = client.resolve_active_inference(
+        domain:         :motor,
+        action:         :increase_gain,
+        actual_outcome: 0.85,
+        inference_id:   reg[:inference_id]
+      )
+      expect(result[:success]).to be true
+      expect(result[:error_magnitude]).to be_a(Float)
+      expect(result).to have_key(:action_helpful)
+    end
+
+    it 'returns not_found when inference does not exist' do
+      result = client.resolve_active_inference(
+        domain:         :missing,
+        action:         :noop,
+        actual_outcome: 0.5,
+        inference_id:   'nonexistent-id'
+      )
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:not_found)
+    end
+
+    it 'marks action_helpful true when error is below surprise threshold' do
+      reg = client.register_active_inference(domain: :x, action: :nudge, expected_outcome: 0.5)
+      result = client.resolve_active_inference(
+        domain:         :x,
+        action:         :nudge,
+        actual_outcome: 0.51,
+        inference_id:   reg[:inference_id]
+      )
+      expect(result[:action_helpful]).to be true
+    end
+
+    it 'marks action_helpful false when error is above surprise threshold' do
+      reg = client.register_active_inference(domain: :x, action: :nudge, expected_outcome: 0.0)
+      result = client.resolve_active_inference(
+        domain:         :x,
+        action:         :nudge,
+        actual_outcome: 1.0,
+        inference_id:   reg[:inference_id]
+      )
+      expect(result[:action_helpful]).to be false
+    end
+  end
+
+  describe '#update_predictive_coding' do
+    it 'returns success' do
+      result = client.update_predictive_coding
+      expect(result[:success]).to be true
+    end
+
+    it 'prunes resolved inferences' do
+      reg = client.register_active_inference(domain: :x, action: :test, expected_outcome: 0.5)
+      client.resolve_active_inference(domain: :x, action: :test, actual_outcome: 0.5, inference_id: reg[:inference_id])
+      result = client.update_predictive_coding
+      expect(result[:pruned_inferences]).to be >= 1
+    end
+
+    it 'returns pruned count of zero when nothing resolved' do
+      result = client.update_predictive_coding
+      expect(result[:pruned_inferences]).to eq(0)
+    end
+  end
+
+  describe '#predictive_coding_stats' do
+    it 'returns full stats hash' do
+      result = client.predictive_coding_stats
+      expect(result[:success]).to be true
+      expect(result[:model]).to be_a(Hash)
+      expect(result[:active_inferences]).to be_a(Integer)
+      expect(result[:pending_inferences]).to be_a(Integer)
+    end
+
+    it 'counts active inferences correctly' do
+      client.register_active_inference(domain: :x, action: :test, expected_outcome: 0.5)
+      result = client.predictive_coding_stats
+      expect(result[:active_inferences]).to eq(1)
+      expect(result[:pending_inferences]).to eq(1)
+    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/predictive_coding'
+
+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-coding
+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: Karl Friston's Free Energy Principle / Predictive Processing framework
+  for brain-modeled agentic AI
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-predictive-coding.gemspec
+- lib/legion/extensions/predictive_coding.rb
+- lib/legion/extensions/predictive_coding/actors/decay.rb
+- lib/legion/extensions/predictive_coding/client.rb
+- lib/legion/extensions/predictive_coding/helpers/constants.rb
+- lib/legion/extensions/predictive_coding/helpers/generative_model.rb
+- lib/legion/extensions/predictive_coding/helpers/prediction_error.rb
+- lib/legion/extensions/predictive_coding/runners/predictive_coding.rb
+- lib/legion/extensions/predictive_coding/version.rb
+- spec/legion/extensions/predictive_coding/client_spec.rb
+- spec/legion/extensions/predictive_coding/helpers/generative_model_spec.rb
+- spec/legion/extensions/predictive_coding/helpers/prediction_error_spec.rb
+- spec/legion/extensions/predictive_coding/runners/predictive_coding_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-predictive-coding
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-predictive-coding
+  source_code_uri: https://github.com/LegionIO/lex-predictive-coding
+  documentation_uri: https://github.com/LegionIO/lex-predictive-coding
+  changelog_uri: https://github.com/LegionIO/lex-predictive-coding
+  bug_tracker_uri: https://github.com/LegionIO/lex-predictive-coding/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 Coding
+test_files: []