lex-causal-reasoning 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 88afa7864d6dde283f8596ad1e51ad4a3bc78979213b93f17586cb4e9b7bece6
+  data.tar.gz: 6c079e57fb21b832e38292d99ad9ba065e34f1118cdfa45f96ecf035af316fce
+SHA512:
+  metadata.gz: 71ca379df8257700e646032095624246f273063884224e0f74718bf13b61eaa6aecaa499a07f88b799997f4706a8e1280f2aac672efe56fcb54141b2dbdcee8f
+  data.tar.gz: d5596c7ea7ef37f4f3c83aaf5787a353cc0b75272b83ce80a85c535cceb6d520d2926b312931baa875b89d2578ff38b6d6e2f817f06e4ede3b7c7e7247a0a3a7

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

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

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/causal_reasoning/helpers/constants'
+require 'legion/extensions/causal_reasoning/helpers/causal_edge'
+require 'legion/extensions/causal_reasoning/helpers/causal_graph'
+require 'legion/extensions/causal_reasoning/runners/causal_reasoning'
+
+module Legion
+  module Extensions
+    module CausalReasoning
+      class Client
+        include Runners::CausalReasoning
+
+        def initialize(graph: nil, **)
+          @graph = graph
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/causal_reasoning/helpers/causal_edge.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CausalReasoning
+      module Helpers
+        class CausalEdge
+          include Constants
+
+          attr_reader :id, :cause, :effect, :edge_type, :domain, :evidence_count, :created_at, :updated_at, :strength
+
+          def initialize(cause:, effect:, edge_type:, domain: :general, strength: Constants::DEFAULT_STRENGTH)
+            @id             = SecureRandom.uuid
+            @cause          = cause
+            @effect         = effect
+            @edge_type      = edge_type
+            @domain         = domain
+            @strength       = strength.clamp(Constants::STRENGTH_FLOOR, Constants::STRENGTH_CEILING)
+            @evidence_count = 0
+            @created_at     = Time.now.utc
+            @updated_at     = Time.now.utc
+          end
+
+          def add_evidence
+            @evidence_count += 1
+            @strength = (@strength + Constants::REINFORCEMENT_RATE).clamp(
+              Constants::STRENGTH_FLOOR, Constants::STRENGTH_CEILING
+            )
+            @updated_at = Time.now.utc
+            self
+          end
+
+          def remove_evidence
+            @evidence_count = [@evidence_count - 1, 0].max
+            @strength = (@strength - Constants::REINFORCEMENT_RATE).clamp(
+              Constants::STRENGTH_FLOOR, Constants::STRENGTH_CEILING
+            )
+            @updated_at = Time.now.utc
+            self
+          end
+
+          def reinforce(amount: Constants::REINFORCEMENT_RATE)
+            @strength = (@strength + amount).clamp(
+              Constants::STRENGTH_FLOOR, Constants::STRENGTH_CEILING
+            )
+            @updated_at = Time.now.utc
+            self
+          end
+
+          def weaken(amount: Constants::REINFORCEMENT_RATE)
+            @strength = (@strength - amount).clamp(
+              Constants::STRENGTH_FLOOR, Constants::STRENGTH_CEILING
+            )
+            @updated_at = Time.now.utc
+            self
+          end
+
+          def decay
+            @strength = (@strength - Constants::DECAY_RATE).clamp(
+              Constants::STRENGTH_FLOOR, Constants::STRENGTH_CEILING
+            )
+            @updated_at = Time.now.utc
+            self
+          end
+
+          def confident?
+            @strength >= Constants::CAUSAL_THRESHOLD &&
+              @evidence_count >= Constants::EVIDENCE_THRESHOLD
+          end
+
+          def confidence_label
+            match = Constants::CONFIDENCE_LABELS.find { |range, _| range.cover?(@strength) }
+            match ? match[1] : :speculative
+          end
+
+          def to_h
+            {
+              id:             @id,
+              cause:          @cause,
+              effect:         @effect,
+              edge_type:      @edge_type,
+              domain:         @domain,
+              strength:       @strength,
+              evidence_count: @evidence_count,
+              confident:      confident?,
+              label:          confidence_label,
+              created_at:     @created_at,
+              updated_at:     @updated_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/causal_reasoning/helpers/causal_graph.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CausalReasoning
+      module Helpers
+        class CausalGraph
+          def initialize
+            @variables  = {}
+            @edges      = {}
+            @edge_index = {}
+          end
+
+          def add_variable(name:, domain: :general)
+            return nil if @variables.key?(name)
+            return nil if @variables.size >= Constants::MAX_VARIABLES
+
+            @variables[name] = { name: name, domain: domain, added_at: Time.now.utc }
+          end
+
+          def variable_exists?(name)
+            @variables.key?(name)
+          end
+
+          def add_edge(cause:, effect:, edge_type:, domain: :general, strength: Constants::DEFAULT_STRENGTH)
+            return nil if @edges.size >= Constants::MAX_EDGES
+            return nil unless Constants::EDGE_TYPES.include?(edge_type)
+
+            add_variable(name: cause, domain: domain)
+            add_variable(name: effect, domain: domain)
+
+            edge = CausalEdge.new(cause: cause, effect: effect,
+                                  edge_type: edge_type, domain: domain, strength: strength)
+            @edges[edge.id] = edge
+            @edge_index[cause] ||= []
+            @edge_index[cause] << edge.id
+            edge
+          end
+
+          def remove_edge(edge_id:)
+            edge = @edges.delete(edge_id)
+            return nil unless edge
+
+            @edge_index[edge.cause]&.delete(edge_id)
+            edge
+          end
+
+          def causes_of(variable:)
+            @edges.values.select { |e| e.effect == variable }
+          end
+
+          def effects_of(variable:)
+            ids = @edge_index.fetch(variable, [])
+            ids.filter_map { |id| @edges[id] }
+          end
+
+          def causal_chain(from:, to:, max_depth: 5)
+            return [] if from == to
+
+            queue   = [[from, [from]]]
+            visited = { from => true }
+            paths   = []
+
+            until queue.empty?
+              current, path = queue.shift
+              next if path.size > max_depth + 1
+
+              effects_of(variable: current).each do |edge|
+                neighbor = edge.effect
+                new_path = path + [neighbor]
+
+                if neighbor == to
+                  paths << new_path
+                  next
+                end
+
+                next if visited[neighbor]
+
+                visited[neighbor] = true
+                queue << [neighbor, new_path]
+              end
+            end
+
+            paths
+          end
+
+          def intervene(variable:, value:)
+            downstream = []
+            queue      = [variable]
+            visited    = { variable => true }
+
+            until queue.empty?
+              current = queue.shift
+              effects_of(variable: current).each do |edge|
+                neighbor = edge.effect
+                downstream << { variable: neighbor, via_edge: edge.id, edge_type: edge.edge_type }
+                next if visited[neighbor]
+
+                visited[neighbor] = true
+                queue << neighbor
+              end
+            end
+
+            { intervention: variable, value: value, downstream_effects: downstream }
+          end
+
+          def observe(variable:, value:, evidence:)
+            affected = causes_of(variable: variable) + effects_of(variable: variable)
+            affected.each { |edge| edge.add_evidence if evidence }
+            { variable: variable, value: value, edges_updated: affected.size }
+          end
+
+          def confounders(var_a:, var_b:)
+            ancestors_a = ancestors_of(var_a)
+            ancestors_b = ancestors_of(var_b)
+            common      = ancestors_a & ancestors_b
+            common.reject { |v| v == var_a || v == var_b }
+          end
+
+          def add_evidence(edge_id:)
+            edge = @edges[edge_id]
+            return nil unless edge
+
+            edge.add_evidence
+          end
+
+          def remove_evidence(edge_id:)
+            edge = @edges[edge_id]
+            return nil unless edge
+
+            edge.remove_evidence
+          end
+
+          def confident_edges
+            @edges.values.select(&:confident?)
+          end
+
+          def by_domain(domain:)
+            @edges.values.select { |e| e.domain == domain }
+          end
+
+          def by_type(type:)
+            @edges.values.select { |e| e.edge_type == type }
+          end
+
+          def decay_all
+            @edges.each_value(&:decay)
+            @edges.size
+          end
+
+          def prune_weak
+            weak_ids = @edges.select { |_, e| e.strength <= Constants::STRENGTH_FLOOR }.keys
+            weak_ids.each { |id| remove_edge(edge_id: id) }
+            weak_ids.size
+          end
+
+          def to_h
+            {
+              variables:       @variables.size,
+              edges:           @edges.size,
+              confident_edges: confident_edges.size,
+              edge_types:      Constants::EDGE_TYPES.to_h { |t| [t, by_type(type: t).size] }
+            }
+          end
+
+          private
+
+          def ancestors_of(variable, visited = {})
+            return [] if visited[variable]
+
+            visited[variable] = true
+            direct_causes = causes_of(variable: variable).map(&:cause)
+            indirect      = direct_causes.flat_map { |c| ancestors_of(c, visited) }
+            (direct_causes + indirect).uniq
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CausalReasoning
+      module Helpers
+        module Constants
+          MAX_VARIABLES = 200
+          MAX_EDGES     = 500
+          MAX_HISTORY   = 300
+
+          DEFAULT_STRENGTH  = 0.5
+          STRENGTH_FLOOR    = 0.05
+          STRENGTH_CEILING  = 0.95
+
+          EVIDENCE_THRESHOLD = 3
+          CAUSAL_THRESHOLD   = 0.6
+
+          REINFORCEMENT_RATE = 0.1
+          DECAY_RATE         = 0.01
+
+          EDGE_TYPES      = %i[causes prevents enables inhibits modulates].freeze
+          INFERENCE_TYPES = %i[observation intervention counterfactual].freeze
+
+          CONFIDENCE_LABELS = {
+            (0.8..)     => :strong,
+            (0.6...0.8) => :moderate,
+            (0.4...0.6) => :weak,
+            (0.2...0.4) => :tentative,
+            (..0.2)     => :speculative
+          }.freeze
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CausalReasoning
+      module Runners
+        module CausalReasoning
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def add_causal_variable(name:, domain: :general, **)
+            if graph.variable_exists?(name)
+              Legion::Logging.warn "[causal] add_variable duplicate: name=#{name}"
+              return { success: false, reason: :limit_or_duplicate, name: name }
+            end
+
+            variable = graph.add_variable(name: name, domain: domain)
+            if variable
+              Legion::Logging.debug "[causal] add_variable: name=#{name} domain=#{domain}"
+              { success: true, variable: variable }
+            else
+              Legion::Logging.warn "[causal] add_variable failed (limit): name=#{name}"
+              { success: false, reason: :limit_or_duplicate, name: name }
+            end
+          end
+
+          def add_causal_edge(cause:, effect:, edge_type:, domain: :general,
+                              strength: Helpers::Constants::DEFAULT_STRENGTH, **)
+            edge = graph.add_edge(cause: cause, effect: effect,
+                                  edge_type: edge_type, domain: domain, strength: strength)
+            if edge
+              str = edge.strength.round(2)
+              Legion::Logging.debug "[causal] add_edge: #{cause}->#{effect} type=#{edge_type} str=#{str}"
+              { success: true, edge: edge.to_h }
+            else
+              Legion::Logging.warn "[causal] add_edge failed: cause=#{cause} effect=#{effect} type=#{edge_type}"
+              { success: false, reason: :limit_or_invalid_type, cause: cause, effect: effect }
+            end
+          end
+
+          def find_causes(variable:, **)
+            edges = graph.causes_of(variable: variable)
+            Legion::Logging.debug "[causal] find_causes: variable=#{variable} count=#{edges.size}"
+            { success: true, variable: variable, causes: edges.map(&:to_h), count: edges.size }
+          end
+
+          def find_effects(variable:, **)
+            edges = graph.effects_of(variable: variable)
+            Legion::Logging.debug "[causal] find_effects: variable=#{variable} count=#{edges.size}"
+            { success: true, variable: variable, effects: edges.map(&:to_h), count: edges.size }
+          end
+
+          def trace_causal_chain(from:, to:, max_depth: 5, **)
+            paths = graph.causal_chain(from: from, to: to, max_depth: max_depth)
+            Legion::Logging.debug "[causal] trace_chain: from=#{from} to=#{to} paths=#{paths.size}"
+            { success: true, from: from, to: to, paths: paths, path_count: paths.size }
+          end
+
+          def causal_intervention(variable:, value:, **)
+            result = graph.intervene(variable: variable, value: value)
+            count = result[:downstream_effects].size
+            Legion::Logging.info "[causal] intervention: do(#{variable}=#{value}) downstream=#{count}"
+            { success: true }.merge(result)
+          end
+
+          def find_confounders(var_a:, var_b:, **)
+            common = graph.confounders(var_a: var_a, var_b: var_b)
+            Legion::Logging.debug "[causal] confounders: #{var_a} <-> #{var_b} count=#{common.size}"
+            { success: true, var_a: var_a, var_b: var_b, confounders: common, count: common.size }
+          end
+
+          def add_causal_evidence(edge_id:, **)
+            edge = graph.add_evidence(edge_id: edge_id)
+            if edge
+              cnt = edge.evidence_count
+              str = edge.strength.round(2)
+              Legion::Logging.debug "[causal] add_evidence: edge=#{edge_id} count=#{cnt} strength=#{str}"
+              { success: true, edge_id: edge_id, evidence_count: edge.evidence_count, strength: edge.strength }
+            else
+              Legion::Logging.warn "[causal] add_evidence failed: edge=#{edge_id} not found"
+              { success: false, reason: :edge_not_found, edge_id: edge_id }
+            end
+          end
+
+          def update_causal_reasoning(**)
+            decayed = graph.decay_all
+            pruned  = graph.prune_weak
+            Legion::Logging.debug "[causal] update: decayed=#{decayed} pruned=#{pruned}"
+            { success: true, decayed: decayed, pruned: pruned }
+          end
+
+          def causal_reasoning_stats(**)
+            stats = graph.to_h
+            Legion::Logging.debug "[causal] stats: #{stats.inspect}"
+            { success: true }.merge(stats)
+          end
+
+          private
+
+          def graph
+            @graph ||= Helpers::CausalGraph.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/causal_reasoning.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/causal_reasoning/version'
+require 'legion/extensions/causal_reasoning/helpers/constants'
+require 'legion/extensions/causal_reasoning/helpers/causal_edge'
+require 'legion/extensions/causal_reasoning/helpers/causal_graph'
+require 'legion/extensions/causal_reasoning/runners/causal_reasoning'
+
+module Legion
+  module Extensions
+    module CausalReasoning
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/causal_reasoning/client'
+
+RSpec.describe Legion::Extensions::CausalReasoning::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to all runner methods' do
+    expect(client).to respond_to(:add_causal_variable)
+    expect(client).to respond_to(:add_causal_edge)
+    expect(client).to respond_to(:find_causes)
+    expect(client).to respond_to(:find_effects)
+    expect(client).to respond_to(:trace_causal_chain)
+    expect(client).to respond_to(:causal_intervention)
+    expect(client).to respond_to(:find_confounders)
+    expect(client).to respond_to(:add_causal_evidence)
+    expect(client).to respond_to(:update_causal_reasoning)
+    expect(client).to respond_to(:causal_reasoning_stats)
+  end
+
+  it 'accepts an injected graph' do
+    injected_graph = Legion::Extensions::CausalReasoning::Helpers::CausalGraph.new
+    injected_graph.add_edge(cause: :a, effect: :b, edge_type: :causes)
+    client_with_graph = described_class.new(graph: injected_graph)
+    result = client_with_graph.causal_reasoning_stats
+    expect(result[:edges]).to eq(1)
+  end
+
+  it 'maintains isolated state between instances' do
+    c1 = described_class.new
+    c2 = described_class.new
+    c1.add_causal_edge(cause: :a, effect: :b, edge_type: :causes)
+    expect(c2.causal_reasoning_stats[:edges]).to eq(0)
+  end
+end

data/spec/legion/extensions/causal_reasoning/helpers/causal_edge_spec.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/causal_reasoning/client'
+
+RSpec.describe Legion::Extensions::CausalReasoning::Helpers::CausalEdge do
+  subject(:edge) do
+    described_class.new(cause: :rain, effect: :wet_grass, edge_type: :causes, domain: :weather)
+  end
+
+  describe '#initialize' do
+    it 'sets cause and effect' do
+      expect(edge.cause).to eq(:rain)
+      expect(edge.effect).to eq(:wet_grass)
+    end
+
+    it 'sets edge_type and domain' do
+      expect(edge.edge_type).to eq(:causes)
+      expect(edge.domain).to eq(:weather)
+    end
+
+    it 'clamps strength to STRENGTH_FLOOR..STRENGTH_CEILING' do
+      over  = described_class.new(cause: :a, effect: :b, edge_type: :causes, strength: 2.0)
+      under = described_class.new(cause: :a, effect: :b, edge_type: :causes, strength: 0.0)
+      expect(over.strength).to eq(Legion::Extensions::CausalReasoning::Helpers::Constants::STRENGTH_CEILING)
+      expect(under.strength).to eq(Legion::Extensions::CausalReasoning::Helpers::Constants::STRENGTH_FLOOR)
+    end
+
+    it 'starts with evidence_count of zero' do
+      expect(edge.evidence_count).to eq(0)
+    end
+
+    it 'assigns a unique id' do
+      other = described_class.new(cause: :rain, effect: :wet_grass, edge_type: :causes)
+      expect(edge.id).not_to eq(other.id)
+    end
+  end
+
+  describe '#add_evidence' do
+    it 'increments evidence_count' do
+      edge.add_evidence
+      expect(edge.evidence_count).to eq(1)
+    end
+
+    it 'increases strength' do
+      before = edge.strength
+      edge.add_evidence
+      expect(edge.strength).to be > before
+    end
+
+    it 'returns self' do
+      expect(edge.add_evidence).to be(edge)
+    end
+
+    it 'does not exceed STRENGTH_CEILING' do
+      100.times { edge.add_evidence }
+      expect(edge.strength).to eq(Legion::Extensions::CausalReasoning::Helpers::Constants::STRENGTH_CEILING)
+    end
+  end
+
+  describe '#remove_evidence' do
+    it 'decrements evidence_count but not below zero' do
+      edge.remove_evidence
+      expect(edge.evidence_count).to eq(0)
+    end
+
+    it 'decreases strength' do
+      before = edge.strength
+      edge.remove_evidence
+      expect(edge.strength).to be < before
+    end
+
+    it 'does not go below STRENGTH_FLOOR' do
+      100.times { edge.remove_evidence }
+      expect(edge.strength).to eq(Legion::Extensions::CausalReasoning::Helpers::Constants::STRENGTH_FLOOR)
+    end
+  end
+
+  describe '#reinforce' do
+    it 'increases strength by given amount' do
+      before = edge.strength
+      edge.reinforce(amount: 0.2)
+      expect(edge.strength).to be_within(0.001).of(before + 0.2)
+    end
+
+    it 'clamps at STRENGTH_CEILING' do
+      edge.reinforce(amount: 1.0)
+      expect(edge.strength).to eq(Legion::Extensions::CausalReasoning::Helpers::Constants::STRENGTH_CEILING)
+    end
+  end
+
+  describe '#weaken' do
+    it 'decreases strength by given amount' do
+      before = edge.strength
+      edge.weaken(amount: 0.1)
+      expect(edge.strength).to be_within(0.001).of(before - 0.1)
+    end
+
+    it 'clamps at STRENGTH_FLOOR' do
+      edge.weaken(amount: 1.0)
+      expect(edge.strength).to eq(Legion::Extensions::CausalReasoning::Helpers::Constants::STRENGTH_FLOOR)
+    end
+  end
+
+  describe '#decay' do
+    it 'reduces strength by DECAY_RATE' do
+      before = edge.strength
+      edge.decay
+      expect(edge.strength).to be_within(0.001).of(before - Legion::Extensions::CausalReasoning::Helpers::Constants::DECAY_RATE)
+    end
+
+    it 'does not go below STRENGTH_FLOOR' do
+      100.times { edge.decay }
+      expect(edge.strength).to eq(Legion::Extensions::CausalReasoning::Helpers::Constants::STRENGTH_FLOOR)
+    end
+  end
+
+  describe '#confident?' do
+    it 'returns false when evidence_count is below EVIDENCE_THRESHOLD' do
+      expect(edge.confident?).to be false
+    end
+
+    it 'returns true when both strength and evidence_count meet thresholds' do
+      3.times { edge.add_evidence }
+      edge.reinforce(amount: 0.2)
+      expect(edge.confident?).to be true
+    end
+  end
+
+  describe '#confidence_label' do
+    it 'returns :speculative for low strength' do
+      edge.weaken(amount: 1.0)
+      expect(edge.confidence_label).to eq(:speculative)
+    end
+
+    it 'returns :moderate for strength around 0.7' do
+      strong_edge = described_class.new(cause: :a, effect: :b, edge_type: :causes, strength: 0.7)
+      expect(strong_edge.confidence_label).to eq(:moderate)
+    end
+
+    it 'returns :strong for strength >= 0.8' do
+      strong_edge = described_class.new(cause: :a, effect: :b, edge_type: :causes, strength: 0.9)
+      expect(strong_edge.confidence_label).to eq(:strong)
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all key fields' do
+      hash = edge.to_h
+      expect(hash).to include(:id, :cause, :effect, :edge_type, :domain,
+                              :strength, :evidence_count, :confident, :label,
+                              :created_at, :updated_at)
+    end
+
+    it 'reflects confident? state' do
+      expect(edge.to_h[:confident]).to be false
+    end
+  end
+end

data/spec/legion/extensions/causal_reasoning/helpers/causal_graph_spec.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/causal_reasoning/client'
+
+RSpec.describe Legion::Extensions::CausalReasoning::Helpers::CausalGraph do
+  subject(:graph) { described_class.new }
+
+  let(:const) { Legion::Extensions::CausalReasoning::Helpers::Constants }
+
+  def add_rain_wet(grph = graph)
+    grph.add_edge(cause: :rain, effect: :wet_grass, edge_type: :causes, domain: :weather)
+  end
+
+  describe '#add_variable' do
+    it 'registers a new variable and returns it' do
+      var = graph.add_variable(name: :temperature, domain: :weather)
+      expect(var[:name]).to eq(:temperature)
+      expect(var[:domain]).to eq(:weather)
+    end
+
+    it 'returns nil for a duplicate variable name' do
+      graph.add_variable(name: :temperature, domain: :weather)
+      result = graph.add_variable(name: :temperature, domain: :weather)
+      expect(result).to be_nil
+    end
+  end
+
+  describe '#add_edge' do
+    it 'creates and returns a CausalEdge' do
+      edge = add_rain_wet
+      expect(edge).to be_a(Legion::Extensions::CausalReasoning::Helpers::CausalEdge)
+    end
+
+    it 'auto-registers both cause and effect as variables' do
+      add_rain_wet
+      expect(graph.to_h[:variables]).to eq(2)
+    end
+
+    it 'returns nil for unknown edge_type' do
+      result = graph.add_edge(cause: :a, effect: :b, edge_type: :unknown_type)
+      expect(result).to be_nil
+    end
+
+    it 'accepts all valid EDGE_TYPES' do
+      const::EDGE_TYPES.each_with_index do |type, idx|
+        result = graph.add_edge(cause: :"cause_#{idx}", effect: :"effect_#{idx}", edge_type: type)
+        expect(result).not_to be_nil
+      end
+    end
+  end
+
+  describe '#remove_edge' do
+    it 'removes an existing edge and returns it' do
+      edge    = add_rain_wet
+      removed = graph.remove_edge(edge_id: edge.id)
+      expect(removed.id).to eq(edge.id)
+      expect(graph.to_h[:edges]).to eq(0)
+    end
+
+    it 'returns nil for unknown edge_id' do
+      expect(graph.remove_edge(edge_id: 'nonexistent')).to be_nil
+    end
+  end
+
+  describe '#causes_of' do
+    it 'returns edges where the variable is the effect' do
+      add_rain_wet
+      causes = graph.causes_of(variable: :wet_grass)
+      expect(causes.size).to eq(1)
+      expect(causes.first.cause).to eq(:rain)
+    end
+
+    it 'returns empty array for variable with no causes' do
+      expect(graph.causes_of(variable: :rain)).to be_empty
+    end
+  end
+
+  describe '#effects_of' do
+    it 'returns edges where the variable is the cause' do
+      add_rain_wet
+      effects = graph.effects_of(variable: :rain)
+      expect(effects.size).to eq(1)
+      expect(effects.first.effect).to eq(:wet_grass)
+    end
+
+    it 'returns empty array for unknown variable' do
+      expect(graph.effects_of(variable: :unknown)).to be_empty
+    end
+  end
+
+  describe '#causal_chain' do
+    before do
+      graph.add_edge(cause: :rain, effect: :wet_grass, edge_type: :causes)
+      graph.add_edge(cause: :wet_grass, effect: :slippery_path, edge_type: :causes)
+    end
+
+    it 'finds a direct path between connected variables' do
+      paths = graph.causal_chain(from: :rain, to: :slippery_path)
+      expect(paths).not_to be_empty
+      expect(paths.first).to eq(%i[rain wet_grass slippery_path])
+    end
+
+    it 'returns empty array when no path exists' do
+      paths = graph.causal_chain(from: :slippery_path, to: :rain)
+      expect(paths).to be_empty
+    end
+
+    it 'returns empty array when from == to' do
+      paths = graph.causal_chain(from: :rain, to: :rain)
+      expect(paths).to be_empty
+    end
+
+    it 'respects max_depth' do
+      graph.add_edge(cause: :slippery_path, effect: :injury, edge_type: :causes)
+      graph.add_edge(cause: :injury, effect: :hospital_visit, edge_type: :causes)
+      paths = graph.causal_chain(from: :rain, to: :hospital_visit, max_depth: 2)
+      expect(paths).to be_empty
+    end
+  end
+
+  describe '#intervene' do
+    before do
+      graph.add_edge(cause: :smoking, effect: :cancer, edge_type: :causes)
+      graph.add_edge(cause: :cancer, effect: :death, edge_type: :causes)
+    end
+
+    it 'returns the intervention variable and value' do
+      result = graph.intervene(variable: :smoking, value: true)
+      expect(result[:intervention]).to eq(:smoking)
+      expect(result[:value]).to be true
+    end
+
+    it 'lists all downstream effects' do
+      result = graph.intervene(variable: :smoking, value: true)
+      variables = result[:downstream_effects].map { |e| e[:variable] }
+      expect(variables).to include(:cancer, :death)
+    end
+
+    it 'returns empty downstream for leaf variable' do
+      result = graph.intervene(variable: :death, value: true)
+      expect(result[:downstream_effects]).to be_empty
+    end
+  end
+
+  describe '#observe' do
+    it 'updates edges involving the variable when evidence is true' do
+      edge = add_rain_wet
+      before_count = edge.evidence_count
+      graph.observe(variable: :rain, value: true, evidence: true)
+      expect(edge.evidence_count).to be > before_count
+    end
+
+    it 'returns the variable, value, and count of edges updated' do
+      add_rain_wet
+      result = graph.observe(variable: :rain, value: true, evidence: true)
+      expect(result[:variable]).to eq(:rain)
+      expect(result[:edges_updated]).to eq(1)
+    end
+  end
+
+  describe '#confounders' do
+    it 'finds common ancestors of two variables' do
+      graph.add_edge(cause: :weather, effect: :rain, edge_type: :causes)
+      graph.add_edge(cause: :weather, effect: :cold, edge_type: :causes)
+      common = graph.confounders(var_a: :rain, var_b: :cold)
+      expect(common).to include(:weather)
+    end
+
+    it 'returns empty array when no confounders exist' do
+      graph.add_edge(cause: :a, effect: :b, edge_type: :causes)
+      graph.add_edge(cause: :c, effect: :d, edge_type: :causes)
+      expect(graph.confounders(var_a: :b, var_b: :d)).to be_empty
+    end
+  end
+
+  describe '#add_evidence and #remove_evidence' do
+    it 'delegates add_evidence to the edge' do
+      edge = add_rain_wet
+      graph.add_evidence(edge_id: edge.id)
+      expect(edge.evidence_count).to eq(1)
+    end
+
+    it 'returns nil for unknown edge_id in add_evidence' do
+      expect(graph.add_evidence(edge_id: 'bad_id')).to be_nil
+    end
+
+    it 'delegates remove_evidence to the edge' do
+      edge = add_rain_wet
+      edge.add_evidence
+      graph.remove_evidence(edge_id: edge.id)
+      expect(edge.evidence_count).to eq(0)
+    end
+  end
+
+  describe '#confident_edges' do
+    it 'returns only edges meeting confidence threshold' do
+      edge = add_rain_wet
+      3.times { edge.add_evidence }
+      edge.reinforce(amount: 0.2)
+      expect(graph.confident_edges).to include(edge)
+    end
+
+    it 'excludes edges below threshold' do
+      add_rain_wet
+      expect(graph.confident_edges).to be_empty
+    end
+  end
+
+  describe '#by_domain and #by_type' do
+    before do
+      graph.add_edge(cause: :rain, effect: :wet_grass, edge_type: :causes, domain: :weather)
+      graph.add_edge(cause: :stress, effect: :illness, edge_type: :causes, domain: :health)
+    end
+
+    it 'filters edges by domain' do
+      expect(graph.by_domain(domain: :weather).size).to eq(1)
+      expect(graph.by_domain(domain: :health).size).to eq(1)
+    end
+
+    it 'filters edges by type' do
+      expect(graph.by_type(type: :causes).size).to eq(2)
+      expect(graph.by_type(type: :prevents).size).to eq(0)
+    end
+  end
+
+  describe '#decay_all' do
+    it 'decays all edges and returns total count' do
+      add_rain_wet
+      result = graph.decay_all
+      expect(result).to eq(1)
+    end
+  end
+
+  describe '#prune_weak' do
+    it 'removes edges at STRENGTH_FLOOR and returns count' do
+      edge = add_rain_wet
+      100.times { edge.weaken }
+      pruned = graph.prune_weak
+      expect(pruned).to eq(1)
+      expect(graph.to_h[:edges]).to eq(0)
+    end
+
+    it 'returns 0 when no weak edges exist' do
+      add_rain_wet
+      expect(graph.prune_weak).to eq(0)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns stats hash with variables, edges, confident_edges, edge_types' do
+      add_rain_wet
+      stats = graph.to_h
+      expect(stats[:variables]).to eq(2)
+      expect(stats[:edges]).to eq(1)
+      expect(stats[:edge_types]).to be_a(Hash)
+      expect(stats[:edge_types][:causes]).to eq(1)
+    end
+  end
+end

data/spec/legion/extensions/causal_reasoning/runners/causal_reasoning_spec.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/causal_reasoning/client'
+
+RSpec.describe Legion::Extensions::CausalReasoning::Runners::CausalReasoning do
+  let(:client) { Legion::Extensions::CausalReasoning::Client.new }
+
+  describe '#add_causal_variable' do
+    it 'returns success: true and the variable hash' do
+      result = client.add_causal_variable(name: :temperature, domain: :weather)
+      expect(result[:success]).to be true
+      expect(result[:variable][:name]).to eq(:temperature)
+    end
+
+    it 'returns success: false for duplicate variable' do
+      client.add_causal_variable(name: :temperature, domain: :weather)
+      result = client.add_causal_variable(name: :temperature, domain: :weather)
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:limit_or_duplicate)
+    end
+  end
+
+  describe '#add_causal_edge' do
+    it 'returns success: true and an edge hash' do
+      result = client.add_causal_edge(cause: :rain, effect: :wet_grass, edge_type: :causes)
+      expect(result[:success]).to be true
+      expect(result[:edge][:cause]).to eq(:rain)
+      expect(result[:edge][:effect]).to eq(:wet_grass)
+    end
+
+    it 'returns success: false for invalid edge_type' do
+      result = client.add_causal_edge(cause: :a, effect: :b, edge_type: :unknown)
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:limit_or_invalid_type)
+    end
+
+    it 'uses given strength' do
+      result = client.add_causal_edge(cause: :a, effect: :b, edge_type: :causes, strength: 0.8)
+      expect(result[:edge][:strength]).to be_within(0.001).of(0.8)
+    end
+  end
+
+  describe '#find_causes' do
+    it 'returns causes of a variable' do
+      client.add_causal_edge(cause: :rain, effect: :wet_grass, edge_type: :causes)
+      result = client.find_causes(variable: :wet_grass)
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(1)
+      expect(result[:causes].first[:cause]).to eq(:rain)
+    end
+
+    it 'returns empty causes for variable with no incoming edges' do
+      client.add_causal_edge(cause: :rain, effect: :wet_grass, edge_type: :causes)
+      result = client.find_causes(variable: :rain)
+      expect(result[:count]).to eq(0)
+    end
+  end
+
+  describe '#find_effects' do
+    it 'returns effects of a variable' do
+      client.add_causal_edge(cause: :rain, effect: :wet_grass, edge_type: :causes)
+      result = client.find_effects(variable: :rain)
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(1)
+      expect(result[:effects].first[:effect]).to eq(:wet_grass)
+    end
+
+    it 'returns empty effects for leaf variable' do
+      client.add_causal_edge(cause: :rain, effect: :wet_grass, edge_type: :causes)
+      result = client.find_effects(variable: :wet_grass)
+      expect(result[:count]).to eq(0)
+    end
+  end
+
+  describe '#trace_causal_chain' do
+    before do
+      client.add_causal_edge(cause: :rain, effect: :wet_grass, edge_type: :causes)
+      client.add_causal_edge(cause: :wet_grass, effect: :slippery, edge_type: :causes)
+    end
+
+    it 'finds a multi-hop causal path' do
+      result = client.trace_causal_chain(from: :rain, to: :slippery)
+      expect(result[:success]).to be true
+      expect(result[:path_count]).to be >= 1
+    end
+
+    it 'returns zero paths when no connection' do
+      result = client.trace_causal_chain(from: :slippery, to: :rain)
+      expect(result[:path_count]).to eq(0)
+    end
+  end
+
+  describe '#causal_intervention' do
+    before do
+      client.add_causal_edge(cause: :smoking, effect: :cancer, edge_type: :causes)
+      client.add_causal_edge(cause: :cancer, effect: :treatment, edge_type: :causes)
+    end
+
+    it 'returns success: true and lists downstream effects' do
+      result = client.causal_intervention(variable: :smoking, value: true)
+      expect(result[:success]).to be true
+      expect(result[:intervention]).to eq(:smoking)
+      downstream_vars = result[:downstream_effects].map { |e| e[:variable] }
+      expect(downstream_vars).to include(:cancer, :treatment)
+    end
+  end
+
+  describe '#find_confounders' do
+    before do
+      client.add_causal_edge(cause: :weather, effect: :rain, edge_type: :causes)
+      client.add_causal_edge(cause: :weather, effect: :cold, edge_type: :causes)
+    end
+
+    it 'identifies common ancestors as confounders' do
+      result = client.find_confounders(var_a: :rain, var_b: :cold)
+      expect(result[:success]).to be true
+      expect(result[:confounders]).to include(:weather)
+    end
+
+    it 'returns empty confounders for unrelated variables' do
+      result = client.find_confounders(var_a: :rain, var_b: :unrelated)
+      expect(result[:count]).to eq(0)
+    end
+  end
+
+  describe '#add_causal_evidence' do
+    it 'increments evidence on an existing edge' do
+      edge_result = client.add_causal_edge(cause: :rain, effect: :wet_grass, edge_type: :causes)
+      edge_id     = edge_result[:edge][:id]
+      result      = client.add_causal_evidence(edge_id: edge_id)
+      expect(result[:success]).to be true
+      expect(result[:evidence_count]).to eq(1)
+    end
+
+    it 'returns success: false for unknown edge_id' do
+      result = client.add_causal_evidence(edge_id: 'nonexistent-uuid')
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:edge_not_found)
+    end
+  end
+
+  describe '#update_causal_reasoning' do
+    it 'returns success: true with decayed and pruned counts' do
+      client.add_causal_edge(cause: :rain, effect: :wet_grass, edge_type: :causes)
+      result = client.update_causal_reasoning
+      expect(result[:success]).to be true
+      expect(result[:decayed]).to eq(1)
+      expect(result[:pruned]).to eq(0)
+    end
+  end
+
+  describe '#causal_reasoning_stats' do
+    it 'returns stats including variables and edges counts' do
+      client.add_causal_edge(cause: :rain, effect: :wet_grass, edge_type: :causes)
+      result = client.causal_reasoning_stats
+      expect(result[:success]).to be true
+      expect(result[:variables]).to eq(2)
+      expect(result[:edges]).to eq(1)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,24 @@
+# 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
+
+  module Extensions
+    module Helpers; end
+  end
+end
+
+require 'legion/extensions/causal_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,75 @@
+--- !ruby/object:Gem::Specification
+name: lex-causal-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: Causal inference engine for brain-modeled agentic AI — do-calculus and
+  causal graphs
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-causal-reasoning.gemspec
+- lib/legion/extensions/causal_reasoning.rb
+- lib/legion/extensions/causal_reasoning/client.rb
+- lib/legion/extensions/causal_reasoning/helpers/causal_edge.rb
+- lib/legion/extensions/causal_reasoning/helpers/causal_graph.rb
+- lib/legion/extensions/causal_reasoning/helpers/constants.rb
+- lib/legion/extensions/causal_reasoning/runners/causal_reasoning.rb
+- lib/legion/extensions/causal_reasoning/version.rb
+- spec/legion/extensions/causal_reasoning/client_spec.rb
+- spec/legion/extensions/causal_reasoning/helpers/causal_edge_spec.rb
+- spec/legion/extensions/causal_reasoning/helpers/causal_graph_spec.rb
+- spec/legion/extensions/causal_reasoning/runners/causal_reasoning_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-causal-reasoning
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-causal-reasoning
+  source_code_uri: https://github.com/LegionIO/lex-causal-reasoning
+  documentation_uri: https://github.com/LegionIO/lex-causal-reasoning
+  changelog_uri: https://github.com/LegionIO/lex-causal-reasoning
+  bug_tracker_uri: https://github.com/LegionIO/lex-causal-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 Causal Reasoning
+test_files: []