lex-agentic-inference 0.1.0

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

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

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

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

data/lib/legion/extensions/agentic/inference/debugging/runners/cognitive_debugging.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module Debugging
+          module Runners
+            module CognitiveDebugging
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def detect_error(error_type:, description:, severity:, source_phase:, confidence_at_detection: 0.5, **)
+                unless Helpers::Constants::ERROR_TYPES.include?(error_type)
+                  Legion::Logging.debug "[cognitive_debugging] detect_error: invalid error_type=#{error_type}"
+                  return { success: false, error: :invalid_error_type, valid: Helpers::Constants::ERROR_TYPES }
+                end
+
+                err = engine.detect_error(
+                  error_type:              error_type,
+                  description:             description,
+                  severity:                severity,
+                  source_phase:            source_phase,
+                  confidence_at_detection: confidence_at_detection
+                )
+
+                if err
+                  Legion::Logging.info "[cognitive_debugging] error detected: id=#{err.id[0..7]} type=#{error_type} " \
+                                       "phase=#{source_phase} severity=#{err.severity_label}"
+                  { success: true, error_id: err.id, error_type: error_type, severity_label: err.severity_label }
+                else
+                  Legion::Logging.warn '[cognitive_debugging] detect_error: engine returned nil (cap reached?)'
+                  { success: false, error: :cap_reached }
+                end
+              end
+
+              def trace_error(error_id:, steps:, root_cause:, confidence: 0.5, **)
+                trace = engine.trace_error(
+                  error_id:   error_id,
+                  steps:      steps,
+                  root_cause: root_cause,
+                  confidence: confidence
+                )
+
+                if trace
+                  Legion::Logging.info "[cognitive_debugging] error traced: error_id=#{error_id[0..7]} " \
+                                       "trace_id=#{trace.id[0..7]} depth=#{trace.depth} root_cause=#{root_cause}"
+                  { success: true, trace_id: trace.id, depth: trace.depth, root_cause: root_cause }
+                else
+                  Legion::Logging.debug "[cognitive_debugging] trace_error: error_id=#{error_id[0..7]} not found or cap"
+                  { success: false, error: :not_found_or_cap }
+                end
+              end
+
+              def propose_correction(error_id:, strategy:, description:, **)
+                unless Helpers::Constants::CORRECTION_STRATEGIES.include?(strategy)
+                  Legion::Logging.debug "[cognitive_debugging] propose_correction: invalid strategy=#{strategy}"
+                  return { success: false, error: :invalid_strategy, valid: Helpers::Constants::CORRECTION_STRATEGIES }
+                end
+
+                correction = engine.propose_correction(error_id: error_id, strategy: strategy, description: description)
+
+                if correction
+                  Legion::Logging.info "[cognitive_debugging] correction proposed: error_id=#{error_id[0..7]} " \
+                                       "correction_id=#{correction.id[0..7]} strategy=#{strategy}"
+                  { success: true, correction_id: correction.id, strategy: strategy }
+                else
+                  Legion::Logging.debug "[cognitive_debugging] propose_correction: error_id=#{error_id[0..7]} not found"
+                  { success: false, error: :not_found }
+                end
+              end
+
+              def apply_correction(correction_id:, **)
+                correction = engine.apply_correction(correction_id: correction_id)
+
+                if correction
+                  Legion::Logging.info "[cognitive_debugging] correction applied: id=#{correction_id[0..7]}"
+                  { success: true, correction_id: correction_id, applied: true }
+                else
+                  Legion::Logging.debug "[cognitive_debugging] apply_correction: id=#{correction_id[0..7]} not found"
+                  { success: false, error: :not_found }
+                end
+              end
+
+              def measure_correction(correction_id:, effectiveness:, **)
+                correction = engine.measure_correction(correction_id: correction_id, effectiveness: effectiveness)
+
+                if correction
+                  Legion::Logging.info "[cognitive_debugging] correction measured: id=#{correction_id[0..7]} " \
+                                       "effectiveness=#{correction.effectiveness} effective=#{correction.effective?}"
+                  { success: true, correction_id: correction_id, effectiveness: correction.effectiveness,
+                    effective: correction.effective? }
+                else
+                  Legion::Logging.debug "[cognitive_debugging] measure_correction: id=#{correction_id[0..7]} not found"
+                  { success: false, error: :not_found }
+                end
+              end
+
+              def resolve_error(error_id:, **)
+                err = engine.resolve_error(error_id: error_id)
+
+                if err
+                  Legion::Logging.info "[cognitive_debugging] error resolved: id=#{error_id[0..7]}"
+                  { success: true, error_id: error_id, resolved: true }
+                else
+                  Legion::Logging.debug "[cognitive_debugging] resolve_error: id=#{error_id[0..7]} not found"
+                  { success: false, error: :not_found }
+                end
+              end
+
+              def active_errors(**)
+                errors = engine.active_errors
+                Legion::Logging.debug "[cognitive_debugging] active_errors: count=#{errors.size}"
+                { success: true, errors: errors.map(&:to_h), count: errors.size }
+              end
+
+              def resolved_errors(**)
+                errors = engine.resolved_errors
+                Legion::Logging.debug "[cognitive_debugging] resolved_errors: count=#{errors.size}"
+                { success: true, errors: errors.map(&:to_h), count: errors.size }
+              end
+
+              def errors_by_type(**)
+                tally = engine.errors_by_type
+                Legion::Logging.debug "[cognitive_debugging] errors_by_type: types=#{tally.keys.join(',')}"
+                { success: true, tally: tally }
+              end
+
+              def errors_by_phase(**)
+                tally = engine.errors_by_phase
+                Legion::Logging.debug "[cognitive_debugging] errors_by_phase: phases=#{tally.keys.join(',')}"
+                { success: true, tally: tally }
+              end
+
+              def most_common_error_type(**)
+                type = engine.most_common_error_type
+                Legion::Logging.debug "[cognitive_debugging] most_common_error_type: type=#{type}"
+                { success: true, error_type: type }
+              end
+
+              def most_effective_strategy(**)
+                strategy = engine.most_effective_strategy
+                Legion::Logging.debug "[cognitive_debugging] most_effective_strategy: strategy=#{strategy}"
+                { success: true, strategy: strategy }
+              end
+
+              def correction_success_rate(**)
+                rate = engine.correction_success_rate
+                Legion::Logging.debug "[cognitive_debugging] correction_success_rate: rate=#{rate}"
+                { success: true, rate: rate }
+              end
+
+              def debugging_report(**)
+                report = engine.debugging_report
+                Legion::Logging.info "[cognitive_debugging] debugging_report: total_errors=#{report[:total_errors]} " \
+                                     "active=#{report[:active_errors]}"
+                { success: true, report: report }
+              end
+
+              def snapshot(**)
+                data = engine.to_h
+                Legion::Logging.debug "[cognitive_debugging] snapshot: errors=#{data[:errors].size} " \
+                                      "traces=#{data[:traces].size} corrections=#{data[:corrections].size}"
+                { success: true, snapshot: data }
+              end
+
+              private
+
+              def engine
+                @engine ||= Helpers::DebuggingEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/inference/debugging/version'
+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'
+require 'legion/extensions/agentic/inference/debugging/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module Debugging
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/inference/enactive_cognition/helpers/sensorimotor_loop'
+require 'legion/extensions/agentic/inference/enactive_cognition/helpers/enaction_engine'
+require 'legion/extensions/agentic/inference/enactive_cognition/runners/enactive_cognition'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module EnactiveCognition
+          class Client
+            include Runners::EnactiveCognition
+
+            def initialize(**)
+              @enaction_engine = Helpers::EnactionEngine.new
+            end
+
+            private
+
+            attr_reader :enaction_engine
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/inference/enactive_cognition/helpers/enaction_engine.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module EnactiveCognition
+          module Helpers
+            class EnactionEngine
+              attr_reader :couplings
+
+              def initialize
+                @couplings = {}
+              end
+
+              def create_coupling(action:, perception:, domain:, loop_type: :sensorimotor)
+                prune_to_limit
+
+                loop = SensorimotorLoop.new(
+                  action:     action,
+                  perception: perception,
+                  domain:     domain,
+                  loop_type:  loop_type
+                )
+                @couplings[loop.id] = loop
+                loop
+              end
+
+              def execute_action(coupling_id:, actual_perception:)
+                loop = @couplings[coupling_id]
+                return { success: false, reason: :not_found } unless loop
+
+                result = loop.execute!(actual_perception: actual_perception)
+                {
+                  success:             true,
+                  coupling_id:         coupling_id,
+                  match:               result[:match],
+                  coupling_strength:   result[:coupling_strength],
+                  prediction_accuracy: result[:prediction_accuracy],
+                  coupling_label:      loop.coupling_label
+                }
+              end
+
+              def adapt_coupling(coupling_id:, new_perception:)
+                loop = @couplings[coupling_id]
+                return { success: false, reason: :not_found } unless loop
+
+                loop.adapt_perception!(new_perception: new_perception)
+                { success: true, coupling_id: coupling_id, new_perception: new_perception }
+              end
+
+              def find_action_for(perception:)
+                best = @couplings.values
+                                 .select(&:coupled?)
+                                 .select { |lp| lp.perception.to_s == perception.to_s }
+                                 .max_by(&:coupling_strength)
+                return nil unless best
+
+                best
+              end
+
+              def coupled_loops
+                @couplings.values.select(&:coupled?)
+              end
+
+              def by_domain(domain:)
+                @couplings.values.select { |lp| lp.domain.to_s == domain.to_s }
+              end
+
+              def by_type(loop_type:)
+                @couplings.values.select { |lp| lp.loop_type == loop_type }
+              end
+
+              def strongest_couplings(limit: 5)
+                @couplings.values.sort_by { |lp| -lp.coupling_strength }.first(limit)
+              end
+
+              def overall_coupling
+                return 0.0 if @couplings.empty?
+
+                total = @couplings.values.sum(&:coupling_strength)
+                total / @couplings.size
+              end
+
+              def decay_all
+                @couplings.each_value(&:decay!)
+              end
+
+              def prune_decoupled
+                @couplings.delete_if { |_id, lp| lp.coupling_strength < SensorimotorLoop::COUPLING_FLOOR + 0.05 }
+              end
+
+              def count
+                @couplings.size
+              end
+
+              def to_h
+                {
+                  coupling_count:   @couplings.size,
+                  coupled_count:    coupled_loops.size,
+                  overall_coupling: overall_coupling.round(4),
+                  strongest:        strongest_couplings(limit: 3).map(&:to_h)
+                }
+              end
+
+              private
+
+              def prune_to_limit
+                return unless @couplings.size >= SensorimotorLoop::MAX_COUPLINGS
+
+                weakest = @couplings.values.sort_by(&:coupling_strength).first(10)
+                weakest.each { |lp| @couplings.delete(lp.id) }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end