lex-agentic-inference 0.1.0

data/spec/legion/extensions/agentic/inference/free_energy/helpers/belief_spec.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Inference::FreeEnergy::Helpers::Belief do
+  subject(:belief) do
+    described_class.new(
+      id:         :belief_one,
+      content:    'weather model',
+      domain:     :environment,
+      prediction: { temperature: 0.7, humidity: 0.5 },
+      precision:  0.6
+    )
+  end
+
+  describe '#initialize' do
+    it 'sets id' do
+      expect(belief.id).to eq(:belief_one)
+    end
+
+    it 'sets content' do
+      expect(belief.content).to eq('weather model')
+    end
+
+    it 'sets domain' do
+      expect(belief.domain).to eq(:environment)
+    end
+
+    it 'sets prediction' do
+      expect(belief.prediction).to eq({ temperature: 0.7, humidity: 0.5 })
+    end
+
+    it 'sets precision' do
+      expect(belief.precision).to eq(0.6)
+    end
+
+    it 'clamps precision to ceiling' do
+      b = described_class.new(id: :x, content: 'test', precision: 1.5)
+      expect(b.precision).to eq(Legion::Extensions::Agentic::Inference::FreeEnergy::Helpers::Constants::PRECISION_CEILING)
+    end
+
+    it 'clamps precision to floor' do
+      b = described_class.new(id: :x, content: 'test', precision: -0.5)
+      expect(b.precision).to eq(Legion::Extensions::Agentic::Inference::FreeEnergy::Helpers::Constants::PRECISION_FLOOR)
+    end
+
+    it 'starts with zero prediction error' do
+      expect(belief.prediction_error).to eq(0.0)
+    end
+
+    it 'starts with nil last_observation' do
+      expect(belief.last_observation).to be_nil
+    end
+
+    it 'is not surprising initially' do
+      expect(belief.surprising?).to be false
+    end
+  end
+
+  describe '#observe' do
+    it 'sets last_observation' do
+      belief.observe(observation: { temperature: 0.7, humidity: 0.5 })
+      expect(belief.last_observation).to eq({ temperature: 0.7, humidity: 0.5 })
+    end
+
+    it 'computes low error for matching observation' do
+      belief.observe(observation: { temperature: 0.7, humidity: 0.5 })
+      expect(belief.prediction_error).to eq(0.0)
+    end
+
+    it 'computes high error for divergent observation' do
+      belief.observe(observation: { temperature: 0.0, humidity: 0.0 })
+      expect(belief.prediction_error).to be > 0.3
+    end
+
+    it 'updates precision upward on low error' do
+      original = belief.precision
+      belief.observe(observation: { temperature: 0.7, humidity: 0.5 })
+      expect(belief.precision).to be > original
+    end
+
+    it 'updates precision downward on high error' do
+      original = belief.precision
+      belief.observe(observation: { temperature: 0.0, humidity: 0.0 })
+      expect(belief.precision).to be < original
+    end
+
+    it 'returns self for chaining' do
+      expect(belief.observe(observation: {})).to be(belief)
+    end
+
+    it 'updates updated_at' do
+      before = belief.updated_at
+      sleep 0.01
+      belief.observe(observation: { temperature: 0.5 })
+      expect(belief.updated_at).to be > before
+    end
+  end
+
+  describe '#free_energy' do
+    it 'returns zero when no observation made' do
+      expect(belief.free_energy).to eq(0.0)
+    end
+
+    it 'returns precision-weighted prediction error' do
+      belief.observe(observation: { temperature: 0.0, humidity: 0.0 })
+      expect(belief.free_energy).to be > 0.0
+    end
+
+    it 'is higher when precision is higher' do
+      high_prec = described_class.new(id: :hp, content: 'test', prediction: { v: 0.9 }, precision: 0.9)
+      low_prec  = described_class.new(id: :lp, content: 'test', prediction: { v: 0.9 }, precision: 0.2)
+
+      high_prec.observe(observation: { v: 0.0 })
+      low_prec.observe(observation: { v: 0.0 })
+
+      expect(high_prec.free_energy).to be > low_prec.free_energy
+    end
+  end
+
+  describe '#surprise_label' do
+    it 'returns :trivial when no error' do
+      expect(belief.surprise_label).to eq(:trivial)
+    end
+
+    it 'returns non-trivial label for larger errors' do
+      belief.observe(observation: { temperature: 0.0, humidity: 0.0 })
+      expect(belief.surprise_label).not_to eq(:trivial)
+    end
+  end
+
+  describe '#revise_prediction' do
+    it 'moves prediction toward observation' do
+      belief.observe(observation: { temperature: 1.0, humidity: 0.5 })
+      belief.revise_prediction(observation: { temperature: 1.0 })
+      expect(belief.prediction[:temperature]).to be > 0.7
+    end
+
+    it 'preserves unobserved prediction keys' do
+      belief.revise_prediction(observation: { temperature: 1.0 })
+      expect(belief.prediction[:humidity]).to eq(0.5)
+    end
+
+    it 'replaces non-numeric values' do
+      b = described_class.new(id: :x, content: 'test', prediction: { color: :red })
+      b.revise_prediction(observation: { color: :blue })
+      expect(b.prediction[:color]).to eq(:blue)
+    end
+  end
+
+  describe '#stale?' do
+    it 'is not stale immediately' do
+      expect(belief.stale?).to be false
+    end
+
+    it 'is stale after threshold' do
+      future = Time.now.utc + 200
+      expect(belief.stale?(now: future)).to be true
+    end
+  end
+
+  describe '#decay_precision' do
+    it 'moves precision toward default' do
+      belief.decay_precision
+      expect(belief.precision).to be < 0.6
+    end
+
+    it 'moves low precision toward default' do
+      b = described_class.new(id: :x, content: 'test', precision: 0.2)
+      b.decay_precision
+      expect(b.precision).to be > 0.2
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with expected keys' do
+      h = belief.to_h
+      expect(h).to include(
+        :id, :domain, :content, :prediction, :last_observation,
+        :prediction_error, :precision, :free_energy, :surprise_label,
+        :surprising, :created_at, :updated_at
+      )
+    end
+  end
+end

data/spec/legion/extensions/agentic/inference/free_energy/helpers/free_energy_engine_spec.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Inference::FreeEnergy::Helpers::FreeEnergyEngine do
+  subject(:engine) { described_class.new }
+
+  let(:constants) { Legion::Extensions::Agentic::Inference::FreeEnergy::Helpers::Constants }
+
+  describe '#initialize' do
+    it 'starts with empty beliefs' do
+      expect(engine.beliefs).to be_empty
+    end
+
+    it 'starts with empty history' do
+      expect(engine.history).to be_empty
+    end
+  end
+
+  describe '#add_belief' do
+    it 'creates a belief' do
+      belief = engine.add_belief(content: 'test model', domain: :test)
+      expect(belief).to be_a(Legion::Extensions::Agentic::Inference::FreeEnergy::Helpers::Belief)
+    end
+
+    it 'assigns sequential IDs' do
+      first  = engine.add_belief(content: 'first')
+      second = engine.add_belief(content: 'second')
+      expect(first.id).to be_a(Symbol)
+      expect(second.id).not_to eq(first.id)
+    end
+
+    it 'stores the belief' do
+      belief = engine.add_belief(content: 'stored')
+      expect(engine.beliefs[belief.id]).to be(belief)
+    end
+
+    it 'respects MAX_BELIEFS limit' do
+      constants::MAX_BELIEFS.times { |i| engine.add_belief(content: "belief #{i}") }
+      expect(engine.add_belief(content: 'overflow')).to be_nil
+    end
+
+    it 'records history event' do
+      engine.add_belief(content: 'tracked')
+      expect(engine.history.last[:type]).to eq(:add_belief)
+    end
+  end
+
+  describe '#observe' do
+    let!(:belief) { engine.add_belief(content: 'weather', prediction: { temp: 0.7 }) }
+
+    it 'updates the belief with observation' do
+      result = engine.observe(belief_id: belief.id, observation: { temp: 0.7 })
+      expect(result.prediction_error).to eq(0.0)
+    end
+
+    it 'returns nil for unknown belief' do
+      expect(engine.observe(belief_id: :nonexistent, observation: {})).to be_nil
+    end
+
+    it 'records history event' do
+      engine.observe(belief_id: belief.id, observation: { temp: 0.5 })
+      expect(engine.history.last[:type]).to eq(:observe)
+    end
+  end
+
+  describe '#minimize_perceptual' do
+    let!(:belief) { engine.add_belief(content: 'model', prediction: { v: 0.3 }) }
+
+    it 'revises prediction toward observation' do
+      engine.observe(belief_id: belief.id, observation: { v: 0.9 })
+      engine.minimize_perceptual(belief_id: belief.id)
+      expect(belief.prediction[:v]).to be > 0.3
+    end
+
+    it 'returns nil for unknown belief' do
+      expect(engine.minimize_perceptual(belief_id: :nonexistent)).to be_nil
+    end
+
+    it 'returns nil when no observation exists' do
+      expect(engine.minimize_perceptual(belief_id: belief.id)).to be_nil
+    end
+  end
+
+  describe '#minimize_active' do
+    let!(:belief) { engine.add_belief(content: 'model', prediction: { v: 0.8 }) }
+
+    it 'returns an action plan' do
+      action = engine.minimize_active(belief_id: belief.id)
+      expect(action[:type]).to eq(:active_inference)
+      expect(action[:target]).to eq(belief.prediction)
+    end
+
+    it 'returns nil for unknown belief' do
+      expect(engine.minimize_active(belief_id: :nonexistent)).to be_nil
+    end
+  end
+
+  describe '#minimize' do
+    let!(:belief) { engine.add_belief(content: 'model', prediction: { v: 0.5 }) }
+
+    it 'delegates to perceptual mode' do
+      engine.observe(belief_id: belief.id, observation: { v: 0.9 })
+      result = engine.minimize(belief_id: belief.id, mode: :perceptual)
+      expect(result).to be_a(Legion::Extensions::Agentic::Inference::FreeEnergy::Helpers::Belief)
+    end
+
+    it 'delegates to active mode' do
+      result = engine.minimize(belief_id: belief.id, mode: :active)
+      expect(result[:type]).to eq(:active_inference)
+    end
+  end
+
+  describe '#total_free_energy' do
+    it 'returns zero with no beliefs' do
+      expect(engine.total_free_energy).to eq(0.0)
+    end
+
+    it 'returns average free energy across beliefs' do
+      b = engine.add_belief(content: 'test', prediction: { v: 0.9 })
+      engine.observe(belief_id: b.id, observation: { v: 0.0 })
+      expect(engine.total_free_energy).to be > 0.0
+    end
+  end
+
+  describe '#surprise_level' do
+    it 'returns :trivial with no beliefs' do
+      expect(engine.surprise_level).to eq(:trivial)
+    end
+
+    it 'reflects high surprise when predictions fail' do
+      b = engine.add_belief(content: 'test', prediction: { v: 1.0 }, precision: 0.9)
+      engine.observe(belief_id: b.id, observation: { v: 0.0 })
+      expect(engine.surprise_level).not_to eq(:trivial)
+    end
+  end
+
+  describe '#high_surprise_beliefs' do
+    it 'returns empty when no surprises' do
+      engine.add_belief(content: 'calm')
+      expect(engine.high_surprise_beliefs).to be_empty
+    end
+
+    it 'returns surprised beliefs' do
+      b = engine.add_belief(content: 'shock', prediction: { v: 1.0 }, precision: 0.9)
+      engine.observe(belief_id: b.id, observation: { v: 0.0 })
+      expect(engine.high_surprise_beliefs.size).to eq(1)
+    end
+  end
+
+  describe '#domain_free_energy' do
+    it 'returns zero for empty domain' do
+      expect(engine.domain_free_energy(domain: :test)).to eq(0.0)
+    end
+
+    it 'computes free energy for domain only' do
+      b_env = engine.add_belief(content: 'env', domain: :environment, prediction: { v: 1.0 }, precision: 0.9)
+      engine.add_belief(content: 'social', domain: :social, prediction: { v: 1.0 }, precision: 0.9)
+      engine.observe(belief_id: b_env.id, observation: { v: 0.0 })
+      expect(engine.domain_free_energy(domain: :environment)).to be > 0.0
+    end
+  end
+
+  describe '#most_surprising' do
+    it 'returns beliefs sorted by free energy descending' do
+      high = engine.add_belief(content: 'a', prediction: { v: 1.0 }, precision: 0.9)
+      low  = engine.add_belief(content: 'b', prediction: { v: 0.5 }, precision: 0.3)
+      engine.observe(belief_id: high.id, observation: { v: 0.0 })
+      engine.observe(belief_id: low.id, observation: { v: 0.0 })
+
+      result = engine.most_surprising(limit: 2)
+      expect(result.first[:free_energy]).to be >= result.last[:free_energy]
+    end
+  end
+
+  describe '#most_precise' do
+    it 'returns beliefs sorted by precision descending' do
+      engine.add_belief(content: 'low', precision: 0.2)
+      engine.add_belief(content: 'high', precision: 0.8)
+
+      result = engine.most_precise(limit: 2)
+      expect(result.first[:precision]).to be >= result.last[:precision]
+    end
+  end
+
+  describe '#decay_stale' do
+    it 'decays precision of stale beliefs' do
+      b = engine.add_belief(content: 'old', precision: 0.8)
+      allow(Time).to receive(:now).and_return(Time.now.utc + 200)
+      original = b.precision
+      engine.decay_stale
+      expect(b.precision).not_to eq(original)
+    end
+  end
+
+  describe '#remove_belief' do
+    it 'removes a belief' do
+      b = engine.add_belief(content: 'temporary')
+      engine.remove_belief(belief_id: b.id)
+      expect(engine.beliefs).to be_empty
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns stats hash' do
+      h = engine.to_h
+      expect(h).to include(
+        :belief_count, :total_free_energy, :surprise_level,
+        :high_surprise_count, :mean_precision, :history_size
+      )
+    end
+  end
+end

data/spec/legion/extensions/agentic/inference/free_energy/runners/free_energy_spec.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Inference::FreeEnergy::Runners::FreeEnergy do
+  let(:runner_host) do
+    Object.new.tap { |o| o.extend(described_class) }
+  end
+
+  describe '#add_generative_belief' do
+    it 'creates a belief successfully' do
+      result = runner_host.add_generative_belief(content: 'test model', domain: :test)
+      expect(result[:success]).to be true
+      expect(result[:belief_id]).to be_a(Symbol)
+    end
+
+    it 'accepts prediction and precision' do
+      result = runner_host.add_generative_belief(
+        content: 'weather', prediction: { temp: 0.7 }, precision: 0.8
+      )
+      expect(result[:precision]).to eq(0.8)
+    end
+  end
+
+  describe '#observe_outcome' do
+    let!(:belief_id) do
+      runner_host.add_generative_belief(content: 'model', prediction: { v: 0.7 })[:belief_id]
+    end
+
+    it 'returns prediction error' do
+      result = runner_host.observe_outcome(belief_id: belief_id, observation: { v: 0.7 })
+      expect(result[:success]).to be true
+      expect(result[:prediction_error]).to eq(0.0)
+    end
+
+    it 'detects surprise' do
+      result = runner_host.observe_outcome(belief_id: belief_id, observation: { v: 0.0 })
+      expect(result[:prediction_error]).to be > 0.0
+    end
+
+    it 'returns failure for unknown belief' do
+      result = runner_host.observe_outcome(belief_id: :nonexistent, observation: {})
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#minimize_free_energy' do
+    let!(:belief_id) do
+      runner_host.add_generative_belief(content: 'model', prediction: { v: 0.3 })[:belief_id]
+    end
+
+    it 'performs perceptual inference' do
+      runner_host.observe_outcome(belief_id: belief_id, observation: { v: 0.9 })
+      result = runner_host.minimize_free_energy(belief_id: belief_id, mode: :perceptual)
+      expect(result[:success]).to be true
+      expect(result[:mode]).to eq(:perceptual)
+    end
+
+    it 'performs active inference' do
+      result = runner_host.minimize_free_energy(belief_id: belief_id, mode: :active)
+      expect(result[:success]).to be true
+      expect(result[:mode]).to eq(:active)
+      expect(result[:type]).to eq(:active_inference)
+    end
+
+    it 'returns failure for unknown belief' do
+      result = runner_host.minimize_free_energy(belief_id: :nonexistent)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#compute_free_energy' do
+    it 'returns total free energy' do
+      result = runner_host.compute_free_energy
+      expect(result[:success]).to be true
+      expect(result).to include(:total_free_energy, :surprise_level, :high_surprise_count)
+    end
+  end
+
+  describe '#surprise_assessment' do
+    it 'returns surprise assessment' do
+      result = runner_host.surprise_assessment
+      expect(result[:success]).to be true
+      expect(result).to include(:surprise_level, :most_surprising, :most_precise)
+    end
+  end
+
+  describe '#high_surprise_beliefs' do
+    it 'returns empty list when calm' do
+      result = runner_host.high_surprise_beliefs
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(0)
+    end
+  end
+
+  describe '#domain_free_energy' do
+    it 'returns domain-specific free energy' do
+      runner_host.add_generative_belief(content: 'env model', domain: :environment)
+      result = runner_host.domain_free_energy(domain: :environment)
+      expect(result[:success]).to be true
+      expect(result[:domain]).to eq(:environment)
+    end
+  end
+
+  describe '#update_free_energy' do
+    it 'decays stale beliefs and returns stats' do
+      result = runner_host.update_free_energy
+      expect(result[:success]).to be true
+      expect(result).to include(:belief_count, :total_free_energy)
+    end
+  end
+
+  describe '#free_energy_stats' do
+    it 'returns engine statistics' do
+      result = runner_host.free_energy_stats
+      expect(result[:success]).to be true
+      expect(result).to include(:belief_count, :surprise_level)
+    end
+  end
+end

data/spec/legion/extensions/agentic/inference/gravity/client_spec.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/inference/gravity/client'
+
+RSpec.describe Legion::Extensions::Agentic::Inference::Gravity::Client do
+  it 'responds to all runner methods' do
+    client = described_class.new
+    expect(client).to respond_to(:create_attractor)
+    expect(client).to respond_to(:add_thought)
+    expect(client).to respond_to(:tick_gravity)
+    expect(client).to respond_to(:accrete)
+    expect(client).to respond_to(:erode)
+    expect(client).to respond_to(:strongest_attractors)
+    expect(client).to respond_to(:thought_distribution)
+    expect(client).to respond_to(:cognitive_density_map)
+    expect(client).to respond_to(:gravity_report)
+  end
+
+  it 'initializes with a fresh gravity engine' do
+    client = described_class.new
+    result = client.gravity_report
+    expect(result[:report][:total_attractors]).to eq(0)
+  end
+end

data/spec/legion/extensions/agentic/inference/gravity/helpers/attractor_spec.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Inference::Gravity::Helpers::Attractor do
+  subject(:attractor) { described_class.new(content: 'test thought', domain: :curiosity) }
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(attractor.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets content' do
+      expect(attractor.content).to eq('test thought')
+    end
+
+    it 'sets domain' do
+      expect(attractor.domain).to eq(:curiosity)
+    end
+
+    it 'sets default mass' do
+      expect(attractor.mass).to eq(1.0)
+    end
+
+    it 'accepts custom mass' do
+      a = described_class.new(content: 'x', mass: 2.5)
+      expect(a.mass).to eq(2.5)
+    end
+
+    it 'sets created_at' do
+      expect(attractor.created_at).to be_a(Time)
+    end
+
+    it 'initializes reinforcement_count to 0' do
+      expect(attractor.reinforcement_count).to eq(0)
+    end
+  end
+
+  describe '#accrete!' do
+    it 'increases mass by default accretion amount' do
+      attractor.accrete!
+      expect(attractor.mass).to be_within(0.001).of(1.15)
+    end
+
+    it 'increases mass by custom amount' do
+      attractor.accrete!(0.5)
+      expect(attractor.mass).to be_within(0.001).of(1.5)
+    end
+
+    it 'increments reinforcement_count' do
+      attractor.accrete!
+      expect(attractor.reinforcement_count).to eq(1)
+    end
+
+    it 'returns self for chaining' do
+      expect(attractor.accrete!).to eq(attractor)
+    end
+  end
+
+  describe '#erode!' do
+    it 'decreases mass by default erosion amount' do
+      attractor.erode!
+      expect(attractor.mass).to be_within(0.001).of(0.95)
+    end
+
+    it 'does not go below zero' do
+      a = described_class.new(content: 'x', mass: 0.03)
+      a.erode!(0.1)
+      expect(a.mass).to eq(0.0)
+    end
+
+    it 'returns self for chaining' do
+      expect(attractor.erode!).to eq(attractor)
+    end
+  end
+
+  describe '#pull_strength_at' do
+    it 'returns positive pull for distance within pull_radius' do
+      strength = attractor.pull_strength_at(distance: 0.5)
+      expect(strength).to be > 0
+    end
+
+    it 'returns zero for distance beyond pull_radius' do
+      strength = attractor.pull_strength_at(distance: 2.0)
+      expect(strength).to eq(0.0)
+    end
+
+    it 'returns zero for zero distance' do
+      strength = attractor.pull_strength_at(distance: 0)
+      expect(strength).to eq(0.0)
+    end
+
+    it 'returns stronger pull for heavier attractors' do
+      heavy = described_class.new(content: 'heavy', mass: 3.0)
+      light = described_class.new(content: 'light', mass: 0.5)
+      expect(heavy.pull_strength_at(distance: 0.5)).to be > light.pull_strength_at(distance: 0.5)
+    end
+
+    it 'returns stronger pull for closer distance' do
+      close_pull = attractor.pull_strength_at(distance: 0.3)
+      far_pull   = attractor.pull_strength_at(distance: 0.8)
+      expect(close_pull).to be > far_pull
+    end
+  end
+
+  describe '#collapsed?' do
+    it 'returns false for normal mass' do
+      expect(attractor.collapsed?).to be false
+    end
+
+    it 'returns true when mass is below collapse threshold' do
+      a = described_class.new(content: 'x', mass: 0.05)
+      expect(a.collapsed?).to be true
+    end
+  end
+
+  describe '#supermassive?' do
+    it 'returns false for normal mass' do
+      expect(attractor.supermassive?).to be false
+    end
+
+    it 'returns true for mass at or above supermassive threshold' do
+      a = described_class.new(content: 'x', mass: 3.0)
+      expect(a.supermassive?).to be true
+    end
+  end
+
+  describe '#mass_label' do
+    it 'returns a symbol label' do
+      expect(attractor.mass_label).to be_a(Symbol)
+    end
+
+    it 'returns :nascent for default mass' do
+      expect(attractor.mass_label).to eq(:nascent)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with expected keys' do
+      h = attractor.to_h
+      expect(h).to include(:id, :content, :domain, :mass, :pull_radius, :decay_rate,
+                           :reinforcement_count, :collapsed, :supermassive, :mass_label, :created_at)
+    end
+  end
+end