lex-agentic-inference 0.1.0

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

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Inference::PredictiveCoding::Helpers::PredictionError do
+  let(:constants) { Legion::Extensions::Agentic::Inference::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/agentic/inference/predictive_coding/runners/predictive_coding_spec.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/inference/predictive_coding/client'
+
+RSpec.describe Legion::Extensions::Agentic::Inference::PredictiveCoding::Runners::PredictiveCoding do
+  let(:client) { Legion::Extensions::Agentic::Inference::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::Agentic::Inference::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/legion/extensions/agentic/inference/predictive_processing/client_spec.rb

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

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

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