lex-agentic-inference 0.1.0

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

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        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
+  end
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        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
+  end
+end

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

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        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::Agentic::Inference::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::Agentic::Inference::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
+  end
+end

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

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

data/lib/legion/extensions/agentic/inference/predictive_coding.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'legion/extensions/agentic/inference/predictive_coding/version'
+require 'legion/extensions/agentic/inference/predictive_coding/helpers/constants'
+require 'legion/extensions/agentic/inference/predictive_coding/helpers/prediction_error'
+require 'legion/extensions/agentic/inference/predictive_coding/helpers/generative_model'
+require 'legion/extensions/agentic/inference/predictive_coding/runners/predictive_coding'
+require 'legion/extensions/agentic/inference/predictive_coding/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module PredictiveCoding
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/inference/predictive_processing/helpers/constants'
+require 'legion/extensions/agentic/inference/predictive_processing/helpers/generative_model'
+require 'legion/extensions/agentic/inference/predictive_processing/helpers/predictive_processor'
+require 'legion/extensions/agentic/inference/predictive_processing/runners/predictive_processing'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        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
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        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
+  end
+end

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

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        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
+  end
+end