lex-agentic-inference 0.1.0

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module Counterfactual
+          module Helpers
+            module Constants
+              MAX_SCENARIOS    = 200
+              MAX_HISTORY      = 300
+              MAX_ALTERNATIVES = 10
+
+              PLAUSIBILITY_THRESHOLD = 0.4
+              RELEVANCE_THRESHOLD    = 0.3
+
+              DEFAULT_REGRET  = 0.0
+              REGRET_DECAY    = 0.02
+              REGRET_CEILING  = 1.0
+              REGRET_FLOOR    = 0.0
+
+              UPWARD_WEIGHT   = 0.7
+              DOWNWARD_WEIGHT = 0.3
+
+              COUNTERFACTUAL_TYPES = %i[upward downward additive subtractive semifactual prefactual].freeze
+              MUTATION_TYPES       = %i[action inaction antecedent outcome context agent].freeze
+
+              EMOTIONAL_RESPONSES = {
+                upward:      :regret,
+                downward:    :relief,
+                semifactual: :acceptance,
+                prefactual:  :anxiety
+              }.freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/inference/counterfactual/helpers/counterfactual_engine.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module Counterfactual
+          module Helpers
+            class CounterfactualEngine
+              include Constants
+
+              attr_reader :scenarios
+
+              def initialize
+                @scenarios = {}
+              end
+
+              def generate(actual_outcome:, counterfactual_outcome:, antecedent:,
+                           scenario_type:, mutation_type:, domain:, plausibility:,
+                           regret_magnitude: 0.5)
+                prune_if_needed
+                scenario = Scenario.new(
+                  scenario_type:          scenario_type,
+                  mutation_type:          mutation_type,
+                  actual_outcome:         actual_outcome,
+                  counterfactual_outcome: counterfactual_outcome,
+                  antecedent:             antecedent,
+                  domain:                 domain,
+                  plausibility:           plausibility,
+                  regret_magnitude:       regret_magnitude
+                )
+                @scenarios[scenario.id] = scenario
+                scenario
+              end
+
+              def generate_alternatives(actual_outcome:, domain:)
+                alternatives = []
+                mutation_samples = MUTATION_TYPES.first(MAX_ALTERNATIVES)
+
+                mutation_samples.each_with_index do |mutation, idx|
+                  type = idx.even? ? :upward : :downward
+                  plausibility = (0.8 - (idx * 0.1)).clamp(PLAUSIBILITY_THRESHOLD, 1.0)
+
+                  scenario = generate(
+                    actual_outcome:         actual_outcome,
+                    counterfactual_outcome: "alternative_#{mutation}_#{idx}",
+                    antecedent:             "#{mutation}_variation_#{idx}",
+                    scenario_type:          type,
+                    mutation_type:          mutation,
+                    domain:                 domain,
+                    plausibility:           plausibility,
+                    regret_magnitude:       0.5
+                  )
+                  alternatives << scenario
+                end
+
+                alternatives
+              end
+
+              def resolve(scenario_id:, lesson:)
+                scenario = @scenarios[scenario_id]
+                return nil unless scenario
+
+                scenario.resolve(lesson: lesson)
+                scenario
+              end
+
+              def compute_regret(scenario_id:)
+                scenario = @scenarios[scenario_id]
+                return 0.0 unless scenario
+
+                if scenario.upward?
+                  scenario.regret_magnitude * UPWARD_WEIGHT * scenario.plausibility
+                elsif scenario.downward?
+                  -(scenario.regret_magnitude * DOWNWARD_WEIGHT * scenario.plausibility)
+                else
+                  0.0
+                end
+              end
+
+              def net_regret
+                unresolved.sum(0.0) { |s| compute_regret(scenario_id: s.id) }
+              end
+
+              def domain_regret(domain:)
+                by_domain(domain: domain).reject(&:resolved).sum(0.0) { |s| compute_regret(scenario_id: s.id) }
+              end
+
+              def lessons_learned
+                @scenarios.values.select { |s| s.resolved && s.lesson }
+              end
+
+              def regret_decay
+                unresolved.each do |scenario|
+                  new_magnitude = (scenario.regret_magnitude - REGRET_DECAY).clamp(REGRET_FLOOR, REGRET_CEILING)
+                  scenario.instance_variable_set(:@regret_magnitude, new_magnitude)
+                  scenario.instance_variable_set(:@emotional_valence, recompute_valence(scenario))
+                end
+              end
+
+              def by_type(type:)
+                @scenarios.values.select { |s| s.scenario_type == type }
+              end
+
+              def by_domain(domain:)
+                @scenarios.values.select { |s| s.domain == domain }
+              end
+
+              def unresolved
+                @scenarios.values.reject(&:resolved)
+              end
+
+              def recent(count:)
+                @scenarios.values.sort_by(&:created_at).last(count)
+              end
+
+              def to_h
+                {
+                  total:         @scenarios.size,
+                  unresolved:    unresolved.size,
+                  resolved:      lessons_learned.size,
+                  net_regret:    net_regret.round(4),
+                  by_type:       type_summary,
+                  lessons_count: lessons_learned.size
+                }
+              end
+
+              private
+
+              def prune_if_needed
+                return unless @scenarios.size >= MAX_SCENARIOS
+
+                oldest = @scenarios.values.min_by(&:created_at)
+                @scenarios.delete(oldest.id) if oldest
+              end
+
+              def type_summary
+                COUNTERFACTUAL_TYPES.to_h { |type| [type, @scenarios.values.count { |s| s.scenario_type == type }] }
+              end
+
+              def recompute_valence(scenario)
+                case scenario.scenario_type
+                when :upward     then -(scenario.regret_magnitude * UPWARD_WEIGHT)
+                when :downward   then scenario.regret_magnitude * DOWNWARD_WEIGHT
+                when :prefactual then -0.2
+                else 0.0
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/inference/counterfactual/helpers/scenario.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module Counterfactual
+          module Helpers
+            class Scenario
+              include Constants
+
+              attr_reader :id, :scenario_type, :mutation_type,
+                          :actual_outcome, :counterfactual_outcome,
+                          :antecedent, :domain, :plausibility,
+                          :emotional_valence, :regret_magnitude,
+                          :lesson, :resolved, :created_at, :resolved_at
+
+              def initialize(scenario_type:, mutation_type:, actual_outcome:,
+                             counterfactual_outcome:, antecedent:, domain:,
+                             plausibility:, regret_magnitude: 0.5)
+                @id = SecureRandom.uuid
+                @scenario_type          = scenario_type
+                @mutation_type          = mutation_type
+                @actual_outcome         = actual_outcome
+                @counterfactual_outcome = counterfactual_outcome
+                @antecedent             = antecedent
+                @domain                 = domain
+                @plausibility           = plausibility.to_f.clamp(0.0, 1.0)
+                @regret_magnitude       = regret_magnitude.to_f.clamp(0.0, 1.0)
+                @emotional_valence      = compute_emotional_valence
+                @lesson                 = nil
+                @resolved               = false
+                @created_at             = Time.now.utc
+                @resolved_at            = nil
+              end
+
+              def upward?
+                @scenario_type == :upward
+              end
+
+              def downward?
+                @scenario_type == :downward
+              end
+
+              def prefactual?
+                @scenario_type == :prefactual
+              end
+
+              def emotional_response
+                EMOTIONAL_RESPONSES.fetch(@scenario_type, :neutral)
+              end
+
+              def resolve(lesson:)
+                @lesson      = lesson
+                @resolved    = true
+                @resolved_at = Time.now.utc
+                self
+              end
+
+              def to_h
+                {
+                  id:                     @id,
+                  scenario_type:          @scenario_type,
+                  mutation_type:          @mutation_type,
+                  actual_outcome:         @actual_outcome,
+                  counterfactual_outcome: @counterfactual_outcome,
+                  antecedent:             @antecedent,
+                  domain:                 @domain,
+                  plausibility:           @plausibility,
+                  emotional_valence:      @emotional_valence,
+                  regret_magnitude:       @regret_magnitude,
+                  emotional_response:     emotional_response,
+                  lesson:                 @lesson,
+                  resolved:               @resolved,
+                  created_at:             @created_at,
+                  resolved_at:            @resolved_at
+                }
+              end
+
+              private
+
+              def compute_emotional_valence
+                case @scenario_type
+                when :upward     then -(@regret_magnitude * UPWARD_WEIGHT)
+                when :downward   then @regret_magnitude * DOWNWARD_WEIGHT
+                when :prefactual then -0.2
+                else 0.0
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module Counterfactual
+          module Runners
+            module Counterfactual
+              include Helpers::Constants
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def imagine_counterfactual(actual_outcome:, counterfactual_outcome:, antecedent:,
+                                         scenario_type:, mutation_type:, domain:, plausibility:, **)
+                unless COUNTERFACTUAL_TYPES.include?(scenario_type)
+                  return { success: false, error: :invalid_scenario_type,
+                           valid_types: COUNTERFACTUAL_TYPES }
+                end
+
+                unless MUTATION_TYPES.include?(mutation_type)
+                  return { success: false, error: :invalid_mutation_type,
+                           valid_types: MUTATION_TYPES }
+                end
+
+                scenario = engine.generate(
+                  actual_outcome:         actual_outcome,
+                  counterfactual_outcome: counterfactual_outcome,
+                  antecedent:             antecedent,
+                  scenario_type:          scenario_type,
+                  mutation_type:          mutation_type,
+                  domain:                 domain,
+                  plausibility:           plausibility
+                )
+
+                Legion::Logging.debug "[counterfactual] imagined: type=#{scenario_type} " \
+                                      "domain=#{domain} id=#{scenario.id[0..7]}"
+
+                { success: true, scenario: scenario.to_h }
+              end
+
+              def generate_alternatives(actual_outcome:, domain:, **)
+                alternatives = engine.generate_alternatives(actual_outcome: actual_outcome, domain: domain)
+                Legion::Logging.debug "[counterfactual] generated #{alternatives.size} alternatives for domain=#{domain}"
+                { success: true, alternatives: alternatives.map(&:to_h), count: alternatives.size }
+              end
+
+              def resolve_counterfactual(scenario_id:, lesson:, **)
+                scenario = engine.resolve(scenario_id: scenario_id, lesson: lesson)
+                if scenario
+                  Legion::Logging.info "[counterfactual] resolved: id=#{scenario_id[0..7]} lesson=#{lesson[0..40]}"
+                  { success: true, scenario: scenario.to_h }
+                else
+                  Legion::Logging.debug "[counterfactual] resolve failed: id=#{scenario_id[0..7]} not found"
+                  { success: false, reason: :not_found }
+                end
+              end
+
+              def compute_regret(scenario_id:, **)
+                regret = engine.compute_regret(scenario_id: scenario_id)
+                Legion::Logging.debug "[counterfactual] regret: id=#{scenario_id[0..7]} value=#{regret.round(4)}"
+                { success: true, scenario_id: scenario_id, regret: regret }
+              end
+
+              def net_regret_level(**)
+                net = engine.net_regret
+                Legion::Logging.debug "[counterfactual] net_regret=#{net.round(4)}"
+                { success: true, net_regret: net }
+              end
+
+              def domain_regret(domain:, **)
+                regret = engine.domain_regret(domain: domain)
+                Legion::Logging.debug "[counterfactual] domain_regret: domain=#{domain} value=#{regret.round(4)}"
+                { success: true, domain: domain, regret: regret }
+              end
+
+              def lessons_learned(**)
+                lessons = engine.lessons_learned
+                Legion::Logging.debug "[counterfactual] lessons_learned: count=#{lessons.size}"
+                { success: true, lessons: lessons.map(&:to_h), count: lessons.size }
+              end
+
+              def update_counterfactual(**)
+                engine.regret_decay
+                Legion::Logging.debug '[counterfactual] regret decay applied'
+                { success: true, action: :regret_decay }
+              end
+
+              def counterfactual_stats(**)
+                stats = engine.to_h
+                Legion::Logging.debug "[counterfactual] stats: total=#{stats[:total]} unresolved=#{stats[:unresolved]}"
+                { success: true, stats: stats }
+              end
+
+              private
+
+              def engine
+                @engine ||= Helpers::CounterfactualEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'counterfactual/version'
+require_relative 'counterfactual/helpers/constants'
+require_relative 'counterfactual/helpers/scenario'
+require_relative 'counterfactual/helpers/counterfactual_engine'
+require_relative 'counterfactual/runners/counterfactual'
+require_relative 'counterfactual/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module Counterfactual
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/inference/debugging/helpers/constants'
+require 'legion/extensions/agentic/inference/debugging/helpers/reasoning_error'
+require 'legion/extensions/agentic/inference/debugging/helpers/causal_trace'
+require 'legion/extensions/agentic/inference/debugging/helpers/correction'
+require 'legion/extensions/agentic/inference/debugging/helpers/debugging_engine'
+require 'legion/extensions/agentic/inference/debugging/runners/cognitive_debugging'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module Debugging
+          class Client
+            include Runners::CognitiveDebugging
+
+            def initialize(engine: nil, **)
+              @engine = engine || Helpers::DebuggingEngine.new
+            end
+
+            private
+
+            attr_reader :engine
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/inference/debugging/helpers/causal_trace.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module Debugging
+          module Helpers
+            class CausalTrace
+              attr_reader :id, :error_id, :steps, :root_cause, :confidence
+
+              def initialize(error_id:, root_cause:, confidence:)
+                @id         = SecureRandom.uuid
+                @error_id   = error_id
+                @root_cause = root_cause
+                @confidence = confidence.clamp(0.0, 1.0).round(10)
+                @steps      = []
+              end
+
+              def add_step!(phase:, description:)
+                @steps << {
+                  phase:       phase,
+                  description: description,
+                  timestamp:   Time.now.utc
+                }
+                self
+              end
+
+              def depth
+                @steps.size
+              end
+
+              def to_h
+                {
+                  id:         @id,
+                  error_id:   @error_id,
+                  steps:      @steps.map(&:dup),
+                  root_cause: @root_cause,
+                  confidence: @confidence,
+                  depth:      depth
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module Debugging
+          module Helpers
+            module Constants
+              MAX_ERRORS      = 300
+              MAX_TRACES      = 500
+              MAX_CORRECTIONS = 200
+
+              ERROR_TYPES = %i[
+                inconsistency
+                circular_logic
+                ungrounded_claim
+                overconfidence
+                logical_fallacy
+                missing_evidence
+                false_analogy
+                confirmation_bias
+              ].freeze
+
+              CORRECTION_STRATEGIES = %i[
+                retrace
+                reframe
+                weaken_confidence
+                seek_evidence
+                decompose
+                analogize
+                devil_advocate
+              ].freeze
+
+              # Range-based severity labels: 0.0..1.0 -> label
+              SEVERITY_LABELS = [
+                { range: (0.0...0.2), label: :trivial  },
+                { range: (0.2...0.4), label: :minor    },
+                { range: (0.4...0.6), label: :moderate },
+                { range: (0.6...0.8), label: :major    },
+                { range: (0.8..1.0),  label: :critical }
+              ].freeze
+
+              STATUS_LABELS = %i[detected traced correcting resolved unresolvable].freeze
+
+              module_function
+
+              def severity_label(severity)
+                entry = SEVERITY_LABELS.find { |e| e[:range].cover?(severity) }
+                entry ? entry[:label] : :critical
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/inference/debugging/helpers/correction.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module Debugging
+          module Helpers
+            class Correction
+              attr_reader :id, :error_id, :strategy, :description, :applied, :effectiveness
+
+              def initialize(error_id:, strategy:, description:)
+                @id            = SecureRandom.uuid
+                @error_id      = error_id
+                @strategy      = strategy
+                @description   = description
+                @applied       = false
+                @effectiveness = nil
+              end
+
+              def apply!
+                @applied = true
+                self
+              end
+
+              def measure_effectiveness!(score)
+                @effectiveness = score.clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def effective?
+                return false if @effectiveness.nil?
+
+                @effectiveness >= 0.6
+              end
+
+              def to_h
+                {
+                  id:            @id,
+                  error_id:      @error_id,
+                  strategy:      @strategy,
+                  description:   @description,
+                  applied:       @applied,
+                  effectiveness: @effectiveness,
+                  effective:     effective?
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end