lex-hypothesis-testing 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 507714e37b488f457d0272db01812b1c653b7743bf94a6d8e13d3a409e9813e7
+  data.tar.gz: b77ad37b8162ea096e222440f2b512021f7aacaf4d824987de6d23f2c26c4936
+SHA512:
+  metadata.gz: 4bbef8ca040aabb9ba210897a4fb0b133e17948771d9664374accf08121fa47aa0b65f28004a5a74612c6823bbe9a35b4467a013ffa216e3c5b44b2286aca3a9
+  data.tar.gz: 3ac381ccf9e26507b1881e12f0962287281e8a7ec9636c0d3cdc72734312bb2e4d30af565f498cdf3e7e1f72867e62fcdcb2c05338201863f1c44207d8108f49

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-hypothesis-testing.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/hypothesis_testing/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-hypothesis-testing'
+  spec.version       = Legion::Extensions::HypothesisTesting::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Hypothesis Testing'
+  spec.description   = 'Scientific hypothesis testing cycle for brain-modeled agentic AI — ' \
+                       'Bayesian evidence accumulation, lifecycle management, competing hypotheses'
+  spec.homepage      = 'https://github.com/LegionIO/lex-hypothesis-testing'
+  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-hypothesis-testing'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-hypothesis-testing'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-hypothesis-testing'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-hypothesis-testing/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-hypothesis-testing.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/hypothesis_testing/helpers/constants'
+require 'legion/extensions/hypothesis_testing/helpers/hypothesis'
+require 'legion/extensions/hypothesis_testing/helpers/hypothesis_engine'
+require 'legion/extensions/hypothesis_testing/runners/hypothesis_testing'
+
+module Legion
+  module Extensions
+    module HypothesisTesting
+      class Client
+        include Runners::HypothesisTesting
+
+        def initialize(**)
+          @hypothesis_engine = Helpers::HypothesisEngine.new
+        end
+
+        private
+
+        attr_reader :hypothesis_engine
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module HypothesisTesting
+      module Helpers
+        module Constants
+          MAX_HYPOTHESES             = 300
+          CONFIRMATION_THRESHOLD     = 0.8
+          DISCONFIRMATION_THRESHOLD  = 0.2
+          EVIDENCE_WEIGHT            = 0.1
+          PRIOR_DEFAULT              = 0.5
+
+          STATUS_LABELS = {
+            proposed:     'Proposed',
+            testing:      'Testing',
+            confirmed:    'Confirmed',
+            disconfirmed: 'Disconfirmed',
+            inconclusive: 'Inconclusive'
+          }.freeze
+
+          CONFIDENCE_LABELS = [
+            [0.9..1.0,  'certain'],
+            [0.7...0.9, 'confident'],
+            [0.5...0.7, 'leaning'],
+            [0.3...0.5, 'uncertain'],
+            [0.0...0.3, 'agnostic']
+          ].freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/hypothesis_testing/helpers/hypothesis.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module HypothesisTesting
+      module Helpers
+        class Hypothesis
+          include Constants
+
+          attr_reader :id, :description, :domain, :prior, :posterior,
+                      :evidence_count, :status, :created_at
+
+          def initialize(description:, domain: 'general', prior: Constants::PRIOR_DEFAULT)
+            @id             = SecureRandom.uuid
+            @description    = description
+            @domain         = domain
+            @prior          = prior.clamp(0.0, 1.0)
+            @posterior      = @prior
+            @evidence_count = 0
+            @status         = :proposed
+            @created_at     = Time.now.utc
+          end
+
+          def update_posterior!(evidence_strength:, supporting: true)
+            return self if @status == :confirmed || @status == :disconfirmed
+
+            @status = :testing
+            weight  = Constants::EVIDENCE_WEIGHT * evidence_strength.clamp(0.0, 1.0)
+
+            @posterior = if supporting
+                           @posterior + (weight * (1.0 - @posterior))
+                         else
+                           @posterior - (weight * @posterior)
+                         end
+
+            @posterior = @posterior.clamp(0.0, 1.0).round(10)
+            @evidence_count += 1
+            self
+          end
+
+          def confirm!
+            @status    = :confirmed
+            @posterior = [@posterior, Constants::CONFIRMATION_THRESHOLD].max.round(10)
+            self
+          end
+
+          def disconfirm!
+            @status    = :disconfirmed
+            @posterior = [@posterior, Constants::DISCONFIRMATION_THRESHOLD].min.round(10)
+            self
+          end
+
+          def confidence_label
+            Constants::CONFIDENCE_LABELS.each do |range, label|
+              return label if range.cover?(@posterior)
+            end
+            'agnostic'
+          end
+
+          def to_h
+            {
+              id:               @id,
+              description:      @description,
+              domain:           @domain,
+              prior:            @prior,
+              posterior:        @posterior,
+              evidence_count:   @evidence_count,
+              status:           @status,
+              confidence_label: confidence_label,
+              created_at:       @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/hypothesis_testing/helpers/hypothesis_engine.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module HypothesisTesting
+      module Helpers
+        class HypothesisEngine
+          include Constants
+
+          attr_reader :hypotheses
+
+          def initialize
+            @hypotheses = {}
+          end
+
+          def propose(description:, domain: 'general', prior: Constants::PRIOR_DEFAULT)
+            evict_oldest! if @hypotheses.size >= Constants::MAX_HYPOTHESES
+
+            h = Hypothesis.new(description: description, domain: domain, prior: prior)
+            @hypotheses[h.id] = h
+            h
+          end
+
+          def test_hypothesis(hypothesis_id:, evidence_strength:, supporting: true)
+            h = @hypotheses[hypothesis_id]
+            return nil unless h
+
+            h.update_posterior!(evidence_strength: evidence_strength, supporting: supporting)
+            evaluate(hypothesis_id)
+            h
+          end
+
+          def evaluate(hypothesis_id)
+            h = @hypotheses[hypothesis_id]
+            return nil unless h
+            return h if %i[confirmed disconfirmed].include?(h.status)
+
+            if h.posterior >= Constants::CONFIRMATION_THRESHOLD
+              h.confirm!
+            elsif h.posterior <= Constants::DISCONFIRMATION_THRESHOLD
+              h.disconfirm!
+            else
+              h
+            end
+          end
+
+          def competing_hypotheses(domain:)
+            @hypotheses.values.select { |h| h.domain == domain }
+          end
+
+          def most_confident(limit: 5)
+            @hypotheses.values
+                       .sort_by { |h| -h.posterior }
+                       .first(limit)
+          end
+
+          def confirmation_rate
+            total = @hypotheses.values.count { |h| %i[confirmed disconfirmed].include?(h.status) }
+            return 0.0 if total.zero?
+
+            confirmed = @hypotheses.values.count { |h| h.status == :confirmed }
+            (confirmed.to_f / total).round(10)
+          end
+
+          def hypothesis_report
+            by_status = @hypotheses.values.group_by(&:status).transform_values(&:count)
+            {
+              total:             @hypotheses.size,
+              by_status:         by_status,
+              confirmation_rate: confirmation_rate,
+              most_confident:    most_confident(limit: 3).map(&:to_h)
+            }
+          end
+
+          def to_h
+            {
+              hypotheses:        @hypotheses.values.map(&:to_h),
+              confirmation_rate: confirmation_rate,
+              total:             @hypotheses.size
+            }
+          end
+
+          private
+
+          def evict_oldest!
+            oldest_key = @hypotheses.min_by { |_, h| h.created_at }&.first
+            @hypotheses.delete(oldest_key) if oldest_key
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module HypothesisTesting
+      module Runners
+        module HypothesisTesting
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def propose_hypothesis(description:, domain: 'general', prior: Helpers::Constants::PRIOR_DEFAULT, **)
+            h = hypothesis_engine.propose(description: description, domain: domain, prior: prior)
+            Legion::Logging.debug "[hypothesis_testing] proposed id=#{h.id[0..7]} domain=#{domain} prior=#{prior}"
+            {
+              hypothesis_id:    h.id,
+              description:      h.description,
+              domain:           h.domain,
+              prior:            h.prior,
+              posterior:        h.posterior,
+              status:           h.status,
+              confidence_label: h.confidence_label
+            }
+          end
+
+          def test_hypothesis(hypothesis_id:, evidence_strength:, supporting: true, **)
+            h = hypothesis_engine.test_hypothesis(
+              hypothesis_id:     hypothesis_id,
+              evidence_strength: evidence_strength,
+              supporting:        supporting
+            )
+            unless h
+              Legion::Logging.debug "[hypothesis_testing] test failed: #{hypothesis_id[0..7]} not found"
+              return { tested: false, reason: :not_found }
+            end
+
+            Legion::Logging.info "[hypothesis_testing] tested #{hypothesis_id[0..7]} " \
+                                 "supporting=#{supporting} strength=#{evidence_strength} " \
+                                 "posterior=#{h.posterior.round(4)} status=#{h.status}"
+            {
+              tested:           true,
+              hypothesis_id:    h.id,
+              posterior:        h.posterior,
+              evidence_count:   h.evidence_count,
+              status:           h.status,
+              confidence_label: h.confidence_label
+            }
+          end
+
+          def evaluate_hypothesis(hypothesis_id:, **)
+            h = hypothesis_engine.evaluate(hypothesis_id)
+            unless h
+              Legion::Logging.debug "[hypothesis_testing] evaluate failed: #{hypothesis_id[0..7]} not found"
+              return { found: false }
+            end
+
+            Legion::Logging.debug "[hypothesis_testing] evaluated #{hypothesis_id[0..7]} status=#{h.status}"
+            {
+              found:            true,
+              hypothesis_id:    h.id,
+              status:           h.status,
+              posterior:        h.posterior,
+              confidence_label: h.confidence_label,
+              evidence_count:   h.evidence_count
+            }
+          end
+
+          def competing_hypotheses(domain:, **)
+            hypotheses = hypothesis_engine.competing_hypotheses(domain: domain)
+            Legion::Logging.debug "[hypothesis_testing] competing count=#{hypotheses.size} domain=#{domain}"
+            {
+              domain:     domain,
+              count:      hypotheses.size,
+              hypotheses: hypotheses.map(&:to_h)
+            }
+          end
+
+          def most_confident_hypotheses(limit: 5, **)
+            hypotheses = hypothesis_engine.most_confident(limit: limit)
+            Legion::Logging.debug "[hypothesis_testing] most_confident count=#{hypotheses.size}"
+            {
+              count:      hypotheses.size,
+              hypotheses: hypotheses.map(&:to_h)
+            }
+          end
+
+          def hypothesis_report(**)
+            report = hypothesis_engine.hypothesis_report
+            Legion::Logging.debug "[hypothesis_testing] report total=#{report[:total]} " \
+                                  "confirmation_rate=#{report[:confirmation_rate].round(4)}"
+            report
+          end
+
+          def get_hypothesis(hypothesis_id:, **)
+            h = hypothesis_engine.hypotheses[hypothesis_id]
+            return { found: false } unless h
+
+            { found: true, hypothesis: h.to_h }
+          end
+
+          private
+
+          def hypothesis_engine
+            @hypothesis_engine ||= Helpers::HypothesisEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/hypothesis_testing.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/hypothesis_testing/version'
+require 'legion/extensions/hypothesis_testing/helpers/constants'
+require 'legion/extensions/hypothesis_testing/helpers/hypothesis'
+require 'legion/extensions/hypothesis_testing/helpers/hypothesis_engine'
+require 'legion/extensions/hypothesis_testing/runners/hypothesis_testing'
+
+module Legion
+  module Extensions
+    module HypothesisTesting
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

data/spec/legion/extensions/hypothesis_testing/helpers/constants_spec.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/hypothesis_testing/helpers/constants'
+
+RSpec.describe Legion::Extensions::HypothesisTesting::Helpers::Constants do
+  it 'defines MAX_HYPOTHESES as 300' do
+    expect(described_class::MAX_HYPOTHESES).to eq(300)
+  end
+
+  it 'defines CONFIRMATION_THRESHOLD as 0.8' do
+    expect(described_class::CONFIRMATION_THRESHOLD).to eq(0.8)
+  end
+
+  it 'defines DISCONFIRMATION_THRESHOLD as 0.2' do
+    expect(described_class::DISCONFIRMATION_THRESHOLD).to eq(0.2)
+  end
+
+  it 'defines EVIDENCE_WEIGHT as 0.1' do
+    expect(described_class::EVIDENCE_WEIGHT).to eq(0.1)
+  end
+
+  it 'defines PRIOR_DEFAULT as 0.5' do
+    expect(described_class::PRIOR_DEFAULT).to eq(0.5)
+  end
+
+  it 'defines all five STATUS_LABELS keys' do
+    expect(described_class::STATUS_LABELS.keys).to match_array(%i[proposed testing confirmed disconfirmed inconclusive])
+  end
+
+  it 'defines five CONFIDENCE_LABELS entries' do
+    expect(described_class::CONFIDENCE_LABELS.size).to eq(5)
+  end
+
+  it 'includes certain, confident, leaning, uncertain, agnostic labels' do
+    labels = described_class::CONFIDENCE_LABELS.map { |_, label| label }
+    expect(labels).to match_array(%w[certain confident leaning uncertain agnostic])
+  end
+end

data/spec/legion/extensions/hypothesis_testing/helpers/hypothesis_engine_spec.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/hypothesis_testing/helpers/constants'
+require 'legion/extensions/hypothesis_testing/helpers/hypothesis'
+require 'legion/extensions/hypothesis_testing/helpers/hypothesis_engine'
+
+RSpec.describe Legion::Extensions::HypothesisTesting::Helpers::HypothesisEngine do
+  subject(:engine) { described_class.new }
+
+  describe '#propose' do
+    it 'returns a Hypothesis object' do
+      h = engine.propose(description: 'test', domain: 'logic')
+      expect(h).to be_a(Legion::Extensions::HypothesisTesting::Helpers::Hypothesis)
+    end
+
+    it 'stores the hypothesis' do
+      h = engine.propose(description: 'stored')
+      expect(engine.hypotheses[h.id]).to eq(h)
+    end
+
+    it 'assigns the given domain' do
+      h = engine.propose(description: 'domain test', domain: 'physics')
+      expect(h.domain).to eq('physics')
+    end
+
+    it 'uses default domain general when not specified' do
+      h = engine.propose(description: 'default domain')
+      expect(h.domain).to eq('general')
+    end
+
+    it 'assigns the given prior' do
+      h = engine.propose(description: 'prior test', prior: 0.3)
+      expect(h.prior).to eq(0.3)
+    end
+
+    it 'evicts oldest when MAX_HYPOTHESES is reached' do
+      max = Legion::Extensions::HypothesisTesting::Helpers::Constants::MAX_HYPOTHESES
+      max.times { |i| engine.propose(description: "h#{i}") }
+      expect(engine.hypotheses.size).to eq(max)
+      oldest_id = engine.hypotheses.values.min_by(&:created_at).id
+      engine.propose(description: 'overflow')
+      expect(engine.hypotheses.key?(oldest_id)).to be false
+    end
+  end
+
+  describe '#test_hypothesis' do
+    it 'updates posterior when hypothesis exists' do
+      h     = engine.propose(description: 'testable', prior: 0.5)
+      prior = h.posterior
+      engine.test_hypothesis(hypothesis_id: h.id, evidence_strength: 1.0, supporting: true)
+      expect(h.posterior).to be > prior
+    end
+
+    it 'returns nil for unknown hypothesis_id' do
+      result = engine.test_hypothesis(hypothesis_id: 'nonexistent', evidence_strength: 0.5, supporting: true)
+      expect(result).to be_nil
+    end
+
+    it 'auto-confirms when posterior crosses CONFIRMATION_THRESHOLD' do
+      h = engine.propose(description: 'high prior', prior: 0.79)
+      engine.test_hypothesis(hypothesis_id: h.id, evidence_strength: 1.0, supporting: true)
+      expect(h.status).to eq(:confirmed)
+    end
+
+    it 'auto-disconfirms when posterior falls below DISCONFIRMATION_THRESHOLD' do
+      h = engine.propose(description: 'low prior', prior: 0.21)
+      engine.test_hypothesis(hypothesis_id: h.id, evidence_strength: 1.0, supporting: false)
+      expect(h.status).to eq(:disconfirmed)
+    end
+  end
+
+  describe '#evaluate' do
+    it 'returns nil for unknown hypothesis_id' do
+      expect(engine.evaluate('nonexistent')).to be_nil
+    end
+
+    it 'confirms when posterior >= CONFIRMATION_THRESHOLD' do
+      h = engine.propose(description: 'evaluate confirm', prior: 0.9)
+      engine.evaluate(h.id)
+      expect(h.status).to eq(:confirmed)
+    end
+
+    it 'disconfirms when posterior <= DISCONFIRMATION_THRESHOLD' do
+      h = engine.propose(description: 'evaluate disconfirm', prior: 0.1)
+      engine.evaluate(h.id)
+      expect(h.status).to eq(:disconfirmed)
+    end
+
+    it 'does not re-evaluate an already confirmed hypothesis' do
+      h = engine.propose(description: 'already confirmed', prior: 0.5)
+      h.confirm!
+      engine.evaluate(h.id)
+      expect(h.status).to eq(:confirmed)
+    end
+  end
+
+  describe '#competing_hypotheses' do
+    it 'returns all hypotheses in the given domain' do
+      engine.propose(description: 'h1', domain: 'physics')
+      engine.propose(description: 'h2', domain: 'physics')
+      engine.propose(description: 'h3', domain: 'chemistry')
+      result = engine.competing_hypotheses(domain: 'physics')
+      expect(result.size).to eq(2)
+    end
+
+    it 'returns an empty array when no hypotheses match the domain' do
+      engine.propose(description: 'other', domain: 'biology')
+      expect(engine.competing_hypotheses(domain: 'astronomy')).to be_empty
+    end
+  end
+
+  describe '#most_confident' do
+    it 'returns hypotheses sorted by descending posterior' do
+      h1 = engine.propose(description: 'low',  prior: 0.2)
+      h2 = engine.propose(description: 'high', prior: 0.9)
+      h3 = engine.propose(description: 'mid',  prior: 0.5)
+      result = engine.most_confident(limit: 3)
+      expect(result.map(&:id)).to eq([h2.id, h3.id, h1.id])
+    end
+
+    it 'respects the limit parameter' do
+      5.times { |i| engine.propose(description: "h#{i}", prior: i * 0.1) }
+      expect(engine.most_confident(limit: 3).size).to eq(3)
+    end
+  end
+
+  describe '#confirmation_rate' do
+    it 'returns 0.0 when no hypotheses have been resolved' do
+      engine.propose(description: 'unresolved')
+      expect(engine.confirmation_rate).to eq(0.0)
+    end
+
+    it 'computes rate correctly with mixed outcomes' do
+      h1 = engine.propose(description: 'h1', prior: 0.9)
+      h1.confirm!
+      h2 = engine.propose(description: 'h2', prior: 0.1)
+      h2.disconfirm!
+      expect(engine.confirmation_rate).to eq(0.5)
+    end
+
+    it 'returns 1.0 when all resolved hypotheses are confirmed' do
+      h = engine.propose(description: 'confirmed', prior: 0.9)
+      h.confirm!
+      expect(engine.confirmation_rate).to eq(1.0)
+    end
+  end
+
+  describe '#hypothesis_report' do
+    it 'includes total, by_status, confirmation_rate, most_confident' do
+      engine.propose(description: 'a')
+      engine.propose(description: 'b')
+      report = engine.hypothesis_report
+      expect(report.keys).to include(:total, :by_status, :confirmation_rate, :most_confident)
+    end
+
+    it 'reports correct total count' do
+      3.times { |i| engine.propose(description: "h#{i}") }
+      expect(engine.hypothesis_report[:total]).to eq(3)
+    end
+
+    it 'limits most_confident to 3 entries' do
+      5.times { |i| engine.propose(description: "h#{i}") }
+      expect(engine.hypothesis_report[:most_confident].size).to be <= 3
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes hypotheses array, confirmation_rate, and total' do
+      engine.propose(description: 'serialized')
+      result = engine.to_h
+      expect(result.keys).to include(:hypotheses, :confirmation_rate, :total)
+    end
+
+    it 'returns each hypothesis as a hash' do
+      engine.propose(description: 'one')
+      engine.to_h[:hypotheses].each do |h|
+        expect(h).to be_a(Hash)
+        expect(h.keys).to include(:id, :description, :status)
+      end
+    end
+  end
+end

data/spec/legion/extensions/hypothesis_testing/helpers/hypothesis_spec.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/hypothesis_testing/helpers/constants'
+require 'legion/extensions/hypothesis_testing/helpers/hypothesis'
+
+RSpec.describe Legion::Extensions::HypothesisTesting::Helpers::Hypothesis do
+  subject(:hypothesis) { described_class.new(description: 'test hypothesis', domain: 'logic') }
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(hypothesis.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets description' do
+      expect(hypothesis.description).to eq('test hypothesis')
+    end
+
+    it 'sets domain' do
+      expect(hypothesis.domain).to eq('logic')
+    end
+
+    it 'defaults prior to PRIOR_DEFAULT' do
+      h = described_class.new(description: 'default prior')
+      expect(h.prior).to eq(Legion::Extensions::HypothesisTesting::Helpers::Constants::PRIOR_DEFAULT)
+    end
+
+    it 'sets posterior to prior at creation' do
+      h = described_class.new(description: 'check posterior', prior: 0.3)
+      expect(h.posterior).to eq(0.3)
+    end
+
+    it 'starts with evidence_count of 0' do
+      expect(hypothesis.evidence_count).to eq(0)
+    end
+
+    it 'starts with status :proposed' do
+      expect(hypothesis.status).to eq(:proposed)
+    end
+
+    it 'clamps prior above 1.0 to 1.0' do
+      h = described_class.new(description: 'high', prior: 1.5)
+      expect(h.prior).to eq(1.0)
+    end
+
+    it 'clamps prior below 0.0 to 0.0' do
+      h = described_class.new(description: 'low', prior: -0.1)
+      expect(h.prior).to eq(0.0)
+    end
+  end
+
+  describe '#update_posterior!' do
+    it 'increases posterior with supporting evidence' do
+      before = hypothesis.posterior
+      hypothesis.update_posterior!(evidence_strength: 1.0, supporting: true)
+      expect(hypothesis.posterior).to be > before
+    end
+
+    it 'decreases posterior with contradicting evidence' do
+      h = described_class.new(description: 'contra', prior: 0.8)
+      h.update_posterior!(evidence_strength: 1.0, supporting: false)
+      expect(h.posterior).to be < 0.8
+    end
+
+    it 'transitions status to :testing' do
+      hypothesis.update_posterior!(evidence_strength: 0.5, supporting: true)
+      expect(hypothesis.status).to eq(:testing)
+    end
+
+    it 'increments evidence_count' do
+      hypothesis.update_posterior!(evidence_strength: 0.5, supporting: true)
+      expect(hypothesis.evidence_count).to eq(1)
+    end
+
+    it 'keeps posterior within [0.0, 1.0]' do
+      10.times { hypothesis.update_posterior!(evidence_strength: 1.0, supporting: true) }
+      expect(hypothesis.posterior).to be <= 1.0
+    end
+
+    it 'does not update a confirmed hypothesis' do
+      hypothesis.confirm!
+      prior_posterior = hypothesis.posterior
+      hypothesis.update_posterior!(evidence_strength: 1.0, supporting: false)
+      expect(hypothesis.posterior).to eq(prior_posterior)
+    end
+
+    it 'does not update a disconfirmed hypothesis' do
+      hypothesis.disconfirm!
+      prior_posterior = hypothesis.posterior
+      hypothesis.update_posterior!(evidence_strength: 1.0, supporting: true)
+      expect(hypothesis.posterior).to eq(prior_posterior)
+    end
+
+    it 'clamps evidence_strength above 1.0' do
+      hypothesis.update_posterior!(evidence_strength: 5.0, supporting: true)
+      expect(hypothesis.posterior).to be <= 1.0
+    end
+
+    it 'rounds posterior to 10 decimal places' do
+      hypothesis.update_posterior!(evidence_strength: 0.7, supporting: true)
+      expect(hypothesis.posterior.to_s.split('.').last.length).to be <= 10
+    end
+  end
+
+  describe '#confirm!' do
+    it 'sets status to :confirmed' do
+      hypothesis.confirm!
+      expect(hypothesis.status).to eq(:confirmed)
+    end
+
+    it 'raises posterior to at least CONFIRMATION_THRESHOLD' do
+      h = described_class.new(description: 'near confirm', prior: 0.75)
+      h.confirm!
+      expect(h.posterior).to be >= Legion::Extensions::HypothesisTesting::Helpers::Constants::CONFIRMATION_THRESHOLD
+    end
+  end
+
+  describe '#disconfirm!' do
+    it 'sets status to :disconfirmed' do
+      hypothesis.disconfirm!
+      expect(hypothesis.status).to eq(:disconfirmed)
+    end
+
+    it 'lowers posterior to at most DISCONFIRMATION_THRESHOLD' do
+      h = described_class.new(description: 'near disconfirm', prior: 0.25)
+      h.disconfirm!
+      expect(h.posterior).to be <= Legion::Extensions::HypothesisTesting::Helpers::Constants::DISCONFIRMATION_THRESHOLD
+    end
+  end
+
+  describe '#confidence_label' do
+    it 'returns certain for posterior >= 0.9' do
+      h = described_class.new(description: 'certain', prior: 0.95)
+      expect(h.confidence_label).to eq('certain')
+    end
+
+    it 'returns confident for posterior in [0.7, 0.9)' do
+      h = described_class.new(description: 'confident', prior: 0.8)
+      expect(h.confidence_label).to eq('confident')
+    end
+
+    it 'returns leaning for posterior in [0.5, 0.7)' do
+      h = described_class.new(description: 'leaning', prior: 0.6)
+      expect(h.confidence_label).to eq('leaning')
+    end
+
+    it 'returns uncertain for posterior in [0.3, 0.5)' do
+      h = described_class.new(description: 'uncertain', prior: 0.4)
+      expect(h.confidence_label).to eq('uncertain')
+    end
+
+    it 'returns agnostic for posterior in [0.0, 0.3)' do
+      h = described_class.new(description: 'agnostic', prior: 0.1)
+      expect(h.confidence_label).to eq('agnostic')
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with all required keys' do
+      result = hypothesis.to_h
+      expect(result.keys).to include(:id, :description, :domain, :prior, :posterior,
+                                     :evidence_count, :status, :confidence_label, :created_at)
+    end
+
+    it 'returns correct id' do
+      expect(hypothesis.to_h[:id]).to eq(hypothesis.id)
+    end
+
+    it 'returns correct status' do
+      expect(hypothesis.to_h[:status]).to eq(:proposed)
+    end
+  end
+end

data/spec/legion/extensions/hypothesis_testing/runners/hypothesis_testing_spec.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/hypothesis_testing/client'
+
+RSpec.describe Legion::Extensions::HypothesisTesting::Runners::HypothesisTesting do
+  let(:client) { Legion::Extensions::HypothesisTesting::Client.new }
+
+  describe '#propose_hypothesis' do
+    it 'returns a hypothesis_id uuid' do
+      result = client.propose_hypothesis(description: 'water boils at 100C')
+      expect(result[:hypothesis_id]).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'returns the description' do
+      result = client.propose_hypothesis(description: 'gravity exists')
+      expect(result[:description]).to eq('gravity exists')
+    end
+
+    it 'returns the domain' do
+      result = client.propose_hypothesis(description: 'test', domain: 'physics')
+      expect(result[:domain]).to eq('physics')
+    end
+
+    it 'defaults domain to general' do
+      result = client.propose_hypothesis(description: 'test')
+      expect(result[:domain]).to eq('general')
+    end
+
+    it 'returns status :proposed' do
+      result = client.propose_hypothesis(description: 'test')
+      expect(result[:status]).to eq(:proposed)
+    end
+
+    it 'returns a confidence_label' do
+      result = client.propose_hypothesis(description: 'test', prior: 0.9)
+      expect(result[:confidence_label]).to eq('certain')
+    end
+
+    it 'sets prior and posterior to the given prior' do
+      result = client.propose_hypothesis(description: 'test', prior: 0.7)
+      expect(result[:prior]).to eq(0.7)
+      expect(result[:posterior]).to eq(0.7)
+    end
+  end
+
+  describe '#test_hypothesis' do
+    let(:proposed) { client.propose_hypothesis(description: 'testable') }
+
+    it 'returns tested: true for a known hypothesis' do
+      result = client.test_hypothesis(hypothesis_id: proposed[:hypothesis_id], evidence_strength: 0.5, supporting: true)
+      expect(result[:tested]).to be true
+    end
+
+    it 'returns tested: false for an unknown id' do
+      result = client.test_hypothesis(hypothesis_id: 'missing', evidence_strength: 0.5, supporting: true)
+      expect(result[:tested]).to be false
+      expect(result[:reason]).to eq(:not_found)
+    end
+
+    it 'includes updated posterior' do
+      result = client.test_hypothesis(hypothesis_id: proposed[:hypothesis_id], evidence_strength: 1.0, supporting: true)
+      expect(result[:posterior]).to be > proposed[:posterior]
+    end
+
+    it 'includes updated evidence_count' do
+      result = client.test_hypothesis(hypothesis_id: proposed[:hypothesis_id], evidence_strength: 0.5, supporting: true)
+      expect(result[:evidence_count]).to eq(1)
+    end
+
+    it 'includes status' do
+      result = client.test_hypothesis(hypothesis_id: proposed[:hypothesis_id], evidence_strength: 0.5, supporting: true)
+      expect(result.key?(:status)).to be true
+    end
+
+    it 'returns :confirmed status when posterior crosses threshold' do
+      h = client.propose_hypothesis(description: 'high prior', prior: 0.79)
+      result = client.test_hypothesis(hypothesis_id: h[:hypothesis_id], evidence_strength: 1.0, supporting: true)
+      expect(result[:status]).to eq(:confirmed)
+    end
+  end
+
+  describe '#evaluate_hypothesis' do
+    it 'returns found: false for unknown id' do
+      result = client.evaluate_hypothesis(hypothesis_id: 'ghost')
+      expect(result[:found]).to be false
+    end
+
+    it 'returns found: true for known hypothesis' do
+      h      = client.propose_hypothesis(description: 'evaluatable')
+      result = client.evaluate_hypothesis(hypothesis_id: h[:hypothesis_id])
+      expect(result[:found]).to be true
+    end
+
+    it 'confirms hypothesis when posterior is above threshold' do
+      h = client.propose_hypothesis(description: 'high', prior: 0.9)
+      result = client.evaluate_hypothesis(hypothesis_id: h[:hypothesis_id])
+      expect(result[:status]).to eq(:confirmed)
+    end
+  end
+
+  describe '#competing_hypotheses' do
+    it 'returns hypotheses in the given domain' do
+      client.propose_hypothesis(description: 'h1', domain: 'biology')
+      client.propose_hypothesis(description: 'h2', domain: 'biology')
+      client.propose_hypothesis(description: 'h3', domain: 'chemistry')
+      result = client.competing_hypotheses(domain: 'biology')
+      expect(result[:count]).to eq(2)
+      expect(result[:domain]).to eq('biology')
+    end
+
+    it 'returns empty list for unrepresented domain' do
+      result = client.competing_hypotheses(domain: 'astrology')
+      expect(result[:count]).to eq(0)
+      expect(result[:hypotheses]).to be_empty
+    end
+  end
+
+  describe '#most_confident_hypotheses' do
+    it 'returns hypotheses sorted by descending posterior' do
+      client.propose_hypothesis(description: 'low',  prior: 0.2)
+      client.propose_hypothesis(description: 'high', prior: 0.9)
+      result = client.most_confident_hypotheses(limit: 2)
+      expect(result[:hypotheses].first[:posterior]).to be >= result[:hypotheses].last[:posterior]
+    end
+
+    it 'respects the limit' do
+      5.times { |i| client.propose_hypothesis(description: "h#{i}") }
+      result = client.most_confident_hypotheses(limit: 3)
+      expect(result[:count]).to be <= 3
+    end
+  end
+
+  describe '#hypothesis_report' do
+    it 'includes total, by_status, confirmation_rate, most_confident' do
+      client.propose_hypothesis(description: 'reported')
+      result = client.hypothesis_report
+      expect(result.keys).to include(:total, :by_status, :confirmation_rate, :most_confident)
+    end
+
+    it 'counts total correctly' do
+      3.times { |i| client.propose_hypothesis(description: "h#{i}") }
+      expect(client.hypothesis_report[:total]).to eq(3)
+    end
+  end
+
+  describe '#get_hypothesis' do
+    it 'returns found: false for unknown id' do
+      result = client.get_hypothesis(hypothesis_id: 'nope')
+      expect(result[:found]).to be false
+    end
+
+    it 'returns found: true and hypothesis hash for known id' do
+      h      = client.propose_hypothesis(description: 'gettable')
+      result = client.get_hypothesis(hypothesis_id: h[:hypothesis_id])
+      expect(result[:found]).to be true
+      expect(result[:hypothesis][:id]).to eq(h[:hypothesis_id])
+    end
+  end
+end

data/spec/legion/extensions/hypothesis_testing_spec.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/hypothesis_testing/client'
+
+RSpec.describe Legion::Extensions::HypothesisTesting::Client do
+  it 'responds to all runner methods' do
+    client = described_class.new
+    expect(client).to respond_to(:propose_hypothesis)
+    expect(client).to respond_to(:test_hypothesis)
+    expect(client).to respond_to(:evaluate_hypothesis)
+    expect(client).to respond_to(:competing_hypotheses)
+    expect(client).to respond_to(:most_confident_hypotheses)
+    expect(client).to respond_to(:hypothesis_report)
+    expect(client).to respond_to(:get_hypothesis)
+  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/hypothesis_testing'
+
+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,76 @@
+--- !ruby/object:Gem::Specification
+name: lex-hypothesis-testing
+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: Scientific hypothesis testing cycle for brain-modeled agentic AI — Bayesian
+  evidence accumulation, lifecycle management, competing hypotheses
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-hypothesis-testing.gemspec
+- lib/legion/extensions/hypothesis_testing.rb
+- lib/legion/extensions/hypothesis_testing/client.rb
+- lib/legion/extensions/hypothesis_testing/helpers/constants.rb
+- lib/legion/extensions/hypothesis_testing/helpers/hypothesis.rb
+- lib/legion/extensions/hypothesis_testing/helpers/hypothesis_engine.rb
+- lib/legion/extensions/hypothesis_testing/runners/hypothesis_testing.rb
+- lib/legion/extensions/hypothesis_testing/version.rb
+- spec/legion/extensions/hypothesis_testing/helpers/constants_spec.rb
+- spec/legion/extensions/hypothesis_testing/helpers/hypothesis_engine_spec.rb
+- spec/legion/extensions/hypothesis_testing/helpers/hypothesis_spec.rb
+- spec/legion/extensions/hypothesis_testing/runners/hypothesis_testing_spec.rb
+- spec/legion/extensions/hypothesis_testing_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-hypothesis-testing
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-hypothesis-testing
+  source_code_uri: https://github.com/LegionIO/lex-hypothesis-testing
+  documentation_uri: https://github.com/LegionIO/lex-hypothesis-testing
+  changelog_uri: https://github.com/LegionIO/lex-hypothesis-testing
+  bug_tracker_uri: https://github.com/LegionIO/lex-hypothesis-testing/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 Hypothesis Testing
+test_files: []