lex-agentic-inference 0.1.0

data/lib/legion/extensions/agentic/inference/free_energy/helpers/belief.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module FreeEnergy
+          module Helpers
+            class Belief
+              include Constants
+
+              attr_reader :id, :domain, :content, :precision, :prediction,
+                          :last_observation, :prediction_error, :created_at, :updated_at
+
+              def initialize(id:, content:, domain: :general, prediction: {}, precision: DEFAULT_PRECISION)
+                @id               = id
+                @content          = content
+                @domain           = domain
+                @prediction       = prediction
+                @precision        = precision.clamp(PRECISION_FLOOR, PRECISION_CEILING)
+                @last_observation = nil
+                @prediction_error = 0.0
+                @created_at       = Time.now.utc
+                @updated_at       = @created_at
+              end
+
+              def observe(observation:)
+                @last_observation = observation
+                @prediction_error = compute_error(observation)
+                update_precision
+                @updated_at = Time.now.utc
+                self
+              end
+
+              def free_energy
+                @prediction_error * @precision
+              end
+
+              def surprising?
+                free_energy > FREE_ENERGY_THRESHOLD
+              end
+
+              def surprise_label
+                fe = free_energy
+                SURPRISE_LABELS.find { |range, _| range.cover?(fe) }&.last || :trivial
+              end
+
+              def revise_prediction(observation:)
+                merged = @prediction.dup
+                observation.each do |key, value|
+                  current = merged[key]
+                  merged[key] = if current.is_a?(Numeric) && value.is_a?(Numeric)
+                                  current + (LEARNING_RATE * (value - current))
+                                else
+                                  value
+                                end
+                end
+                @prediction = merged
+                @updated_at = Time.now.utc
+                self
+              end
+
+              def stale?(now: Time.now.utc)
+                (now - @updated_at) > STALE_THRESHOLD
+              end
+
+              def decay_precision
+                diff = @precision - DEFAULT_PRECISION
+                @precision -= diff * PRECISION_DECAY
+                @precision = @precision.clamp(PRECISION_FLOOR, PRECISION_CEILING)
+              end
+
+              def to_h
+                {
+                  id:               @id,
+                  domain:           @domain,
+                  content:          @content,
+                  prediction:       @prediction,
+                  last_observation: @last_observation,
+                  prediction_error: @prediction_error.round(4),
+                  precision:        @precision.round(4),
+                  free_energy:      free_energy.round(4),
+                  surprise_label:   surprise_label,
+                  surprising:       surprising?,
+                  created_at:       @created_at,
+                  updated_at:       @updated_at
+                }
+              end
+
+              private
+
+              def compute_error(observation)
+                return empty_prediction_error(observation) if @prediction.empty?
+
+                shared_keys = @prediction.keys & observation.keys
+                return 1.0 if shared_keys.empty?
+
+                errors = shared_keys.map { |k| key_error(@prediction[k], observation[k]) }
+                missing_penalty = (@prediction.keys - shared_keys).size * 0.5
+                ((errors.sum + missing_penalty) / @prediction.size.to_f).clamp(0.0, 1.0)
+              end
+
+              def empty_prediction_error(observation)
+                observation.empty? ? 0.0 : 1.0
+              end
+
+              def key_error(predicted, observed)
+                return (predicted - observed).abs.clamp(0.0, 1.0) if predicted.is_a?(Numeric) && observed.is_a?(Numeric)
+
+                predicted == observed ? 0.0 : 1.0
+              end
+
+              def update_precision
+                if @prediction_error < 0.2
+                  @precision += PRECISION_UPDATE_RATE * (1.0 - @prediction_error)
+                else
+                  @precision -= PRECISION_UPDATE_RATE * @prediction_error
+                end
+                @precision = @precision.clamp(PRECISION_FLOOR, PRECISION_CEILING)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module FreeEnergy
+          module Helpers
+            module Constants
+              # Maximum generative-model beliefs
+              MAX_BELIEFS = 200
+
+              # Maximum planned actions
+              MAX_ACTIONS = 100
+
+              # Maximum event history
+              MAX_HISTORY = 300
+
+              # Default precision (inverse variance / confidence in prediction)
+              DEFAULT_PRECISION = 0.5
+
+              # Precision bounds
+              PRECISION_FLOOR   = 0.05
+              PRECISION_CEILING = 0.95
+
+              # Free energy above this triggers high-surprise state
+              FREE_ENERGY_THRESHOLD = 0.5
+
+              # Learning rate for belief updates (perceptual inference)
+              LEARNING_RATE = 0.1
+
+              # Rate at which precision adapts to prediction errors
+              PRECISION_UPDATE_RATE = 0.05
+
+              # Precision decay toward default for stale beliefs
+              PRECISION_DECAY = 0.01
+
+              # How stale (seconds) before precision decays
+              STALE_THRESHOLD = 120
+
+              # Free energy minimization strategies
+              INFERENCE_MODES = %i[perceptual active].freeze
+
+              # Surprise magnitude labels
+              SURPRISE_LABELS = {
+                (0.8..)     => :shocking,
+                (0.6...0.8) => :surprising,
+                (0.4...0.6) => :notable,
+                (0.2...0.4) => :expected,
+                (..0.2)     => :trivial
+              }.freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/inference/free_energy/helpers/free_energy_engine.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module FreeEnergy
+          module Helpers
+            class FreeEnergyEngine
+              include Constants
+
+              attr_reader :beliefs, :history
+
+              def initialize
+                @beliefs      = {}
+                @belief_count = 0
+                @history      = []
+              end
+
+              def add_belief(content:, domain: :general, prediction: {}, precision: DEFAULT_PRECISION)
+                return nil if @beliefs.size >= MAX_BELIEFS
+
+                @belief_count += 1
+                belief = Belief.new(
+                  id:         :"belief_#{@belief_count}",
+                  content:    content,
+                  domain:     domain,
+                  prediction: prediction,
+                  precision:  precision
+                )
+                @beliefs[belief.id] = belief
+                record_event(:add_belief, belief_id: belief.id)
+                belief
+              end
+
+              def observe(belief_id:, observation:)
+                belief = @beliefs[belief_id]
+                return nil unless belief
+
+                belief.observe(observation: observation)
+                record_event(:observe, belief_id: belief_id, error: belief.prediction_error)
+                belief
+              end
+
+              def minimize_perceptual(belief_id:)
+                belief = @beliefs[belief_id]
+                return nil unless belief
+                return nil unless belief.last_observation
+
+                belief.revise_prediction(observation: belief.last_observation)
+                record_event(:minimize_perceptual, belief_id: belief_id)
+                belief
+              end
+
+              def minimize_active(belief_id:)
+                belief = @beliefs[belief_id]
+                return nil unless belief
+
+                action = {
+                  type:      :active_inference,
+                  belief_id: belief_id,
+                  target:    belief.prediction,
+                  urgency:   belief.free_energy
+                }
+                record_event(:minimize_active, belief_id: belief_id, action: action)
+                action
+              end
+
+              def minimize(belief_id:, mode: :perceptual)
+                case mode
+                when :perceptual then minimize_perceptual(belief_id: belief_id)
+                when :active     then minimize_active(belief_id: belief_id)
+                end
+              end
+
+              def total_free_energy
+                return 0.0 if @beliefs.empty?
+
+                @beliefs.values.sum(&:free_energy) / @beliefs.size.to_f
+              end
+
+              def surprise_level
+                fe = total_free_energy
+                SURPRISE_LABELS.find { |range, _| range.cover?(fe) }&.last || :trivial
+              end
+
+              def high_surprise_beliefs
+                @beliefs.values.select(&:surprising?).map(&:to_h)
+              end
+
+              def domain_beliefs(domain:)
+                @beliefs.values.select { |b| b.domain == domain }
+              end
+
+              def domain_free_energy(domain:)
+                relevant = domain_beliefs(domain: domain)
+                return 0.0 if relevant.empty?
+
+                relevant.sum(&:free_energy) / relevant.size.to_f
+              end
+
+              def most_surprising(limit: 5)
+                @beliefs.values
+                        .sort_by { |b| -b.free_energy }
+                        .first(limit)
+                        .map(&:to_h)
+              end
+
+              def most_precise(limit: 5)
+                @beliefs.values
+                        .sort_by { |b| -b.precision }
+                        .first(limit)
+                        .map(&:to_h)
+              end
+
+              def decay_stale
+                now = Time.now.utc
+                @beliefs.each_value do |belief|
+                  belief.decay_precision if belief.stale?(now: now)
+                end
+              end
+
+              def remove_belief(belief_id:)
+                @beliefs.delete(belief_id)
+              end
+
+              def to_h
+                {
+                  belief_count:        @beliefs.size,
+                  total_free_energy:   total_free_energy.round(4),
+                  surprise_level:      surprise_level,
+                  high_surprise_count: @beliefs.values.count(&:surprising?),
+                  mean_precision:      mean_precision.round(4),
+                  history_size:        @history.size
+                }
+              end
+
+              private
+
+              def mean_precision
+                return DEFAULT_PRECISION if @beliefs.empty?
+
+                @beliefs.values.sum(&:precision) / @beliefs.size.to_f
+              end
+
+              def record_event(type, **details)
+                @history << { type: type, at: Time.now.utc }.merge(details)
+                @history.shift while @history.size > MAX_HISTORY
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module FreeEnergy
+          module Runners
+            module FreeEnergy
+              include Helpers::Constants
+              include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+              def add_generative_belief(content:, domain: :general, prediction: {}, precision: DEFAULT_PRECISION, **)
+                belief = engine.add_belief(content: content, domain: domain, prediction: prediction, precision: precision)
+                return { success: false, reason: :limit_reached } unless belief
+
+                { success: true, belief_id: belief.id, precision: belief.precision }
+              end
+
+              def observe_outcome(belief_id:, observation:, **)
+                belief = engine.observe(belief_id: belief_id, observation: observation)
+                return { success: false, reason: :not_found } unless belief
+
+                {
+                  success:          true,
+                  belief_id:        belief_id,
+                  prediction_error: belief.prediction_error.round(4),
+                  free_energy:      belief.free_energy.round(4),
+                  surprising:       belief.surprising?,
+                  surprise_label:   belief.surprise_label
+                }
+              end
+
+              def minimize_free_energy(belief_id:, mode: :perceptual, **)
+                result = engine.minimize(belief_id: belief_id, mode: mode)
+                return { success: false, reason: :not_found } unless result
+
+                if mode == :active
+                  { success: true, mode: :active }.merge(result)
+                else
+                  { success: true, mode: :perceptual, belief_id: result.id, prediction: result.prediction }
+                end
+              end
+
+              def compute_free_energy(**)
+                {
+                  success:             true,
+                  total_free_energy:   engine.total_free_energy.round(4),
+                  surprise_level:      engine.surprise_level,
+                  high_surprise_count: engine.high_surprise_beliefs.size
+                }
+              end
+
+              def surprise_assessment(**)
+                {
+                  success:         true,
+                  surprise_level:  engine.surprise_level,
+                  most_surprising: engine.most_surprising,
+                  most_precise:    engine.most_precise
+                }
+              end
+
+              def high_surprise_beliefs(**)
+                beliefs = engine.high_surprise_beliefs
+                { success: true, beliefs: beliefs, count: beliefs.size }
+              end
+
+              def domain_free_energy(domain:, **)
+                {
+                  success:      true,
+                  domain:       domain,
+                  free_energy:  engine.domain_free_energy(domain: domain).round(4),
+                  belief_count: engine.domain_beliefs(domain: domain).size
+                }
+              end
+
+              def update_free_energy(**)
+                engine.decay_stale
+                { success: true }.merge(engine.to_h)
+              end
+
+              def free_energy_stats(**)
+                { success: true }.merge(engine.to_h)
+              end
+
+              private
+
+              def engine
+                @engine ||= Helpers::FreeEnergyEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'free_energy/version'
+require_relative 'free_energy/helpers/constants'
+require_relative 'free_energy/helpers/belief'
+require_relative 'free_energy/helpers/free_energy_engine'
+require_relative 'free_energy/runners/free_energy'
+require_relative 'free_energy/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module FreeEnergy
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/inference/gravity/helpers/constants'
+require 'legion/extensions/agentic/inference/gravity/helpers/attractor'
+require 'legion/extensions/agentic/inference/gravity/helpers/orbiting_thought'
+require 'legion/extensions/agentic/inference/gravity/helpers/gravity_engine'
+require 'legion/extensions/agentic/inference/gravity/runners/gravity'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module Gravity
+          class Client
+            include Runners::Gravity
+
+            def initialize(**)
+              @gravity_engine = Helpers::GravityEngine.new
+            end
+
+            private
+
+            attr_reader :gravity_engine
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/inference/gravity/helpers/attractor.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module Gravity
+          module Helpers
+            class Attractor
+              attr_reader :id, :content, :domain, :mass, :pull_radius, :decay_rate, :created_at, :reinforcement_count
+
+              def initialize(content:, domain: :unknown, mass: Constants::DEFAULT_MASS,
+                             pull_radius: 1.0, decay_rate: 0.01)
+                @id                  = SecureRandom.uuid
+                @content             = content
+                @domain              = domain
+                @mass                = mass.to_f.round(10)
+                @pull_radius         = pull_radius.clamp(0.01, Float::INFINITY)
+                @decay_rate          = decay_rate.clamp(0.0, 1.0)
+                @created_at          = Time.now.utc
+                @reinforcement_count = 0
+              end
+
+              def accrete!(amount = Constants::MASS_ACCRETION)
+                @mass = (@mass + amount.to_f).round(10)
+                @reinforcement_count += 1
+                self
+              end
+
+              def erode!(amount = Constants::MASS_EROSION)
+                @mass = [(@mass - amount.to_f).round(10), 0.0].max
+                self
+              end
+
+              def pull_strength_at(distance:)
+                return 0.0 if distance <= 0 || distance > @pull_radius
+
+                raw = (Constants::PULL_CONSTANT * @mass) / (distance**2)
+                raw.clamp(0.0, @mass)
+              end
+
+              def collapsed?
+                @mass < Constants::COLLAPSE_THRESHOLD
+              end
+
+              def supermassive?
+                @mass >= Constants::SUPERMASSIVE_THRESHOLD
+              end
+
+              def mass_label
+                Constants.label_for(Constants::MASS_LABELS, @mass)
+              end
+
+              def to_h
+                {
+                  id:                  @id,
+                  content:             @content,
+                  domain:              @domain,
+                  mass:                @mass,
+                  pull_radius:         @pull_radius,
+                  decay_rate:          @decay_rate,
+                  reinforcement_count: @reinforcement_count,
+                  collapsed:           collapsed?,
+                  supermassive:        supermassive?,
+                  mass_label:          mass_label,
+                  created_at:          @created_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module Gravity
+          module Helpers
+            module Constants
+              MAX_ATTRACTORS   = 200
+              MAX_ORBITING     = 500
+              DEFAULT_MASS     = 1.0
+              MASS_ACCRETION   = 0.15
+              MASS_EROSION     = 0.05
+              CAPTURE_RADIUS   = 0.2
+              ESCAPE_RADIUS    = 1.5
+              PULL_CONSTANT    = 0.1
+              COLLAPSE_THRESHOLD     = 0.1
+              SUPERMASSIVE_THRESHOLD = 3.0
+
+              ATTRACTOR_DOMAINS = %i[
+                problem
+                curiosity
+                anxiety
+                obsession
+                interest
+                fear
+                desire
+                unknown
+              ].freeze
+
+              MASS_LABELS = {
+                (0.0..0.1)             => :collapsing,
+                (0.1..0.5)             => :weak,
+                (0.5..1.0)             => :nascent,
+                (1.0..2.0)             => :moderate,
+                (2.0..3.0)             => :strong,
+                (3.0..Float::INFINITY) => :supermassive
+              }.freeze
+
+              DENSITY_LABELS = {
+                (0..0)                => :empty,
+                (1..2)                => :sparse,
+                (3..5)                => :light,
+                (6..10)               => :moderate,
+                (11..20)              => :dense,
+                (21..Float::INFINITY) => :crowded
+              }.freeze
+
+              ORBIT_LABELS = {
+                (0.0..0.2)             => :captured,
+                (0.2..0.5)             => :tight,
+                (0.5..1.0)             => :stable,
+                (1.0..1.5)             => :loose,
+                (1.5..Float::INFINITY) => :escaped
+              }.freeze
+
+              module_function
+
+              def label_for(labels_hash, value)
+                labels_hash.each do |range, label|
+                  return label if range.cover?(value)
+                end
+                :unknown
+              end
+
+              def valid_domain?(domain)
+                ATTRACTOR_DOMAINS.include?(domain)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end