lex-agentic-inference 0.1.0

data/lib/legion/extensions/agentic/inference/causal_attribution/helpers/attribution_engine.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module CausalAttribution
+          module Helpers
+            class AttributionEngine
+              def initialize
+                @attributions = {}
+                @history      = []
+              end
+
+              def create_attribution(event:, outcome:, domain:, locus:, stability:, controllability:,
+                                     confidence: Attribution::DEFAULT_CONFIDENCE)
+                trim_if_needed
+                attribution = Attribution.new(
+                  event:           event,
+                  outcome:         outcome,
+                  domain:          domain,
+                  locus:           locus,
+                  stability:       stability,
+                  controllability: controllability,
+                  confidence:      confidence
+                )
+                @attributions[attribution.id] = attribution
+                attribution
+              end
+
+              def reattribute(attribution_id:, locus: nil, stability: nil, controllability: nil)
+                attr = @attributions[attribution_id]
+                return { found: false, attribution_id: attribution_id } unless attr
+
+                new_locus           = locus           || attr.locus
+                new_stability       = stability       || attr.stability
+                new_controllability = controllability || attr.controllability
+
+                updated = Attribution.new(
+                  event:           attr.event,
+                  outcome:         attr.outcome,
+                  domain:          attr.domain,
+                  locus:           new_locus,
+                  stability:       new_stability,
+                  controllability: new_controllability,
+                  confidence:      attr.confidence
+                )
+                @history << attr.to_h if @history.size < Attribution::MAX_HISTORY
+                @attributions[attribution_id] = updated
+                updated
+              end
+
+              def by_pattern(locus: nil, stability: nil, controllability: nil)
+                @attributions.values.select do |a|
+                  (locus.nil? || a.locus == locus) &&
+                    (stability.nil?       || a.stability == stability) &&
+                    (controllability.nil? || a.controllability == controllability)
+                end
+              end
+
+              def by_domain(domain:)
+                @attributions.values.select { |a| a.domain == domain }
+              end
+
+              def by_outcome(outcome:)
+                @attributions.values.select { |a| a.outcome == outcome }
+              end
+
+              def attribution_bias
+                return { bias: :none, detail: 'no attributions' } if @attributions.empty?
+
+                all     = @attributions.values
+                total   = all.size.to_f
+                locus   = bias_ratio(all, :locus, :external, total)
+                stab    = bias_ratio(all, :stability, :stable, total)
+                control = bias_ratio(all, :controllability, :uncontrollable, total)
+
+                failures = all.select { |a| a.outcome == :failure }
+                external_failure_ratio = failures.empty? ? 0.0 : failures.count(&:external?).to_f / failures.size
+
+                {
+                  external_locus_ratio:       locus.round(3),
+                  stable_ratio:               stab.round(3),
+                  uncontrollable_ratio:       control.round(3),
+                  external_failure_ratio:     external_failure_ratio.round(3),
+                  self_serving_bias_detected: external_failure_ratio > 0.6,
+                  total_attributions:         @attributions.size
+                }
+              end
+
+              def emotional_profile
+                counts = Hash.new(0)
+                @attributions.each_value { |a| counts[a.emotional_response] += 1 if a.emotional_response }
+                total = counts.values.sum.to_f
+                profile = counts.transform_values { |v| (v / total).round(3) }
+                dominant = counts.max_by { |_, v| v }&.first
+                { distribution: profile, dominant: dominant, total: counts.values.sum }
+              end
+
+              def most_common_pattern
+                return { pattern: nil, count: 0 } if @attributions.empty?
+
+                grouped = @attributions.values.group_by(&:pattern)
+                best    = grouped.max_by { |_, attrs| attrs.size }
+                { pattern: best[0], count: best[1].size }
+              end
+
+              def decay_all
+                decayed = 0
+                @attributions.each_value do |a|
+                  new_conf = (a.confidence - Attribution::DECAY_RATE).clamp(
+                    Attribution::CONFIDENCE_FLOOR, Attribution::CONFIDENCE_CEILING
+                  )
+                  a.instance_variable_set(:@confidence, new_conf)
+                  decayed += 1
+                end
+                decayed
+              end
+
+              def count
+                @attributions.size
+              end
+
+              def to_h
+                {
+                  total_attributions: @attributions.size,
+                  history_size:       @history.size,
+                  outcome_counts:     outcome_counts,
+                  locus_counts:       locus_counts
+                }
+              end
+
+              private
+
+              def trim_if_needed
+                return unless @attributions.size >= Attribution::MAX_ATTRIBUTIONS
+
+                oldest_key = @attributions.min_by { |_, a| a.created_at }&.first
+                @attributions.delete(oldest_key)
+              end
+
+              def bias_ratio(all, dimension, value, total)
+                all.count { |a| a.public_send(dimension) == value } / total
+              end
+
+              def outcome_counts
+                @attributions.values.group_by(&:outcome).transform_values(&:size)
+              end
+
+              def locus_counts
+                @attributions.values.group_by(&:locus).transform_values(&:size)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/inference/causal_attribution/runners/causal_attribution.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module CausalAttribution
+          module Runners
+            module CausalAttribution
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def create_causal_attribution(event:, outcome:, domain:, locus:, stability:, controllability:,
+                                            confidence: nil, **)
+                conf = (confidence || Helpers::Attribution::DEFAULT_CONFIDENCE)
+                       .clamp(Helpers::Attribution::CONFIDENCE_FLOOR, Helpers::Attribution::CONFIDENCE_CEILING)
+                attr = engine.create_attribution(
+                  event:           event,
+                  outcome:         outcome,
+                  domain:          domain,
+                  locus:           locus.to_sym,
+                  stability:       stability.to_sym,
+                  controllability: controllability.to_sym,
+                  confidence:      conf
+                )
+                Legion::Logging.info "[causal_attribution] create id=#{attr.id} event=#{event} " \
+                                     "outcome=#{outcome} locus=#{locus} emotion=#{attr.emotional_response}"
+                { success: true, attribution: attr.to_h }
+              end
+
+              def reattribute_cause(attribution_id:, locus: nil, stability: nil, controllability: nil, **)
+                result = engine.reattribute(
+                  attribution_id:  attribution_id,
+                  locus:           locus&.to_sym,
+                  stability:       stability&.to_sym,
+                  controllability: controllability&.to_sym
+                )
+                if result.is_a?(Hash) && result[:found] == false
+                  Legion::Logging.warn "[causal_attribution] reattribute not_found id=#{attribution_id}"
+                  return { success: false, attribution_id: attribution_id, found: false }
+                end
+
+                Legion::Logging.debug "[causal_attribution] reattribute id=#{attribution_id} " \
+                                      "locus=#{result.locus} emotion=#{result.emotional_response}"
+                { success: true, attribution: result.to_h }
+              end
+
+              def attributions_by_pattern(locus: nil, stability: nil, controllability: nil, **)
+                results = engine.by_pattern(
+                  locus:           locus&.to_sym,
+                  stability:       stability&.to_sym,
+                  controllability: controllability&.to_sym
+                )
+                Legion::Logging.debug "[causal_attribution] by_pattern count=#{results.size}"
+                { success: true, attributions: results.map(&:to_h), count: results.size }
+              end
+
+              def domain_attributions(domain:, **)
+                results = engine.by_domain(domain: domain.to_sym)
+                Legion::Logging.debug "[causal_attribution] by_domain domain=#{domain} count=#{results.size}"
+                { success: true, attributions: results.map(&:to_h), count: results.size }
+              end
+
+              def outcome_attributions(outcome:, **)
+                results = engine.by_outcome(outcome: outcome.to_sym)
+                Legion::Logging.debug "[causal_attribution] by_outcome outcome=#{outcome} count=#{results.size}"
+                { success: true, attributions: results.map(&:to_h), count: results.size }
+              end
+
+              def attribution_bias_assessment(**)
+                bias = engine.attribution_bias
+                Legion::Logging.debug "[causal_attribution] bias_assessment self_serving=#{bias[:self_serving_bias_detected]}"
+                { success: true, bias: bias }
+              end
+
+              def emotional_attribution_profile(**)
+                profile = engine.emotional_profile
+                Legion::Logging.debug "[causal_attribution] emotional_profile dominant=#{profile[:dominant]} total=#{profile[:total]}"
+                { success: true, profile: profile }
+              end
+
+              def most_common_attribution(**)
+                result = engine.most_common_pattern
+                Legion::Logging.debug "[causal_attribution] most_common pattern=#{result[:pattern].inspect} count=#{result[:count]}"
+                { success: true, pattern: result[:pattern], count: result[:count] }
+              end
+
+              def update_causal_attribution(**)
+                decayed = engine.decay_all
+                Legion::Logging.debug "[causal_attribution] decay cycle entries=#{decayed}"
+                { success: true, decayed: decayed }
+              end
+
+              def causal_attribution_stats(**)
+                stats = engine.to_h
+                Legion::Logging.debug "[causal_attribution] stats total=#{stats[:total_attributions]}"
+                { success: true, stats: stats }
+              end
+
+              private
+
+              def engine
+                @engine ||= Helpers::AttributionEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/inference/causal_attribution/version'
+require 'legion/extensions/agentic/inference/causal_attribution/helpers/attribution'
+require 'legion/extensions/agentic/inference/causal_attribution/helpers/attribution_engine'
+require 'legion/extensions/agentic/inference/causal_attribution/runners/causal_attribution'
+require 'legion/extensions/agentic/inference/causal_attribution/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module CausalAttribution
+        end
+      end
+    end
+  end
+end

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

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

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

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

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

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

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

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