lex-cognitive-debugging 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2dea7a09ee184044d9ec2bd1ab8b225072b166960290e2e97ca97e2740f75875
+  data.tar.gz: 4a00f3fa6f9cbf962ac790d5a75c5f99cc46eb9bc43154d40d249521f30a4065
+SHA512:
+  metadata.gz: ec15e829ba922b803c848f85b0200feccc3526fef59afe1432de044e95a4f65761b76ae9e72950c254f3070962c17afbfde032c1dfa508c65ed9944cadfdf0b4
+  data.tar.gz: f1e966d6acad1e9777cfeaf4e9c9ffccfdce045768f49bf99dd808f6ea1cc6f80c2db998c7c5bbf559581c01a14499d9a603bf179ac4f910364b291155650344

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'
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Esity
+
+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,65 @@
+# lex-cognitive-debugging
+
+Self-debugging system for cognitive processes in LegionIO. Detects reasoning errors, traces their causal chain through cognitive phases, proposes corrective strategies, and tracks resolution effectiveness.
+
+## What It Does
+
+Cognitive debugging models the metacognitive capacity to catch and fix reasoning failures before they propagate into actions. An error is detected with a type and severity, then traced through a causal investigation (steps + root cause). One or more corrections are proposed using defined strategies, applied, and measured for effectiveness. The system tracks per-type error frequencies, per-phase detection rates, and per-strategy effectiveness averages — enabling ongoing quality assessment of the agent's own reasoning.
+
+Eight error types cover the common failure modes: inconsistency, circular logic, ungrounded claims, overconfidence, logical fallacies, missing evidence, false analogy, and confirmation bias. Seven correction strategies map to standard epistemic repair techniques: retrace, reframe, weaken_confidence, seek_evidence, decompose, analogize, and devil_advocate.
+
+## Usage
+
+```ruby
+client = Legion::Extensions::CognitiveDebugging::Client.new
+
+# Detect a reasoning error
+result = client.detect_error(
+  error_type: :overconfidence,
+  description: 'Predicted outcome with 0.95 confidence after only two data points',
+  severity: 0.7,
+  source_phase: :prediction_engine,
+  confidence_at_detection: 0.8
+)
+error_id = result[:error_id]
+
+# Trace the causal chain
+client.trace_error(
+  error_id: error_id,
+  steps: ['checked prediction log', 'found insufficient evidence base'],
+  root_cause: 'recency bias from last two successful predictions',
+  confidence: 0.75
+)
+
+# Propose and apply a correction
+correction = client.propose_correction(
+  error_id: error_id,
+  strategy: :weaken_confidence,
+  description: 'Reduce confidence floor until five+ data points available'
+)
+correction_id = correction[:correction_id]
+
+client.apply_correction(correction_id: correction_id)
+client.measure_correction(correction_id: correction_id, effectiveness: 0.8)
+client.resolve_error(error_id: error_id)
+
+# Analysis
+client.active_errors
+client.errors_by_type
+client.most_common_error_type
+client.most_effective_strategy
+client.correction_success_rate
+client.debugging_report
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-debugging.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_debugging/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-debugging'
+  spec.version       = Legion::Extensions::CognitiveDebugging::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Cognitive Debugging'
+  spec.description   = 'Self-debugging system for cognitive processes in LegionIO — detects reasoning errors, ' \
+                       'traces causal chains, and applies corrective strategies'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-debugging'
+  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-cognitive-debugging'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-cognitive-debugging'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-cognitive-debugging'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-cognitive-debugging/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-cognitive-debugging.gemspec Gemfile LICENSE README.md]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

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

data/lib/legion/extensions/cognitive_debugging/helpers/causal_trace.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveDebugging
+      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

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveDebugging
+      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

data/lib/legion/extensions/cognitive_debugging/helpers/correction.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveDebugging
+      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

data/lib/legion/extensions/cognitive_debugging/helpers/debugging_engine.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveDebugging
+      module Helpers
+        class DebuggingEngine
+          attr_reader :errors, :traces, :corrections
+
+          def initialize
+            @errors      = {}
+            @traces      = {}
+            @corrections = {}
+          end
+
+          def detect_error(error_type:, description:, severity:, source_phase:, confidence_at_detection:)
+            return nil unless Constants::ERROR_TYPES.include?(error_type)
+            return nil if @errors.size >= Constants::MAX_ERRORS
+
+            err = ReasoningError.new(
+              error_type:              error_type,
+              description:             description,
+              severity:                severity,
+              source_phase:            source_phase,
+              confidence_at_detection: confidence_at_detection
+            )
+            @errors[err.id] = err
+            err
+          end
+
+          def trace_error(error_id:, steps:, root_cause:, confidence:)
+            err = @errors[error_id]
+            return nil unless err
+            return nil if @traces.size >= Constants::MAX_TRACES
+
+            trace = CausalTrace.new(error_id: error_id, root_cause: root_cause, confidence: confidence)
+            steps.each { |s| trace.add_step!(phase: s.fetch(:phase), description: s.fetch(:description)) }
+            @traces[trace.id] = trace
+            err.trace!(trace.id)
+            trace
+          end
+
+          def propose_correction(error_id:, strategy:, description:)
+            err = @errors[error_id]
+            return nil unless err
+            return nil unless Constants::CORRECTION_STRATEGIES.include?(strategy)
+            return nil if @corrections.size >= Constants::MAX_CORRECTIONS
+
+            correction = Correction.new(error_id: error_id, strategy: strategy, description: description)
+            @corrections[correction.id] = correction
+            err.correct!(correction.id)
+            correction
+          end
+
+          def apply_correction(correction_id:)
+            correction = @corrections[correction_id]
+            return nil unless correction
+
+            correction.apply!
+          end
+
+          def measure_correction(correction_id:, effectiveness:)
+            correction = @corrections[correction_id]
+            return nil unless correction
+
+            correction.measure_effectiveness!(effectiveness)
+          end
+
+          def resolve_error(error_id:)
+            err = @errors[error_id]
+            return nil unless err
+
+            err.resolve!
+          end
+
+          def active_errors
+            @errors.values.select(&:active?)
+          end
+
+          def resolved_errors
+            @errors.values.select(&:resolved?)
+          end
+
+          def errors_by_type
+            @errors.values.group_by(&:error_type).transform_values(&:length)
+          end
+
+          def errors_by_phase
+            @errors.values.group_by(&:source_phase).transform_values(&:length)
+          end
+
+          def most_common_error_type
+            tally = errors_by_type
+            return nil if tally.empty?
+
+            tally.max_by { |_, count| count }&.first
+          end
+
+          def most_effective_strategy
+            applied = @corrections.values.reject { |c| c.effectiveness.nil? }
+            return nil if applied.empty?
+
+            by_strategy = applied.group_by(&:strategy)
+            best = by_strategy.max_by do |_, list|
+              scores = list.map(&:effectiveness)
+              scores.sum.round(10) / scores.size
+            end
+            best&.first
+          end
+
+          def error_rate_by_phase
+            errors_by_phase
+          end
+
+          def correction_success_rate
+            applied = @corrections.values.select(&:applied)
+            return 0.0 if applied.empty?
+
+            measured = applied.reject { |c| c.effectiveness.nil? }
+            return 0.0 if measured.empty?
+
+            effective_count = measured.count(&:effective?)
+            (effective_count.to_f / measured.size).round(10)
+          end
+
+          def debugging_report
+            {
+              total_errors:            @errors.size,
+              active_errors:           active_errors.size,
+              resolved_errors:         resolved_errors.size,
+              total_traces:            @traces.size,
+              total_corrections:       @corrections.size,
+              correction_success_rate: correction_success_rate,
+              most_common_error_type:  most_common_error_type,
+              most_effective_strategy: most_effective_strategy,
+              errors_by_type:          errors_by_type,
+              error_rate_by_phase:     error_rate_by_phase
+            }
+          end
+
+          def to_h
+            {
+              errors:      @errors.transform_values(&:to_h),
+              traces:      @traces.transform_values(&:to_h),
+              corrections: @corrections.transform_values(&:to_h)
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_debugging/helpers/reasoning_error.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveDebugging
+      module Helpers
+        class ReasoningError
+          attr_reader :id, :error_type, :description, :severity, :source_phase,
+                      :confidence_at_detection, :trace_ids, :correction_ids,
+                      :created_at, :resolved_at, :status
+
+          def initialize(error_type:, description:, severity:, source_phase:, confidence_at_detection:)
+            @id                       = SecureRandom.uuid
+            @error_type               = error_type
+            @description              = description
+            @severity                 = severity.clamp(0.0, 1.0).round(10)
+            @source_phase             = source_phase
+            @confidence_at_detection  = confidence_at_detection.clamp(0.0, 1.0).round(10)
+            @status                   = :detected
+            @trace_ids                = []
+            @correction_ids           = []
+            @created_at               = Time.now.utc
+            @resolved_at              = nil
+          end
+
+          def detect!
+            @status = :detected
+            self
+          end
+
+          def trace!(trace_id)
+            @trace_ids << trace_id
+            @status = :traced
+            self
+          end
+
+          def correct!(correction_id)
+            @correction_ids << correction_id
+            @status = :correcting
+            self
+          end
+
+          def resolve!
+            @status      = :resolved
+            @resolved_at = Time.now.utc
+            self
+          end
+
+          def mark_unresolvable!
+            @status      = :unresolvable
+            @resolved_at = Time.now.utc
+            self
+          end
+
+          def severe?
+            @severity >= 0.7
+          end
+
+          def resolved?
+            @status == :resolved
+          end
+
+          def active?
+            !%i[resolved unresolvable].include?(@status)
+          end
+
+          def severity_label
+            Constants.severity_label(@severity)
+          end
+
+          def to_h
+            {
+              id:                      @id,
+              error_type:              @error_type,
+              description:             @description,
+              severity:                @severity,
+              severity_label:          severity_label,
+              source_phase:            @source_phase,
+              confidence_at_detection: @confidence_at_detection,
+              status:                  @status,
+              trace_ids:               @trace_ids.dup,
+              correction_ids:          @correction_ids.dup,
+              created_at:              @created_at,
+              resolved_at:             @resolved_at
+            }
+          end
+        end
+      end
+    end
+  end
+end