lex-bayesian-belief 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 770dcdd91a8320f7de43996caf8d36e8e0e35a89c52c4ddd9995417afc6d1e1d
+  data.tar.gz: a700d35695dd6cf00adca507441852d0dec89a0ea77bbd9683d0442b4782ca62
+SHA512:
+  metadata.gz: 62ddebb2896d4fc62499706ca323ab44b96fd8a6aa69cfcb4959b5820600dacced757d9b0b62a5f1c1baab9b92caba362cc91b5937113aba96e2315087a18acb
+  data.tar.gz: 283e62186e910f6e4d07a2a5a81b91f19e49d64f8a703261f15ff6217ee474e16d286f39fbd28f171e3cf1a21cc0c4e8c1074019e04bf69b670666434961817f

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rspec', '~> 3.13'
+gem 'rubocop', '~> 1.75', require: false
+gem 'rubocop-rspec', require: false
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/lex-bayesian-belief.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/bayesian_belief/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-bayesian-belief'
+  spec.version       = Legion::Extensions::BayesianBelief::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Bayesian Belief'
+  spec.description   = 'Bayesian belief updating engine (prior + evidence = posterior) for brain-modeled agentic AI'
+  spec.homepage      = 'https://github.com/LegionIO/lex-bayesian-belief'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']        = spec.homepage
+  spec.metadata['source_code_uri']     = 'https://github.com/LegionIO/lex-bayesian-belief'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-bayesian-belief'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-bayesian-belief'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-bayesian-belief/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-bayesian-belief.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

data/lib/legion/extensions/bayesian_belief/client.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/bayesian_belief/helpers/constants'
+require 'legion/extensions/bayesian_belief/helpers/belief'
+require 'legion/extensions/bayesian_belief/helpers/belief_network'
+require 'legion/extensions/bayesian_belief/runners/bayesian_belief'
+
+module Legion
+  module Extensions
+    module BayesianBelief
+      class Client
+        include Runners::BayesianBelief
+
+        def initialize(**)
+          @belief_network = Helpers::BeliefNetwork.new
+        end
+
+        private
+
+        attr_reader :belief_network
+      end
+    end
+  end
+end

data/lib/legion/extensions/bayesian_belief/helpers/belief.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module BayesianBelief
+      module Helpers
+        class Belief
+          include Constants
+
+          attr_reader :id, :content, :domain, :prior, :posterior,
+                      :evidence_history, :update_count, :created_at, :last_updated_at
+
+          def initialize(content:, domain:, prior: Constants::DEFAULT_PRIOR)
+            @id               = SecureRandom.uuid
+            @content          = content
+            @domain           = domain
+            @prior            = prior.clamp(Constants::PRIOR_FLOOR, Constants::PRIOR_CEILING)
+            @posterior        = @prior
+            @evidence_history = []
+            @update_count     = 0
+            @created_at       = Time.now.utc
+            @last_updated_at  = @created_at
+          end
+
+          def update(likelihood:, evidence_id:)
+            clamped_likelihood = likelihood.clamp(Constants::LIKELIHOOD_FLOOR, Constants::LIKELIHOOD_CEILING)
+            marginal = (clamped_likelihood * @posterior) + ((1.0 - clamped_likelihood) * (1.0 - @posterior))
+            new_posterior = (clamped_likelihood * @posterior) / marginal
+            @posterior = new_posterior.clamp(Constants::PRIOR_FLOOR, Constants::PRIOR_CEILING)
+            @update_count    += 1
+            @last_updated_at  = Time.now.utc
+
+            @evidence_history << {
+              evidence_id:     evidence_id,
+              likelihood:      clamped_likelihood,
+              posterior_after: @posterior
+            }
+            @evidence_history.shift while @evidence_history.size > Constants::MAX_HISTORY
+
+            @posterior
+          end
+
+          def log_odds
+            Math.log(@posterior / (1.0 - @posterior))
+          end
+
+          def confidence_label
+            Constants::CONFIDENCE_LABELS.each do |range, label|
+              return label if range.cover?(@posterior)
+            end
+            :unknown
+          end
+
+          def surprise(observation_likelihood:)
+            clamped = observation_likelihood.clamp(Constants::LIKELIHOOD_FLOOR, 1.0)
+            -Math.log2(clamped)
+          end
+
+          def reset_to_prior!
+            @posterior       = @prior
+            @update_count    = 0
+            @evidence_history = []
+            @last_updated_at  = Time.now.utc
+            @posterior
+          end
+
+          def stale?(threshold: Constants::STALE_THRESHOLD)
+            (Time.now.utc - @last_updated_at) > threshold
+          end
+
+          def to_h
+            {
+              id:               @id,
+              content:          @content,
+              domain:           @domain,
+              prior:            @prior,
+              posterior:        @posterior,
+              confidence_label: confidence_label,
+              log_odds:         log_odds,
+              update_count:     @update_count,
+              evidence_history: @evidence_history,
+              created_at:       @created_at,
+              last_updated_at:  @last_updated_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/bayesian_belief/helpers/belief_network.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module BayesianBelief
+      module Helpers
+        class BeliefNetwork
+          include Constants
+
+          attr_reader :beliefs
+
+          def initialize
+            @beliefs = {}
+          end
+
+          def add_belief(content:, domain:, prior: Constants::DEFAULT_PRIOR)
+            return nil if @beliefs.size >= Constants::MAX_HYPOTHESES
+
+            belief = Belief.new(content: content, domain: domain, prior: prior)
+            @beliefs[belief.id] = belief
+            belief
+          end
+
+          def update_belief(belief_id:, evidence_id:, likelihood:)
+            belief = @beliefs[belief_id]
+            return nil unless belief
+
+            belief.update(likelihood: likelihood, evidence_id: evidence_id)
+            belief
+          end
+
+          def batch_update(evidence_id:, likelihoods:)
+            return {} if likelihoods.empty?
+
+            updated = {}
+            likelihoods.each do |belief_id, likelihood|
+              belief = update_belief(belief_id: belief_id, evidence_id: evidence_id, likelihood: likelihood)
+              updated[belief_id] = belief.posterior if belief
+            end
+
+            normalize_posteriors(updated.keys)
+            updated
+          end
+
+          def most_probable(domain: nil, limit: 5)
+            filtered(domain).sort_by { |b| -b.posterior }.first(limit)
+          end
+
+          def least_probable(domain: nil, limit: 5)
+            filtered(domain).sort_by(&:posterior).first(limit)
+          end
+
+          def by_domain(domain:)
+            @beliefs.values.select { |b| b.domain == domain }
+          end
+
+          def posterior_distribution(domain: nil)
+            subset = filtered(domain)
+            total  = subset.sum(&:posterior)
+            return {} if total.zero?
+
+            subset.to_h { |b| [b.id, b.posterior / total] }
+          end
+
+          def information_gain(belief_id:, evidence_id:, likelihood:) # rubocop:disable Lint/UnusedMethodArgument
+            belief = @beliefs[belief_id]
+            return 0.0 unless belief
+
+            prior_p = belief.posterior
+            clamped = likelihood.clamp(Constants::LIKELIHOOD_FLOOR, Constants::LIKELIHOOD_CEILING)
+            marginal = (clamped * prior_p) + ((1.0 - clamped) * (1.0 - prior_p))
+            post_p = (clamped * prior_p) / marginal
+            post_p = post_p.clamp(Constants::PRIOR_FLOOR, Constants::PRIOR_CEILING)
+
+            kl_divergence(prior_p, post_p)
+          end
+
+          def entropy(domain: nil)
+            dist = posterior_distribution(domain: domain)
+            return 0.0 if dist.empty?
+
+            -dist.values.sum do |prob|
+              next 0.0 if prob <= 0.0
+
+              prob * Math.log2(prob)
+            end
+          end
+
+          def decay_all
+            @beliefs.each_value do |belief|
+              shift = (belief.posterior - belief.prior) * Constants::DECAY_RATE
+              new_posterior = belief.posterior - shift
+              belief.instance_variable_set(:@posterior, new_posterior.clamp(Constants::PRIOR_FLOOR, Constants::PRIOR_CEILING))
+              belief.instance_variable_set(:@last_updated_at, Time.now.utc)
+            end
+            @beliefs.size
+          end
+
+          def count
+            @beliefs.size
+          end
+
+          def to_h
+            {
+              belief_count: @beliefs.size,
+              beliefs:      @beliefs.transform_values(&:to_h)
+            }
+          end
+
+          private
+
+          def filtered(domain)
+            return @beliefs.values if domain.nil?
+
+            by_domain(domain: domain)
+          end
+
+          def normalize_posteriors(belief_ids)
+            subset = belief_ids.filter_map { |bid| @beliefs[bid] }
+            total  = subset.sum(&:posterior)
+            return if total.zero?
+
+            subset.each do |belief|
+              normalized = (belief.posterior / total).clamp(Constants::PRIOR_FLOOR, Constants::PRIOR_CEILING)
+              belief.instance_variable_set(:@posterior, normalized)
+            end
+          end
+
+          def kl_divergence(prior_p, post_p)
+            return 0.0 if prior_p <= 0.0 || post_p <= 0.0
+
+            prior_q = 1.0 - prior_p
+            post_q  = 1.0 - post_p
+
+            term1 = post_p  * Math.log2(post_p  / prior_p)
+            term2 = post_q  * Math.log2(post_q  / prior_q)
+            term1 + term2
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module BayesianBelief
+      module Helpers
+        module Constants
+          MAX_HYPOTHESES  = 200
+          MAX_EVIDENCE    = 500
+          MAX_HISTORY     = 300
+
+          DEFAULT_PRIOR     = 0.5
+          PRIOR_FLOOR       = 0.001
+          PRIOR_CEILING     = 0.999
+          LIKELIHOOD_FLOOR  = 0.001
+          LIKELIHOOD_CEILING = 0.999
+
+          DECAY_RATE       = 0.01
+          STALE_THRESHOLD  = 120
+
+          CONFIDENCE_LABELS = {
+            (0.9..)     => :certain,
+            (0.7...0.9) => :confident,
+            (0.5...0.7) => :leaning,
+            (0.3...0.5) => :uncertain,
+            (..0.3)     => :doubtful
+          }.freeze
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module BayesianBelief
+      module Runners
+        module BayesianBelief
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def add_bayesian_belief(content:, domain:, prior: nil, **)
+            pri = (prior || Helpers::Constants::DEFAULT_PRIOR).clamp(
+              Helpers::Constants::PRIOR_FLOOR,
+              Helpers::Constants::PRIOR_CEILING
+            )
+            belief = belief_network.add_belief(content: content, domain: domain, prior: pri)
+            unless belief
+              Legion::Logging.warn "[bayesian_belief] add failed: network at capacity (#{Helpers::Constants::MAX_HYPOTHESES})"
+              return { success: false, reason: :capacity_exceeded, max: Helpers::Constants::MAX_HYPOTHESES }
+            end
+
+            Legion::Logging.debug "[bayesian_belief] add: id=#{belief.id[0..7]} domain=#{domain} prior=#{pri.round(3)}"
+            { success: true, belief_id: belief.id, domain: domain, prior: belief.prior, posterior: belief.posterior }
+          end
+
+          def update_bayesian_belief(belief_id:, evidence_id:, likelihood:, **)
+            clamped = likelihood.clamp(Helpers::Constants::LIKELIHOOD_FLOOR, Helpers::Constants::LIKELIHOOD_CEILING)
+            belief  = belief_network.update_belief(belief_id: belief_id, evidence_id: evidence_id, likelihood: clamped)
+            unless belief
+              Legion::Logging.debug "[bayesian_belief] update failed: belief_id=#{belief_id} not found"
+              return { success: false, reason: :not_found, belief_id: belief_id }
+            end
+
+            Legion::Logging.debug "[bayesian_belief] update: id=#{belief_id[0..7]} evidence=#{evidence_id} " \
+                                  "likelihood=#{clamped.round(3)} posterior=#{belief.posterior.round(3)}"
+            {
+              success:          true,
+              belief_id:        belief_id,
+              evidence_id:      evidence_id,
+              likelihood:       clamped,
+              posterior:        belief.posterior,
+              confidence_label: belief.confidence_label,
+              update_count:     belief.update_count
+            }
+          end
+
+          def batch_bayesian_update(evidence_id:, likelihoods:, **)
+            if likelihoods.nil? || likelihoods.empty?
+              Legion::Logging.debug '[bayesian_belief] batch_update: empty likelihoods, skipping'
+              return { success: true, updated: 0, posteriors: {} }
+            end
+
+            posteriors = belief_network.batch_update(evidence_id: evidence_id, likelihoods: likelihoods)
+            Legion::Logging.debug "[bayesian_belief] batch_update: evidence=#{evidence_id} updated=#{posteriors.size}"
+            { success: true, evidence_id: evidence_id, updated: posteriors.size, posteriors: posteriors }
+          end
+
+          def most_probable_beliefs(domain: nil, limit: 5, **)
+            beliefs = belief_network.most_probable(domain: domain, limit: limit)
+            Legion::Logging.debug "[bayesian_belief] most_probable: domain=#{domain.inspect} count=#{beliefs.size}"
+            { success: true, beliefs: beliefs.map(&:to_h), count: beliefs.size }
+          end
+
+          def least_probable_beliefs(domain: nil, limit: 5, **)
+            beliefs = belief_network.least_probable(domain: domain, limit: limit)
+            Legion::Logging.debug "[bayesian_belief] least_probable: domain=#{domain.inspect} count=#{beliefs.size}"
+            { success: true, beliefs: beliefs.map(&:to_h), count: beliefs.size }
+          end
+
+          def posterior_distribution(domain: nil, **)
+            dist = belief_network.posterior_distribution(domain: domain)
+            Legion::Logging.debug "[bayesian_belief] posterior_distribution: domain=#{domain.inspect} size=#{dist.size}"
+            { success: true, distribution: dist, size: dist.size }
+          end
+
+          def information_gain(belief_id:, evidence_id:, likelihood:, **)
+            clamped = likelihood.clamp(Helpers::Constants::LIKELIHOOD_FLOOR, Helpers::Constants::LIKELIHOOD_CEILING)
+            gain    = belief_network.information_gain(belief_id: belief_id, evidence_id: evidence_id, likelihood: clamped)
+            Legion::Logging.debug "[bayesian_belief] information_gain: id=#{belief_id[0..7]} likelihood=#{clamped.round(3)} gain=#{gain.round(4)}"
+            { success: true, belief_id: belief_id, evidence_id: evidence_id, likelihood: clamped, information_gain: gain }
+          end
+
+          def belief_entropy(domain: nil, **)
+            ent = belief_network.entropy(domain: domain)
+            Legion::Logging.debug "[bayesian_belief] entropy: domain=#{domain.inspect} entropy=#{ent.round(4)}"
+            { success: true, domain: domain, entropy: ent }
+          end
+
+          def update_bayesian_beliefs(**)
+            decayed = belief_network.decay_all
+            Legion::Logging.debug "[bayesian_belief] decay cycle: beliefs_updated=#{decayed}"
+            { success: true, decayed: decayed }
+          end
+
+          def bayesian_belief_stats(**)
+            total = belief_network.count
+            ent   = belief_network.entropy
+            most  = belief_network.most_probable(limit: 1).first
+            least = belief_network.least_probable(limit: 1).first
+
+            Legion::Logging.debug "[bayesian_belief] stats: total=#{total} entropy=#{ent.round(4)}"
+            {
+              success:        true,
+              total_beliefs:  total,
+              entropy:        ent,
+              most_probable:  most&.to_h,
+              least_probable: least&.to_h,
+              capacity:       Helpers::Constants::MAX_HYPOTHESES
+            }
+          end
+
+          private
+
+          def belief_network
+            @belief_network ||= Helpers::BeliefNetwork.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/bayesian_belief.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/bayesian_belief/version'
+require 'legion/extensions/bayesian_belief/helpers/constants'
+require 'legion/extensions/bayesian_belief/helpers/belief'
+require 'legion/extensions/bayesian_belief/helpers/belief_network'
+require 'legion/extensions/bayesian_belief/runners/bayesian_belief'
+
+module Legion
+  module Extensions
+    module BayesianBelief
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/bayesian_belief/client'
+
+RSpec.describe Legion::Extensions::BayesianBelief::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to all runner methods' do
+    expect(client).to respond_to(:add_bayesian_belief)
+    expect(client).to respond_to(:update_bayesian_belief)
+    expect(client).to respond_to(:batch_bayesian_update)
+    expect(client).to respond_to(:most_probable_beliefs)
+    expect(client).to respond_to(:least_probable_beliefs)
+    expect(client).to respond_to(:posterior_distribution)
+    expect(client).to respond_to(:information_gain)
+    expect(client).to respond_to(:belief_entropy)
+    expect(client).to respond_to(:update_bayesian_beliefs)
+    expect(client).to respond_to(:bayesian_belief_stats)
+  end
+end

data/spec/legion/extensions/bayesian_belief/helpers/belief_network_spec.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::BayesianBelief::Helpers::BeliefNetwork do
+  let(:network) { described_class.new }
+  let(:consts)  { Legion::Extensions::BayesianBelief::Helpers::Constants }
+
+  def add(content: 'hypothesis', domain: :general, prior: 0.5)
+    network.add_belief(content: content, domain: domain, prior: prior)
+  end
+
+  describe '#add_belief' do
+    it 'adds a belief and returns it' do
+      belief = add
+      expect(belief).to be_a(Legion::Extensions::BayesianBelief::Helpers::Belief)
+      expect(network.count).to eq(1)
+    end
+
+    it 'uses provided prior' do
+      belief = add(prior: 0.7)
+      expect(belief.prior).to eq(0.7)
+    end
+  end
+
+  describe '#update_belief' do
+    it 'updates and returns the belief' do
+      belief = add
+      result = network.update_belief(belief_id: belief.id, evidence_id: 'ev-1', likelihood: 0.9)
+      expect(result).to be_a(Legion::Extensions::BayesianBelief::Helpers::Belief)
+      expect(result.posterior).to be > 0.5
+    end
+
+    it 'returns nil for unknown belief_id' do
+      result = network.update_belief(belief_id: 'nonexistent', evidence_id: 'ev-1', likelihood: 0.8)
+      expect(result).to be_nil
+    end
+  end
+
+  describe '#batch_update' do
+    it 'updates multiple beliefs with same evidence' do
+      b1 = add(content: 'h1', domain: :test)
+      b2 = add(content: 'h2', domain: :test)
+      likelihoods = { b1.id => 0.8, b2.id => 0.3 }
+
+      result = network.batch_update(evidence_id: 'ev-batch', likelihoods: likelihoods)
+      expect(result.size).to eq(2)
+    end
+
+    it 'returns empty hash for empty likelihoods' do
+      result = network.batch_update(evidence_id: 'ev-1', likelihoods: {})
+      expect(result).to be_empty
+    end
+  end
+
+  describe '#most_probable' do
+    it 'returns beliefs sorted by posterior descending' do
+      add(content: 'low',  domain: :test, prior: 0.2)
+      add(content: 'high', domain: :test, prior: 0.8)
+      add(content: 'mid',  domain: :test, prior: 0.5)
+
+      beliefs = network.most_probable
+      expect(beliefs.first.posterior).to be >= beliefs.last.posterior
+    end
+
+    it 'limits results' do
+      3.times { |idx| add(content: "h#{idx}", domain: :test) }
+      expect(network.most_probable(limit: 2).size).to eq(2)
+    end
+
+    it 'filters by domain' do
+      add(content: 'a', domain: :alpha)
+      add(content: 'b', domain: :beta)
+      results = network.most_probable(domain: :alpha)
+      expect(results.all? { |b| b.domain == :alpha }).to be true
+    end
+  end
+
+  describe '#least_probable' do
+    it 'returns beliefs sorted by posterior ascending' do
+      add(content: 'low',  domain: :test, prior: 0.1)
+      add(content: 'high', domain: :test, prior: 0.9)
+
+      beliefs = network.least_probable
+      expect(beliefs.first.posterior).to be <= beliefs.last.posterior
+    end
+  end
+
+  describe '#by_domain' do
+    it 'returns only beliefs in specified domain' do
+      add(content: 'a', domain: :alpha)
+      add(content: 'b', domain: :beta)
+      result = network.by_domain(domain: :alpha)
+      expect(result.size).to eq(1)
+      expect(result.first.domain).to eq(:alpha)
+    end
+  end
+
+  describe '#posterior_distribution' do
+    it 'returns normalized probabilities that sum to ~1' do
+      add(content: 'h1', domain: :test, prior: 0.3)
+      add(content: 'h2', domain: :test, prior: 0.7)
+
+      dist = network.posterior_distribution(domain: :test)
+      expect(dist.values.sum).to be_within(0.001).of(1.0)
+    end
+
+    it 'returns empty hash when no beliefs exist' do
+      expect(network.posterior_distribution).to eq({})
+    end
+  end
+
+  describe '#information_gain' do
+    it 'returns a non-negative float' do
+      belief = add
+      gain = network.information_gain(belief_id: belief.id, evidence_id: 'ev-1', likelihood: 0.9)
+      expect(gain).to be >= 0.0
+    end
+
+    it 'returns 0.0 for unknown belief' do
+      gain = network.information_gain(belief_id: 'nonexistent', evidence_id: 'ev-1', likelihood: 0.8)
+      expect(gain).to eq(0.0)
+    end
+
+    it 'does not mutate the belief posterior' do
+      belief = add
+      before = belief.posterior
+      network.information_gain(belief_id: belief.id, evidence_id: 'ev-1', likelihood: 0.9)
+      expect(belief.posterior).to eq(before)
+    end
+
+    it 'returns higher gain for more extreme likelihoods' do
+      b1 = add(content: 'h1')
+      b2 = add(content: 'h2')
+
+      gain_strong = network.information_gain(belief_id: b1.id, evidence_id: 'ev', likelihood: 0.95)
+      gain_weak   = network.information_gain(belief_id: b2.id, evidence_id: 'ev', likelihood: 0.55)
+      expect(gain_strong).to be > gain_weak
+    end
+  end
+
+  describe '#entropy' do
+    it 'returns 0.0 when no beliefs' do
+      expect(network.entropy).to eq(0.0)
+    end
+
+    it 'returns a positive float when beliefs exist' do
+      2.times { |idx| add(content: "h#{idx}") }
+      expect(network.entropy).to be > 0.0
+    end
+  end
+
+  describe '#decay_all' do
+    it 'returns count of beliefs updated' do
+      3.times { |idx| add(content: "h#{idx}") }
+      expect(network.decay_all).to eq(3)
+    end
+
+    it 'drifts posterior toward prior' do
+      belief = add(prior: 0.5)
+      belief.update(likelihood: 0.9, evidence_id: 'ev-1')
+      before = belief.posterior
+
+      network.decay_all
+
+      after = belief.posterior
+      expect(after).to be < before
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes belief_count and beliefs keys' do
+      add
+      hash = network.to_h
+      expect(hash).to have_key(:belief_count)
+      expect(hash).to have_key(:beliefs)
+      expect(hash[:belief_count]).to eq(1)
+    end
+  end
+end

data/spec/legion/extensions/bayesian_belief/helpers/belief_spec.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::BayesianBelief::Helpers::Belief do
+  let(:belief) { described_class.new(content: 'test hypothesis', domain: :general) }
+
+  describe '#initialize' do
+    it 'sets prior and posterior to default' do
+      expect(belief.prior).to eq(Legion::Extensions::BayesianBelief::Helpers::Constants::DEFAULT_PRIOR)
+      expect(belief.posterior).to eq(belief.prior)
+    end
+
+    it 'generates a uuid id' do
+      expect(belief.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'starts with empty evidence_history' do
+      expect(belief.evidence_history).to be_empty
+    end
+
+    it 'clamps prior to floor/ceiling' do
+      high = described_class.new(content: 'test', domain: :x, prior: 1.5)
+      low  = described_class.new(content: 'test', domain: :x, prior: -0.1)
+      expect(high.prior).to eq(Legion::Extensions::BayesianBelief::Helpers::Constants::PRIOR_CEILING)
+      expect(low.prior).to eq(Legion::Extensions::BayesianBelief::Helpers::Constants::PRIOR_FLOOR)
+    end
+  end
+
+  describe '#update' do
+    it 'raises posterior when likelihood is high' do
+      before = belief.posterior
+      belief.update(likelihood: 0.9, evidence_id: 'ev-1')
+      expect(belief.posterior).to be > before
+    end
+
+    it 'lowers posterior when likelihood is low' do
+      before = belief.posterior
+      belief.update(likelihood: 0.1, evidence_id: 'ev-1')
+      expect(belief.posterior).to be < before
+    end
+
+    it 'records evidence in history' do
+      belief.update(likelihood: 0.8, evidence_id: 'ev-1')
+      expect(belief.evidence_history.size).to eq(1)
+      expect(belief.evidence_history.first[:evidence_id]).to eq('ev-1')
+    end
+
+    it 'increments update_count' do
+      belief.update(likelihood: 0.7, evidence_id: 'ev-1')
+      belief.update(likelihood: 0.6, evidence_id: 'ev-2')
+      expect(belief.update_count).to eq(2)
+    end
+
+    it 'clamps posterior within bounds' do
+      10.times { |idx| belief.update(likelihood: 0.999, evidence_id: "ev-#{idx}") }
+      expect(belief.posterior).to be <= Legion::Extensions::BayesianBelief::Helpers::Constants::PRIOR_CEILING
+      expect(belief.posterior).to be >= Legion::Extensions::BayesianBelief::Helpers::Constants::PRIOR_FLOOR
+    end
+  end
+
+  describe '#log_odds' do
+    it 'returns 0.0 at prior 0.5' do
+      expect(belief.log_odds).to be_within(0.001).of(0.0)
+    end
+
+    it 'returns positive value when posterior > 0.5' do
+      belief.update(likelihood: 0.9, evidence_id: 'ev-1')
+      expect(belief.log_odds).to be > 0.0
+    end
+
+    it 'returns negative value when posterior < 0.5' do
+      belief.update(likelihood: 0.1, evidence_id: 'ev-1')
+      expect(belief.log_odds).to be < 0.0
+    end
+  end
+
+  describe '#confidence_label' do
+    it 'returns :leaning for default prior 0.5' do
+      expect(belief.confidence_label).to eq(:leaning)
+    end
+
+    it 'returns :certain for high posterior' do
+      high = described_class.new(content: 'test', domain: :x, prior: 0.95)
+      expect(high.confidence_label).to eq(:certain)
+    end
+
+    it 'returns :doubtful for low posterior' do
+      low = described_class.new(content: 'test', domain: :x, prior: 0.1)
+      expect(low.confidence_label).to eq(:doubtful)
+    end
+
+    it 'returns :confident for posterior in 0.7..0.9' do
+      conf = described_class.new(content: 'test', domain: :x, prior: 0.8)
+      expect(conf.confidence_label).to eq(:confident)
+    end
+
+    it 'returns :uncertain for posterior in 0.3..0.5' do
+      unc = described_class.new(content: 'test', domain: :x, prior: 0.4)
+      expect(unc.confidence_label).to eq(:uncertain)
+    end
+  end
+
+  describe '#surprise' do
+    it 'returns 0.0 for certain observation (likelihood 1.0)' do
+      expect(belief.surprise(observation_likelihood: 1.0)).to be_within(0.001).of(0.0)
+    end
+
+    it 'returns positive surprise for unlikely observation' do
+      expect(belief.surprise(observation_likelihood: 0.125)).to be_within(0.001).of(3.0)
+    end
+  end
+
+  describe '#reset_to_prior!' do
+    it 'resets posterior to original prior' do
+      belief.update(likelihood: 0.9, evidence_id: 'ev-1')
+      expect(belief.posterior).not_to eq(belief.prior)
+      belief.reset_to_prior!
+      expect(belief.posterior).to eq(belief.prior)
+    end
+
+    it 'clears evidence history and update count' do
+      belief.update(likelihood: 0.8, evidence_id: 'ev-1')
+      belief.reset_to_prior!
+      expect(belief.evidence_history).to be_empty
+      expect(belief.update_count).to eq(0)
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all required keys' do
+      hash = belief.to_h
+      %i[id content domain prior posterior confidence_label log_odds update_count
+         evidence_history created_at last_updated_at].each do |key|
+        expect(hash).to have_key(key)
+      end
+    end
+  end
+end

data/spec/legion/extensions/bayesian_belief/runners/bayesian_belief_spec.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/bayesian_belief/client'
+
+RSpec.describe Legion::Extensions::BayesianBelief::Runners::BayesianBelief do
+  let(:client) { Legion::Extensions::BayesianBelief::Client.new }
+
+  describe '#add_bayesian_belief' do
+    it 'adds a belief and returns success' do
+      result = client.add_bayesian_belief(content: 'test hypothesis', domain: :general)
+      expect(result[:success]).to be true
+      expect(result[:belief_id]).to match(/\A[0-9a-f-]{36}\z/)
+      expect(result[:domain]).to eq(:general)
+    end
+
+    it 'uses default prior when none provided' do
+      result = client.add_bayesian_belief(content: 'test', domain: :test)
+      expect(result[:prior]).to eq(Legion::Extensions::BayesianBelief::Helpers::Constants::DEFAULT_PRIOR)
+    end
+
+    it 'uses provided prior' do
+      result = client.add_bayesian_belief(content: 'test', domain: :test, prior: 0.7)
+      expect(result[:prior]).to be_within(0.001).of(0.7)
+    end
+  end
+
+  describe '#update_bayesian_belief' do
+    it 'updates an existing belief' do
+      added  = client.add_bayesian_belief(content: 'h1', domain: :test)
+      result = client.update_bayesian_belief(
+        belief_id:   added[:belief_id],
+        evidence_id: 'ev-1',
+        likelihood:  0.9
+      )
+      expect(result[:success]).to be true
+      expect(result[:posterior]).to be > 0.5
+      expect(result[:update_count]).to eq(1)
+    end
+
+    it 'returns not_found for unknown belief' do
+      result = client.update_bayesian_belief(belief_id: 'nonexistent', evidence_id: 'ev-1', likelihood: 0.8)
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:not_found)
+    end
+
+    it 'returns confidence_label' do
+      added  = client.add_bayesian_belief(content: 'h1', domain: :test, prior: 0.95)
+      result = client.update_bayesian_belief(
+        belief_id:   added[:belief_id],
+        evidence_id: 'ev-1',
+        likelihood:  0.9
+      )
+      expect(result[:confidence_label]).to eq(:certain)
+    end
+  end
+
+  describe '#batch_bayesian_update' do
+    it 'updates multiple beliefs' do
+      b1 = client.add_bayesian_belief(content: 'h1', domain: :test)
+      b2 = client.add_bayesian_belief(content: 'h2', domain: :test)
+      likelihoods = { b1[:belief_id] => 0.8, b2[:belief_id] => 0.3 }
+
+      result = client.batch_bayesian_update(evidence_id: 'ev-batch', likelihoods: likelihoods)
+      expect(result[:success]).to be true
+      expect(result[:updated]).to eq(2)
+    end
+
+    it 'handles empty likelihoods gracefully' do
+      result = client.batch_bayesian_update(evidence_id: 'ev-1', likelihoods: {})
+      expect(result[:success]).to be true
+      expect(result[:updated]).to eq(0)
+    end
+  end
+
+  describe '#most_probable_beliefs' do
+    it 'returns beliefs sorted by probability' do
+      client.add_bayesian_belief(content: 'low',  domain: :ranked, prior: 0.2)
+      client.add_bayesian_belief(content: 'high', domain: :ranked, prior: 0.8)
+
+      result = client.most_probable_beliefs(domain: :ranked)
+      expect(result[:success]).to be true
+      expect(result[:beliefs].first[:posterior]).to be >= result[:beliefs].last[:posterior]
+    end
+
+    it 'respects limit parameter' do
+      5.times { |idx| client.add_bayesian_belief(content: "h#{idx}", domain: :limit_test) }
+      result = client.most_probable_beliefs(domain: :limit_test, limit: 3)
+      expect(result[:count]).to eq(3)
+    end
+  end
+
+  describe '#least_probable_beliefs' do
+    it 'returns beliefs sorted by ascending probability' do
+      client.add_bayesian_belief(content: 'low',  domain: :sorted, prior: 0.1)
+      client.add_bayesian_belief(content: 'high', domain: :sorted, prior: 0.9)
+
+      result = client.least_probable_beliefs(domain: :sorted)
+      expect(result[:beliefs].first[:posterior]).to be <= result[:beliefs].last[:posterior]
+    end
+  end
+
+  describe '#posterior_distribution' do
+    it 'returns normalized distribution summing to 1' do
+      client.add_bayesian_belief(content: 'h1', domain: :dist, prior: 0.3)
+      client.add_bayesian_belief(content: 'h2', domain: :dist, prior: 0.7)
+
+      result = client.posterior_distribution(domain: :dist)
+      expect(result[:success]).to be true
+      expect(result[:distribution].values.sum).to be_within(0.001).of(1.0)
+    end
+
+    it 'returns empty distribution when no beliefs' do
+      result = client.posterior_distribution(domain: :empty_domain)
+      expect(result[:distribution]).to be_empty
+    end
+  end
+
+  describe '#information_gain' do
+    it 'computes gain without mutating the belief' do
+      added   = client.add_bayesian_belief(content: 'h1', domain: :ig)
+      before  = added[:posterior]
+      result  = client.information_gain(belief_id: added[:belief_id], evidence_id: 'ev-1', likelihood: 0.9)
+      expect(result[:success]).to be true
+      expect(result[:information_gain]).to be >= 0.0
+
+      check = client.most_probable_beliefs(domain: :ig)
+      expect(check[:beliefs].first[:posterior]).to be_within(0.001).of(before)
+    end
+  end
+
+  describe '#belief_entropy' do
+    it 'returns entropy for all beliefs' do
+      client.add_bayesian_belief(content: 'h1', domain: :ent)
+      client.add_bayesian_belief(content: 'h2', domain: :ent)
+
+      result = client.belief_entropy(domain: :ent)
+      expect(result[:success]).to be true
+      expect(result[:entropy]).to be >= 0.0
+    end
+
+    it 'returns 0.0 entropy when no beliefs exist' do
+      fresh = Legion::Extensions::BayesianBelief::Client.new
+      result = fresh.belief_entropy
+      expect(result[:entropy]).to eq(0.0)
+    end
+  end
+
+  describe '#update_bayesian_beliefs (decay)' do
+    it 'returns success and decayed count' do
+      2.times { |idx| client.add_bayesian_belief(content: "h#{idx}", domain: :decay) }
+      result = client.update_bayesian_beliefs
+      expect(result[:success]).to be true
+      expect(result[:decayed]).to eq(2)
+    end
+  end
+
+  describe '#bayesian_belief_stats' do
+    it 'returns stats hash with expected keys' do
+      client.add_bayesian_belief(content: 'h1', domain: :stats)
+      result = client.bayesian_belief_stats
+      expect(result[:success]).to be true
+      expect(result).to have_key(:total_beliefs)
+      expect(result).to have_key(:entropy)
+      expect(result).to have_key(:most_probable)
+      expect(result).to have_key(:least_probable)
+      expect(result).to have_key(:capacity)
+    end
+
+    it 'returns nil for most/least probable when no beliefs' do
+      fresh  = Legion::Extensions::BayesianBelief::Client.new
+      result = fresh.bayesian_belief_stats
+      expect(result[:most_probable]).to be_nil
+      expect(result[:least_probable]).to be_nil
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+module Legion
+  module Logging
+    def self.debug(_msg); end
+    def self.info(_msg); end
+    def self.warn(_msg); end
+    def self.error(_msg); end
+  end
+end
+
+require 'legion/extensions/bayesian_belief'
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = '.rspec_status'
+  config.disable_monkey_patching!
+  config.expect_with(:rspec) { |c| c.syntax = :expect }
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: lex-bayesian-belief
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Esity
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: legion-gaia
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Bayesian belief updating engine (prior + evidence = posterior) for brain-modeled
+  agentic AI
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-bayesian-belief.gemspec
+- lib/legion/extensions/bayesian_belief.rb
+- lib/legion/extensions/bayesian_belief/client.rb
+- lib/legion/extensions/bayesian_belief/helpers/belief.rb
+- lib/legion/extensions/bayesian_belief/helpers/belief_network.rb
+- lib/legion/extensions/bayesian_belief/helpers/constants.rb
+- lib/legion/extensions/bayesian_belief/runners/bayesian_belief.rb
+- lib/legion/extensions/bayesian_belief/version.rb
+- spec/legion/extensions/bayesian_belief/client_spec.rb
+- spec/legion/extensions/bayesian_belief/helpers/belief_network_spec.rb
+- spec/legion/extensions/bayesian_belief/helpers/belief_spec.rb
+- spec/legion/extensions/bayesian_belief/runners/bayesian_belief_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-bayesian-belief
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-bayesian-belief
+  source_code_uri: https://github.com/LegionIO/lex-bayesian-belief
+  documentation_uri: https://github.com/LegionIO/lex-bayesian-belief
+  changelog_uri: https://github.com/LegionIO/lex-bayesian-belief
+  bug_tracker_uri: https://github.com/LegionIO/lex-bayesian-belief/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: LEX Bayesian Belief
+test_files: []