lex-abductive-reasoning 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 81b8af5d21f6a677bd9d1a625f01a62f27b6371653f48ead364306a9c783868a
+  data.tar.gz: ee959cfaec090545d8c412609c44fda9d38ae7f8e6c87a290973bfc421e41442
+SHA512:
+  metadata.gz: 6e4f124201ff7740d8e4ec8d264447cf95236df6ffbbca2e66cb91e31d6654e05395eb07ecf8cf48a5cd75c74254fabc405d5e0d675b169b7b88fd5c81e18f2d
+  data.tar.gz: d91e013c47d85b926c4e2585975ab8671e7c5f9a041ec1c26e39c116965288972a0422790eed6b034ca1ce0ecdfcf79d0a3d4dd93102a3a815f06da5c399e846

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-abductive-reasoning.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/abductive_reasoning/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-abductive-reasoning'
+  spec.version       = Legion::Extensions::AbductiveReasoning::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Abductive Reasoning'
+  spec.description   = 'Peirce abductive reasoning engine — inference to the best explanation for brain-modeled agentic AI'
+  spec.homepage      = 'https://github.com/LegionIO/lex-abductive-reasoning'
+  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-abductive-reasoning'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-abductive-reasoning'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-abductive-reasoning'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-abductive-reasoning/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-abductive-reasoning.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/abductive_reasoning/helpers/constants'
+require 'legion/extensions/abductive_reasoning/helpers/observation'
+require 'legion/extensions/abductive_reasoning/helpers/hypothesis'
+require 'legion/extensions/abductive_reasoning/helpers/abduction_engine'
+require 'legion/extensions/abductive_reasoning/runners/abductive_reasoning'
+
+module Legion
+  module Extensions
+    module AbductiveReasoning
+      class Client
+        include Runners::AbductiveReasoning
+
+        def initialize(engine: nil)
+          @engine = engine || Helpers::AbductionEngine.new
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/abductive_reasoning/helpers/abduction_engine.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module AbductiveReasoning
+      module Helpers
+        class AbductionEngine
+          include Constants
+
+          def initialize
+            @observations = {}
+            @hypotheses   = {}
+          end
+
+          def record_observation(content:, domain:, surprise_level: :notable, context: {})
+            obs = Observation.new(
+              content:        content,
+              domain:         domain,
+              surprise_level: surprise_level,
+              context:        context
+            )
+            prune_observations if @observations.size >= Constants::MAX_OBSERVATIONS
+            @observations[obs.id] = obs
+            obs
+          end
+
+          def generate_hypothesis(content:, observation_ids:, domain:, simplicity:,
+                                  explanatory_power:, prior_probability: Constants::DEFAULT_PLAUSIBILITY)
+            hyp = Hypothesis.new(
+              content:           content,
+              observation_ids:   observation_ids,
+              domain:            domain,
+              simplicity:        simplicity,
+              explanatory_power: explanatory_power,
+              prior_probability: prior_probability
+            )
+            prune_hypotheses if @hypotheses.size >= Constants::MAX_HYPOTHESES
+            @hypotheses[hyp.id] = hyp
+            hyp
+          end
+
+          def evaluate_hypothesis(hypothesis_id:)
+            hyp = @hypotheses[hypothesis_id]
+            return { found: false } unless hyp
+
+            hyp.instance_variable_set(:@last_evaluated_at, Time.now.utc)
+            ranked = ranked_hypotheses_for_observations(hyp.observation_ids)
+            rank = ranked.index { |h| h.id == hypothesis_id }.to_i + 1
+
+            {
+              score:         hyp.overall_score,
+              rank:          rank,
+              quality_label: hyp.quality_label
+            }
+          end
+
+          def add_evidence(hypothesis_id:, supporting:)
+            hyp = @hypotheses[hypothesis_id]
+            return { found: false } unless hyp
+
+            hyp.add_evidence(supporting: supporting)
+            { found: true, hypothesis_id: hypothesis_id, state: hyp.state, plausibility: hyp.plausibility }
+          end
+
+          def best_explanation(observation_id:)
+            candidates = active_hypotheses_for(observation_id)
+            return nil if candidates.empty?
+
+            candidates.max_by(&:overall_score)
+          end
+
+          def competing_hypotheses(observation_id:)
+            active_hypotheses_for(observation_id).sort_by { |h| -h.overall_score }
+          end
+
+          def refute_hypothesis(hypothesis_id:)
+            hyp = @hypotheses[hypothesis_id]
+            return { found: false } unless hyp
+
+            hyp.refute!
+            { found: true, hypothesis_id: hypothesis_id, state: hyp.state }
+          end
+
+          def find_by_domain(domain:)
+            @hypotheses.values.select { |h| h.domain == domain && h.state != :refuted }
+          end
+
+          def unexplained_observations
+            @observations.values.reject do |obs|
+              @hypotheses.values.any? do |h|
+                h.state == :supported && h.observation_ids.include?(obs.id)
+              end
+            end
+          end
+
+          def decay_stale
+            cutoff = Time.now.utc - Constants::STALE_THRESHOLD
+            decayed = 0
+            @hypotheses.each_value do |hyp|
+              next if hyp.state == :refuted
+              next if hyp.last_evaluated_at >= cutoff
+
+              hyp.plausibility = (hyp.plausibility - Constants::DECAY_RATE).clamp(
+                Constants::PLAUSIBILITY_FLOOR,
+                Constants::PLAUSIBILITY_CEILING
+              )
+              decayed += 1
+            end
+            decayed
+          end
+
+          def prune_refuted
+            before = @hypotheses.size
+            @hypotheses.delete_if { |_, h| h.state == :refuted }
+            before - @hypotheses.size
+          end
+
+          def to_h
+            {
+              observation_count: @observations.size,
+              hypothesis_count:  @hypotheses.size,
+              supported_count:   @hypotheses.values.count { |h| h.state == :supported },
+              refuted_count:     @hypotheses.values.count { |h| h.state == :refuted },
+              candidate_count:   @hypotheses.values.count { |h| h.state == :candidate },
+              unexplained_count: unexplained_observations.size
+            }
+          end
+
+          private
+
+          def active_hypotheses_for(observation_id)
+            @hypotheses.values.select do |h|
+              h.state != :refuted && h.observation_ids.include?(observation_id)
+            end
+          end
+
+          def ranked_hypotheses_for_observations(observation_ids)
+            obs_set = Array(observation_ids)
+            @hypotheses.values
+                       .select { |h| h.state != :refuted && h.observation_ids.intersect?(obs_set) }
+                       .sort_by { |h| -h.overall_score }
+          end
+
+          def prune_observations
+            sorted = @observations.values.sort_by(&:created_at)
+            excess = @observations.size - Constants::MAX_OBSERVATIONS + 1
+            sorted.first(excess).each { |obs| @observations.delete(obs.id) }
+          end
+
+          def prune_hypotheses
+            candidates = @hypotheses.values.select { |h| h.state == :candidate }
+            sorted = candidates.sort_by(&:created_at)
+            excess = @hypotheses.size - Constants::MAX_HYPOTHESES + 1
+            sorted.first(excess).each { |h| @hypotheses.delete(h.id) }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module AbductiveReasoning
+      module Helpers
+        module Constants
+          MAX_OBSERVATIONS     = 200
+          MAX_HYPOTHESES       = 100
+          MAX_EXPLANATIONS     = 500
+          MAX_HISTORY          = 300
+          DEFAULT_PLAUSIBILITY = 0.5
+          PLAUSIBILITY_FLOOR   = 0.0
+          PLAUSIBILITY_CEILING = 1.0
+          SIMPLICITY_WEIGHT    = 0.3
+          EXPLANATORY_POWER_WEIGHT = 0.4
+          PRIOR_WEIGHT         = 0.3
+          EVIDENCE_BOOST       = 0.1
+          CONTRADICTION_PENALTY = 0.2
+          DECAY_RATE           = 0.02
+          STALE_THRESHOLD      = 120
+          SURPRISE_LEVELS      = %i[trivial expected notable surprising shocking].freeze
+          HYPOTHESIS_STATES    = %i[candidate supported refuted].freeze
+          QUALITY_LABELS       = {
+            (0.8..)     => :compelling,
+            (0.6...0.8) => :plausible,
+            (0.4...0.6) => :possible,
+            (0.2...0.4) => :weak,
+            (..0.2)     => :implausible
+          }.freeze
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module AbductiveReasoning
+      module Helpers
+        class Hypothesis
+          include Constants
+
+          attr_reader :id, :content, :observation_ids, :domain,
+                      :simplicity, :explanatory_power, :prior_probability,
+                      :evidence_for, :evidence_against, :state,
+                      :created_at, :last_evaluated_at
+          attr_accessor :plausibility
+
+          SUPPORT_EVIDENCE_THRESHOLD = 3
+
+          def initialize(content:, observation_ids:, domain:, simplicity:, explanatory_power:,
+                         prior_probability: Constants::DEFAULT_PLAUSIBILITY)
+            @id                 = SecureRandom.uuid
+            @content            = content
+            @observation_ids    = Array(observation_ids)
+            @domain             = domain
+            @plausibility       = prior_probability
+            @simplicity         = simplicity
+            @explanatory_power  = explanatory_power
+            @prior_probability  = prior_probability
+            @evidence_for       = 0
+            @evidence_against   = 0
+            @state              = :candidate
+            @created_at         = Time.now.utc
+            @last_evaluated_at  = Time.now.utc
+          end
+
+          def overall_score
+            (Constants::SIMPLICITY_WEIGHT * @simplicity) +
+              (Constants::EXPLANATORY_POWER_WEIGHT * @explanatory_power) +
+              (Constants::PRIOR_WEIGHT * @prior_probability)
+          end
+
+          def add_evidence(supporting:)
+            @last_evaluated_at = Time.now.utc
+            if supporting
+              @evidence_for += 1
+              @plausibility = (@plausibility + Constants::EVIDENCE_BOOST).clamp(
+                Constants::PLAUSIBILITY_FLOOR,
+                Constants::PLAUSIBILITY_CEILING
+              )
+            else
+              @evidence_against += 1
+              @plausibility = (@plausibility - Constants::CONTRADICTION_PENALTY).clamp(
+                Constants::PLAUSIBILITY_FLOOR,
+                Constants::PLAUSIBILITY_CEILING
+              )
+            end
+            support! if @evidence_for >= SUPPORT_EVIDENCE_THRESHOLD && @state == :candidate
+          end
+
+          def refute!
+            @state = :refuted
+            @last_evaluated_at = Time.now.utc
+          end
+
+          def support!
+            @state = :supported
+            @last_evaluated_at = Time.now.utc
+          end
+
+          def quality_label
+            score = overall_score
+            Constants::QUALITY_LABELS.each do |range, label|
+              return label if range.include?(score)
+            end
+            :implausible
+          end
+
+          def to_h
+            {
+              id:                @id,
+              content:           @content,
+              observation_ids:   @observation_ids,
+              domain:            @domain,
+              plausibility:      @plausibility,
+              simplicity:        @simplicity,
+              explanatory_power: @explanatory_power,
+              prior_probability: @prior_probability,
+              evidence_for:      @evidence_for,
+              evidence_against:  @evidence_against,
+              state:             @state,
+              overall_score:     overall_score,
+              quality_label:     quality_label,
+              created_at:        @created_at,
+              last_evaluated_at: @last_evaluated_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/abductive_reasoning/helpers/observation.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module AbductiveReasoning
+      module Helpers
+        class Observation
+          attr_reader :id, :content, :domain, :surprise_level, :context, :created_at
+
+          def initialize(content:, domain:, surprise_level: :notable, context: {})
+            @id             = SecureRandom.uuid
+            @content        = content
+            @domain         = domain
+            @surprise_level = surprise_level
+            @context        = context
+            @created_at     = Time.now.utc
+          end
+
+          def to_h
+            {
+              id:             @id,
+              content:        @content,
+              domain:         @domain,
+              surprise_level: @surprise_level,
+              context:        @context,
+              created_at:     @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module AbductiveReasoning
+      module Runners
+        module AbductiveReasoning
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def record_observation(content:, domain:, surprise_level: :notable, context: {}, **)
+            unless Helpers::Constants::SURPRISE_LEVELS.include?(surprise_level)
+              return { success: false, error: :invalid_surprise_level,
+                       valid_levels: Helpers::Constants::SURPRISE_LEVELS }
+            end
+
+            obs = engine.record_observation(
+              content:        content,
+              domain:         domain,
+              surprise_level: surprise_level,
+              context:        context
+            )
+            Legion::Logging.debug "[abductive_reasoning] observation recorded: id=#{obs.id[0..7]} " \
+                                  "domain=#{domain} surprise=#{surprise_level}"
+            { success: true, observation: obs.to_h }
+          end
+
+          def generate_hypothesis(content:, observation_ids:, domain:, simplicity:,
+                                  explanatory_power:, prior_probability: nil, **)
+            prior = prior_probability || Helpers::Constants::DEFAULT_PLAUSIBILITY
+            hyp = engine.generate_hypothesis(
+              content:           content,
+              observation_ids:   observation_ids,
+              domain:            domain,
+              simplicity:        simplicity,
+              explanatory_power: explanatory_power,
+              prior_probability: prior
+            )
+            Legion::Logging.debug "[abductive_reasoning] hypothesis generated: id=#{hyp.id[0..7]} " \
+                                  "domain=#{domain} score=#{hyp.overall_score.round(3)}"
+            { success: true, hypothesis: hyp.to_h }
+          end
+
+          def evaluate_hypothesis(hypothesis_id:, **)
+            result = engine.evaluate_hypothesis(hypothesis_id: hypothesis_id)
+            if result[:found] == false
+              Legion::Logging.debug "[abductive_reasoning] evaluate: not found id=#{hypothesis_id[0..7]}"
+              return { success: false, error: :not_found }
+            end
+
+            Legion::Logging.debug "[abductive_reasoning] evaluate: id=#{hypothesis_id[0..7]} " \
+                                  "score=#{result[:score].round(3)} rank=#{result[:rank]} label=#{result[:quality_label]}"
+            { success: true }.merge(result)
+          end
+
+          def add_hypothesis_evidence(hypothesis_id:, supporting:, **)
+            result = engine.add_evidence(hypothesis_id: hypothesis_id, supporting: supporting)
+            if result[:found] == false
+              Legion::Logging.debug "[abductive_reasoning] add_evidence: not found id=#{hypothesis_id[0..7]}"
+              return { success: false, error: :not_found }
+            end
+
+            Legion::Logging.debug "[abductive_reasoning] evidence added: id=#{hypothesis_id[0..7]} " \
+                                  "supporting=#{supporting} state=#{result[:state]}"
+            { success: true }.merge(result)
+          end
+
+          def best_explanation(observation_id:, **)
+            hyp = engine.best_explanation(observation_id: observation_id)
+            if hyp
+              Legion::Logging.debug "[abductive_reasoning] best_explanation: obs=#{observation_id[0..7]} " \
+                                    "hyp=#{hyp.id[0..7]} score=#{hyp.overall_score.round(3)}"
+              { success: true, found: true, hypothesis: hyp.to_h }
+            else
+              Legion::Logging.debug "[abductive_reasoning] best_explanation: obs=#{observation_id[0..7]} none found"
+              { success: true, found: false }
+            end
+          end
+
+          def competing_hypotheses(observation_id:, **)
+            ranked = engine.competing_hypotheses(observation_id: observation_id)
+            Legion::Logging.debug "[abductive_reasoning] competing_hypotheses: obs=#{observation_id[0..7]} count=#{ranked.size}"
+            { success: true, hypotheses: ranked.map(&:to_h), count: ranked.size }
+          end
+
+          def refute_hypothesis(hypothesis_id:, **)
+            result = engine.refute_hypothesis(hypothesis_id: hypothesis_id)
+            if result[:found] == false
+              Legion::Logging.debug "[abductive_reasoning] refute: not found id=#{hypothesis_id[0..7]}"
+              return { success: false, error: :not_found }
+            end
+
+            Legion::Logging.debug "[abductive_reasoning] hypothesis refuted: id=#{hypothesis_id[0..7]}"
+            { success: true }.merge(result)
+          end
+
+          def unexplained_observations(**)
+            observations = engine.unexplained_observations
+            Legion::Logging.debug "[abductive_reasoning] unexplained_observations: count=#{observations.size}"
+            { success: true, observations: observations.map(&:to_h), count: observations.size }
+          end
+
+          def update_abductive_reasoning(**)
+            decayed = engine.decay_stale
+            pruned  = engine.prune_refuted
+            Legion::Logging.debug "[abductive_reasoning] update cycle: decayed=#{decayed} pruned=#{pruned}"
+            { success: true, decayed: decayed, pruned: pruned }
+          end
+
+          def abductive_reasoning_stats(**)
+            stats = engine.to_h
+            Legion::Logging.debug "[abductive_reasoning] stats: #{stats.inspect}"
+            { success: true }.merge(stats)
+          end
+
+          private
+
+          def engine
+            @engine ||= Helpers::AbductionEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/abductive_reasoning.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/abductive_reasoning/version'
+require 'legion/extensions/abductive_reasoning/helpers/constants'
+require 'legion/extensions/abductive_reasoning/helpers/observation'
+require 'legion/extensions/abductive_reasoning/helpers/hypothesis'
+require 'legion/extensions/abductive_reasoning/helpers/abduction_engine'
+require 'legion/extensions/abductive_reasoning/runners/abductive_reasoning'
+
+module Legion
+  module Extensions
+    module AbductiveReasoning
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/abductive_reasoning/client'
+
+RSpec.describe Legion::Extensions::AbductiveReasoning::Client do
+  it 'responds to all runner methods' do
+    client = described_class.new
+    expect(client).to respond_to(:record_observation)
+    expect(client).to respond_to(:generate_hypothesis)
+    expect(client).to respond_to(:evaluate_hypothesis)
+    expect(client).to respond_to(:add_hypothesis_evidence)
+    expect(client).to respond_to(:best_explanation)
+    expect(client).to respond_to(:competing_hypotheses)
+    expect(client).to respond_to(:refute_hypothesis)
+    expect(client).to respond_to(:unexplained_observations)
+    expect(client).to respond_to(:update_abductive_reasoning)
+    expect(client).to respond_to(:abductive_reasoning_stats)
+  end
+
+  it 'accepts a custom engine' do
+    custom_engine = Legion::Extensions::AbductiveReasoning::Helpers::AbductionEngine.new
+    client = described_class.new(engine: custom_engine)
+    expect(client).to be_a(described_class)
+  end
+end

data/spec/legion/extensions/abductive_reasoning/runners/abductive_reasoning_spec.rb

@@ -0,0 +1,349 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/abductive_reasoning/client'
+
+RSpec.describe Legion::Extensions::AbductiveReasoning::Runners::AbductiveReasoning do
+  let(:client) { Legion::Extensions::AbductiveReasoning::Client.new }
+
+  describe '#record_observation' do
+    it 'records an observation and returns success' do
+      result = client.record_observation(
+        content:        'CPU usage spiked to 100% unexpectedly',
+        domain:         :system_health,
+        surprise_level: :surprising
+      )
+      expect(result[:success]).to be true
+      expect(result[:observation][:id]).to match(/\A[0-9a-f-]{36}\z/)
+      expect(result[:observation][:domain]).to eq(:system_health)
+      expect(result[:observation][:surprise_level]).to eq(:surprising)
+    end
+
+    it 'rejects invalid surprise level' do
+      result = client.record_observation(
+        content:        'some fact',
+        domain:         :test,
+        surprise_level: :unknown_level
+      )
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq(:invalid_surprise_level)
+      expect(result[:valid_levels]).to eq(Legion::Extensions::AbductiveReasoning::Helpers::Constants::SURPRISE_LEVELS)
+    end
+
+    it 'uses notable as default surprise level' do
+      result = client.record_observation(content: 'a fact', domain: :test)
+      expect(result[:observation][:surprise_level]).to eq(:notable)
+    end
+
+    it 'stores context hash' do
+      result = client.record_observation(
+        content: 'memory leak detected',
+        domain:  :system,
+        context: { pid: 1234, rss_mb: 4096 }
+      )
+      expect(result[:observation][:context]).to eq({ pid: 1234, rss_mb: 4096 })
+    end
+  end
+
+  describe '#generate_hypothesis' do
+    let(:obs_result) { client.record_observation(content: 'service crashed', domain: :ops) }
+    let(:obs_id)     { obs_result[:observation][:id] }
+
+    it 'generates a hypothesis and returns success' do
+      result = client.generate_hypothesis(
+        content:           'Memory leak caused service crash',
+        observation_ids:   [obs_id],
+        domain:            :ops,
+        simplicity:        0.7,
+        explanatory_power: 0.8
+      )
+      expect(result[:success]).to be true
+      expect(result[:hypothesis][:id]).to match(/\A[0-9a-f-]{36}\z/)
+      expect(result[:hypothesis][:state]).to eq(:candidate)
+      expect(result[:hypothesis][:overall_score]).to be > 0
+    end
+
+    it 'uses default prior probability when not given' do
+      result = client.generate_hypothesis(
+        content:           'Network partition caused crash',
+        observation_ids:   [obs_id],
+        domain:            :ops,
+        simplicity:        0.5,
+        explanatory_power: 0.6
+      )
+      expect(result[:hypothesis][:prior_probability]).to eq(
+        Legion::Extensions::AbductiveReasoning::Helpers::Constants::DEFAULT_PLAUSIBILITY
+      )
+    end
+
+    it 'uses provided prior probability' do
+      result = client.generate_hypothesis(
+        content:           'Config error',
+        observation_ids:   [obs_id],
+        domain:            :ops,
+        simplicity:        0.9,
+        explanatory_power: 0.7,
+        prior_probability: 0.8
+      )
+      expect(result[:hypothesis][:prior_probability]).to eq(0.8)
+    end
+  end
+
+  describe '#evaluate_hypothesis' do
+    let(:obs_id) { client.record_observation(content: 'anomaly', domain: :test)[:observation][:id] }
+    let(:hyp_id) do
+      client.generate_hypothesis(
+        content:           'hypothesis A',
+        observation_ids:   [obs_id],
+        domain:            :test,
+        simplicity:        0.8,
+        explanatory_power: 0.9
+      )[:hypothesis][:id]
+    end
+
+    it 'evaluates a known hypothesis' do
+      result = client.evaluate_hypothesis(hypothesis_id: hyp_id)
+      expect(result[:success]).to be true
+      expect(result[:score]).to be_a(Float)
+      expect(result[:rank]).to be >= 1
+      expect(result[:quality_label]).to be_a(Symbol)
+    end
+
+    it 'returns not_found for unknown hypothesis' do
+      result = client.evaluate_hypothesis(hypothesis_id: 'nonexistent-id')
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq(:not_found)
+    end
+  end
+
+  describe '#add_hypothesis_evidence' do
+    let(:obs_id) { client.record_observation(content: 'strange output', domain: :test)[:observation][:id] }
+    let(:hyp_id) do
+      client.generate_hypothesis(
+        content:           'bad config',
+        observation_ids:   [obs_id],
+        domain:            :test,
+        simplicity:        0.6,
+        explanatory_power: 0.7
+      )[:hypothesis][:id]
+    end
+
+    it 'adds supporting evidence and boosts plausibility' do
+      before_plausibility = client.evaluate_hypothesis(hypothesis_id: hyp_id)[:score]
+      client.add_hypothesis_evidence(hypothesis_id: hyp_id, supporting: true)
+      hyp_after = client.evaluate_hypothesis(hypothesis_id: hyp_id)
+      expect(hyp_after[:success]).to be true
+      expect(before_plausibility).to be_a(Float)
+    end
+
+    it 'transitions to supported after enough supporting evidence' do
+      3.times { client.add_hypothesis_evidence(hypothesis_id: hyp_id, supporting: true) }
+      result = client.add_hypothesis_evidence(hypothesis_id: hyp_id, supporting: true)
+      expect(result[:state]).to eq(:supported)
+    end
+
+    it 'adds contradicting evidence' do
+      result = client.add_hypothesis_evidence(hypothesis_id: hyp_id, supporting: false)
+      expect(result[:success]).to be true
+      expect(result[:state]).to eq(:candidate)
+    end
+
+    it 'returns not_found for unknown hypothesis' do
+      result = client.add_hypothesis_evidence(hypothesis_id: 'missing', supporting: true)
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq(:not_found)
+    end
+  end
+
+  describe '#best_explanation' do
+    let(:obs_id) { client.record_observation(content: 'disk full warning', domain: :storage)[:observation][:id] }
+
+    it 'returns nil found when no hypotheses exist' do
+      result = client.best_explanation(observation_id: obs_id)
+      expect(result[:success]).to be true
+      expect(result[:found]).to be false
+    end
+
+    it 'returns best hypothesis by overall_score' do
+      client.generate_hypothesis(
+        content:           'log files grew unbounded',
+        observation_ids:   [obs_id],
+        domain:            :storage,
+        simplicity:        0.9,
+        explanatory_power: 0.9,
+        prior_probability: 0.8
+      )
+      client.generate_hypothesis(
+        content:           'backup job failed and left temp files',
+        observation_ids:   [obs_id],
+        domain:            :storage,
+        simplicity:        0.3,
+        explanatory_power: 0.4,
+        prior_probability: 0.2
+      )
+      result = client.best_explanation(observation_id: obs_id)
+      expect(result[:success]).to be true
+      expect(result[:found]).to be true
+      expect(result[:hypothesis][:content]).to eq('log files grew unbounded')
+    end
+  end
+
+  describe '#competing_hypotheses' do
+    let(:obs_id) { client.record_observation(content: 'latency spike', domain: :perf)[:observation][:id] }
+
+    it 'returns empty list when no hypotheses' do
+      result = client.competing_hypotheses(observation_id: obs_id)
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(0)
+      expect(result[:hypotheses]).to eq([])
+    end
+
+    it 'returns hypotheses sorted by score descending' do
+      client.generate_hypothesis(
+        content:           'DB slow query',
+        observation_ids:   [obs_id],
+        domain:            :perf,
+        simplicity:        0.8,
+        explanatory_power: 0.8
+      )
+      client.generate_hypothesis(
+        content:           'Network congestion',
+        observation_ids:   [obs_id],
+        domain:            :perf,
+        simplicity:        0.2,
+        explanatory_power: 0.2
+      )
+      result = client.competing_hypotheses(observation_id: obs_id)
+      expect(result[:count]).to eq(2)
+      scores = result[:hypotheses].map { |h| h[:overall_score] }
+      expect(scores).to eq(scores.sort.reverse)
+    end
+  end
+
+  describe '#refute_hypothesis' do
+    let(:obs_id) { client.record_observation(content: 'error 500', domain: :web)[:observation][:id] }
+    let(:hyp_id) do
+      client.generate_hypothesis(
+        content:           'out of memory',
+        observation_ids:   [obs_id],
+        domain:            :web,
+        simplicity:        0.5,
+        explanatory_power: 0.5
+      )[:hypothesis][:id]
+    end
+
+    it 'refutes a hypothesis' do
+      result = client.refute_hypothesis(hypothesis_id: hyp_id)
+      expect(result[:success]).to be true
+      expect(result[:state]).to eq(:refuted)
+    end
+
+    it 'excludes refuted hypotheses from competing list' do
+      client.refute_hypothesis(hypothesis_id: hyp_id)
+      result = client.competing_hypotheses(observation_id: obs_id)
+      expect(result[:count]).to eq(0)
+    end
+
+    it 'returns not_found for unknown hypothesis' do
+      result = client.refute_hypothesis(hypothesis_id: 'ghost')
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq(:not_found)
+    end
+  end
+
+  describe '#unexplained_observations' do
+    it 'returns observations with no supported hypothesis' do
+      client.record_observation(content: 'unexplained event', domain: :mystery)
+      result = client.unexplained_observations
+      expect(result[:success]).to be true
+      expect(result[:count]).to be >= 1
+    end
+
+    it 'excludes observations explained by a supported hypothesis' do
+      obs_id = client.record_observation(content: 'explained', domain: :test)[:observation][:id]
+      hyp_id = client.generate_hypothesis(
+        content:           'known cause',
+        observation_ids:   [obs_id],
+        domain:            :test,
+        simplicity:        0.9,
+        explanatory_power: 0.9
+      )[:hypothesis][:id]
+      3.times { client.add_hypothesis_evidence(hypothesis_id: hyp_id, supporting: true) }
+      client.add_hypothesis_evidence(hypothesis_id: hyp_id, supporting: true)
+
+      result = client.unexplained_observations
+      obs_ids = result[:observations].map { |o| o[:id] }
+      expect(obs_ids).not_to include(obs_id)
+    end
+  end
+
+  describe '#update_abductive_reasoning' do
+    it 'runs decay and prune cycle' do
+      result = client.update_abductive_reasoning
+      expect(result[:success]).to be true
+      expect(result[:decayed]).to be >= 0
+      expect(result[:pruned]).to be >= 0
+    end
+
+    it 'prunes refuted hypotheses' do
+      obs_id = client.record_observation(content: 'obs', domain: :test)[:observation][:id]
+      hyp_id = client.generate_hypothesis(
+        content:           'bad hyp',
+        observation_ids:   [obs_id],
+        domain:            :test,
+        simplicity:        0.5,
+        explanatory_power: 0.5
+      )[:hypothesis][:id]
+      client.refute_hypothesis(hypothesis_id: hyp_id)
+
+      result = client.update_abductive_reasoning
+      expect(result[:pruned]).to eq(1)
+    end
+  end
+
+  describe '#abductive_reasoning_stats' do
+    it 'returns stats hash' do
+      result = client.abductive_reasoning_stats
+      expect(result[:success]).to be true
+      expect(result).to have_key(:observation_count)
+      expect(result).to have_key(:hypothesis_count)
+      expect(result).to have_key(:supported_count)
+      expect(result).to have_key(:refuted_count)
+      expect(result).to have_key(:candidate_count)
+      expect(result).to have_key(:unexplained_count)
+    end
+
+    it 'reflects accumulated state' do
+      client.record_observation(content: 'fact', domain: :test)
+      result = client.abductive_reasoning_stats
+      expect(result[:observation_count]).to be >= 1
+    end
+  end
+
+  describe 'quality labels' do
+    let(:obs_id) { client.record_observation(content: 'obs', domain: :test)[:observation][:id] }
+
+    it 'assigns compelling label for high-scoring hypothesis' do
+      result = client.generate_hypothesis(
+        content:           'strong hypothesis',
+        observation_ids:   [obs_id],
+        domain:            :test,
+        simplicity:        1.0,
+        explanatory_power: 1.0,
+        prior_probability: 1.0
+      )
+      expect(result[:hypothesis][:quality_label]).to eq(:compelling)
+    end
+
+    it 'assigns implausible label for low-scoring hypothesis' do
+      result = client.generate_hypothesis(
+        content:           'weak hypothesis',
+        observation_ids:   [obs_id],
+        domain:            :test,
+        simplicity:        0.0,
+        explanatory_power: 0.0,
+        prior_probability: 0.0
+      )
+      expect(result[:hypothesis][:quality_label]).to eq(:implausible)
+    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/abductive_reasoning'
+
+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,74 @@
+--- !ruby/object:Gem::Specification
+name: lex-abductive-reasoning
+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: Peirce abductive reasoning engine — inference to the best explanation
+  for brain-modeled agentic AI
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-abductive-reasoning.gemspec
+- lib/legion/extensions/abductive_reasoning.rb
+- lib/legion/extensions/abductive_reasoning/client.rb
+- lib/legion/extensions/abductive_reasoning/helpers/abduction_engine.rb
+- lib/legion/extensions/abductive_reasoning/helpers/constants.rb
+- lib/legion/extensions/abductive_reasoning/helpers/hypothesis.rb
+- lib/legion/extensions/abductive_reasoning/helpers/observation.rb
+- lib/legion/extensions/abductive_reasoning/runners/abductive_reasoning.rb
+- lib/legion/extensions/abductive_reasoning/version.rb
+- spec/legion/extensions/abductive_reasoning/client_spec.rb
+- spec/legion/extensions/abductive_reasoning/runners/abductive_reasoning_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-abductive-reasoning
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-abductive-reasoning
+  source_code_uri: https://github.com/LegionIO/lex-abductive-reasoning
+  documentation_uri: https://github.com/LegionIO/lex-abductive-reasoning
+  changelog_uri: https://github.com/LegionIO/lex-abductive-reasoning
+  bug_tracker_uri: https://github.com/LegionIO/lex-abductive-reasoning/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 Abductive Reasoning
+test_files: []