lex-agentic-inference 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6dd00ebbcc35eceb42f311a3fe5a3eb05cd85dfe202b25e990aa9e763c767e9a
+  data.tar.gz: e77d26da91244a176b5a784838b5cc39e6e98d7e24db1e8670c632fce8cde8e3
+SHA512:
+  metadata.gz: fda03d8791a5668dedc78b0017abb410b75d941d309d594e8cf46ac96b9d6e81ae6324e3fe2b71ebe89de8244771905330e84e20ea914bdec6fa964738fc63e2
+  data.tar.gz: 7a971543bc03ec39d07f1165428bcebccb49c9b9d5c938530b9aa6593752f204f6e9a4f83c50b1baed2f422790bd2fffaab50703212f931c3cc81b49c058c7d1

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-18
+
+### Added
+- Initial release as domain consolidation gem
+- Consolidated source extensions into unified domain gem under `Legion::Extensions::Agentic::<Domain>`
+- All sub-modules loaded from single entry point
+- Full spec suite with zero failures
+- RuboCop compliance across all files

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Iverson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,13 @@
+# lex-agentic-inference
+
+LEX agentic inference domain: causal reasoning, prediction, belief updating
+
+## Sub-modules
+
+*(populated as extensions are consolidated)*
+
+## Installation
+
+```ruby
+gem 'lex-agentic-inference'
+```

data/lex-agentic-inference.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/agentic/inference/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-agentic-inference'
+  spec.version       = Legion::Extensions::Agentic::Inference::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Agentic Inference'
+  spec.description   = 'LEX agentic inference domain: causal reasoning, prediction, belief updating'
+  spec.homepage      = 'https://github.com/LegionIO/lex-agentic-inference'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']      = spec.homepage
+  spec.metadata['source_code_uri']   = spec.homepage
+  spec.metadata['changelog_uri']     = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir.glob('{lib,spec}/**/*.rb') + %w[lex-agentic-inference.gemspec Gemfile LICENSE README.md CHANGELOG.md]
+  end
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'rspec', '~> 3.13'
+  spec.add_development_dependency 'rubocop', '~> 1.60'
+  spec.add_development_dependency 'rubocop-rspec', '~> 2.26'
+end

data/lib/legion/extensions/agentic/inference/abductive/client.rb

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

data/lib/legion/extensions/agentic/inference/abductive/helpers/abduction_engine.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module Abductive
+          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
+  end
+end

data/lib/legion/extensions/agentic/inference/abductive/helpers/constants.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module Abductive
+          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
+  end
+end

data/lib/legion/extensions/agentic/inference/abductive/helpers/hypothesis.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module Abductive
+          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
+  end
+end

data/lib/legion/extensions/agentic/inference/abductive/helpers/observation.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module Abductive
+          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
+  end
+end

data/lib/legion/extensions/agentic/inference/abductive/runners/abductive_reasoning.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module Abductive
+          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
+  end
+end

data/lib/legion/extensions/agentic/inference/abductive/version.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module Abductive
+          VERSION = '0.1.0'
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/inference/abductive.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/inference/abductive/version'
+require 'legion/extensions/agentic/inference/abductive/helpers/constants'
+require 'legion/extensions/agentic/inference/abductive/helpers/observation'
+require 'legion/extensions/agentic/inference/abductive/helpers/hypothesis'
+require 'legion/extensions/agentic/inference/abductive/helpers/abduction_engine'
+require 'legion/extensions/agentic/inference/abductive/runners/abductive_reasoning'
+require 'legion/extensions/agentic/inference/abductive/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module Abductive
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/inference/affordance/actors/scan.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module Affordance
+          module Actor
+            class Scan < Legion::Extensions::Actors::Every
+              def time
+                30
+              end
+
+              def use_runner?
+                false
+              end
+
+              def runner_function
+                :update_affordances
+              end
+
+              def runner_class
+                Legion::Extensions::Agentic::Inference::Affordance::Runners::Affordance
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end