agentic-qe 3.7.21 → 3.8.0

package/dist/coordination/reasoning-qec.d.ts

@@ -0,0 +1,315 @@
+/**
+ * Multi-Path Consensus Reasoning Validator - Task 4.5
+ *
+ * Applies error correction to AI reasoning using three independent paths.
+ * Generates multiple independent reasoning chains for critical decisions,
+ * extracts syndrome locations (disagreements between paths), and applies
+ * confidence-weighted voting to produce a high-confidence result.
+ *
+ * Use cases:
+ *   - Test generation validation
+ *   - Security audit consensus
+ *   - Defect triage decisions
+ *
+ * TypeScript implementation (no native package exists for reasoning QEC —
+ * consensus logic doesn't benefit from native computation).
+ *
+ * @module coordination/reasoning-qec
+ * @see docs/research/ruvector-quantum-solvers.md
+ */
+/**
+ * A problem requiring multi-path reasoning validation.
+ */
+export interface ReasoningProblem {
+    /** Problem domain: 'test-generation', 'security-audit', 'defect-triage' */
+    type: string;
+    /** Domain-specific context data */
+    context: Record<string, unknown>;
+    /** Reasoning steps to validate */
+    steps: string[];
+}
+/**
+ * A single step within a reasoning path.
+ */
+export interface ReasoningStep {
+    /** Zero-based step index within the path */
+    index: number;
+    /** Human-readable description of what this step does */
+    description: string;
+    /** The conclusion reached at this step */
+    conclusion: string;
+    /** Evidence supporting this conclusion */
+    evidence: string[];
+}
+/**
+ * An independent reasoning path through a problem.
+ */
+export interface ReasoningPath {
+    /** Path identifier (0, 1, 2) */
+    id: number;
+    /** Ordered reasoning steps */
+    steps: ReasoningStep[];
+    /** Final conclusion of this path */
+    conclusion: string;
+    /** Confidence in the conclusion (0-1) */
+    confidence: number;
+}
+/**
+ * A syndrome identifies a disagreement location between paths.
+ */
+export interface Syndrome {
+    /** Step index where disagreement occurs */
+    stepIndex: number;
+    /** Which paths disagree, and what each concluded */
+    disagreements: {
+        pathId: number;
+        conclusion: string;
+    }[];
+    /** How severe the disagreement is */
+    severity: 'minor' | 'major' | 'critical';
+}
+/**
+ * The result after error correction has been applied.
+ */
+export interface CorrectedReasoning {
+    /** Corrected reasoning steps */
+    steps: ReasoningStep[];
+    /** Corrected final conclusion */
+    conclusion: string;
+    /** Confidence in the corrected reasoning (0-1) */
+    confidence: number;
+    /** List of corrections applied */
+    corrections: CorrectionEntry[];
+    /** Number of syndromes detected */
+    syndromeCount: number;
+}
+/**
+ * A single correction applied during error correction.
+ */
+export interface CorrectionEntry {
+    /** Step index where the correction was applied */
+    stepIndex: number;
+    /** Original (minority) conclusion that was overridden */
+    original: string;
+    /** Corrected (majority) conclusion */
+    corrected: string;
+    /** Human-readable reason for the correction */
+    reason: string;
+}
+/**
+ * Result of validating a corrected reasoning chain.
+ */
+export interface ValidationResult {
+    /** Whether the corrected reasoning passes validation */
+    valid: boolean;
+    /** Overall confidence in the validated result (0-1) */
+    confidence: number;
+    /** Issues discovered during validation */
+    issues: ValidationIssue[];
+}
+/**
+ * A single issue found during validation.
+ */
+export interface ValidationIssue {
+    /** Step index where issue was found, or -1 for conclusion-level */
+    stepIndex: number;
+    /** Type of issue */
+    type: 'low-confidence' | 'no-majority' | 'inconsistent-evidence' | 'all-divergent';
+    /** Human-readable description */
+    description: string;
+}
+/**
+ * Configuration for the ReasoningQEC engine.
+ */
+export interface ReasoningQECConfig {
+    /** Minimum number of reasoning paths (default: 3) */
+    minPaths: number;
+    /** Confidence threshold below which syndromes are flagged (default: 0.5) */
+    confidenceThreshold: number;
+    /** Minimum agreement ratio for a corrected step to be considered valid (default: 0.5) */
+    majorityThreshold: number;
+    /** Whether to attempt loading the native ruqu-exotic module (default: true) */
+    useNativeBackend: boolean;
+    /** Voting method for error correction: 'weighted' uses path confidence, 'majority' uses simple count (default: 'weighted') */
+    votingMethod: 'majority' | 'weighted';
+}
+/**
+ * Default configuration values.
+ */
+export declare const DEFAULT_QEC_CONFIG: ReasoningQECConfig;
+/**
+ * Multi-Path Consensus Reasoning Validator.
+ *
+ * Named QEC by analogy with quantum error correction; implements consensus
+ * voting across multiple reasoning paths, not quantum algorithms.
+ *
+ * Generates multiple independent reasoning paths for a given problem,
+ * extracts syndrome locations where paths disagree, and applies
+ * confidence-weighted (or simple majority) voting to produce a
+ * high-confidence result.
+ *
+ * @example
+ * ```typescript
+ * const qec = new ReasoningQEC();
+ *
+ * const problem: ReasoningProblem = {
+ *   type: 'security-audit',
+ *   context: { file: 'auth.ts', finding: 'potential XSS' },
+ *   steps: ['Analyze input handling', 'Check sanitization', 'Evaluate risk'],
+ * };
+ *
+ * const paths = qec.generatePaths(problem);
+ * const syndromes = qec.extractSyndromes(paths);
+ * const corrected = qec.correctErrors(paths, syndromes);
+ * const validation = qec.validate(corrected);
+ * ```
+ */
+export declare class ReasoningQEC {
+    private readonly config;
+    private nativeAvailable;
+    constructor(config?: Partial<ReasoningQECConfig>);
+    /**
+     * Initialize the engine, probing for the native backend if configured.
+     * Call this once before using generate/extract/correct methods.
+     * If not called, the engine works in pure TypeScript mode.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Generate independent reasoning paths for a problem.
+     *
+     * Each path represents a different analytical perspective on the problem,
+     * producing its own step-by-step reasoning chain and conclusion.
+     *
+     * @param problem - The reasoning problem to analyze
+     * @returns Array of independent reasoning paths (minimum 3)
+     */
+    generatePaths(problem: ReasoningProblem): ReasoningPath[];
+    /**
+     * Extract syndromes (disagreement locations) from reasoning paths.
+     *
+     * Compares all paths step-by-step and identifies indices where
+     * paths reach different conclusions. Severity is classified as:
+     *   - minor: only one path disagrees (easily correctable)
+     *   - major: paths are split (no clear majority)
+     *   - critical: all paths disagree (low confidence in any correction)
+     *
+     * @param paths - Array of reasoning paths to compare
+     * @returns Array of syndromes identifying disagreement locations
+     */
+    extractSyndromes(paths: ReasoningPath[]): Syndrome[];
+    /**
+     * Correct errors using voting across paths.
+     *
+     * For each step, the conclusion with the highest vote weight among paths
+     * is selected. When votingMethod is 'weighted', path confidence is used
+     * as vote weight. When 'majority', simple count-based voting is used.
+     * If no clear majority exists, the highest-weighted conclusion is used
+     * but confidence is reduced.
+     *
+     * @param paths - Array of reasoning paths
+     * @param syndromes - Array of extracted syndromes
+     * @returns Corrected reasoning with applied corrections
+     */
+    correctErrors(paths: ReasoningPath[], syndromes: Syndrome[]): CorrectedReasoning;
+    /**
+     * Validate a corrected reasoning chain.
+     *
+     * Checks for low confidence, missing majority, inconsistent evidence,
+     * and all-divergent conditions. Returns a validation result indicating
+     * whether the corrected reasoning is trustworthy.
+     *
+     * @param corrected - The corrected reasoning to validate
+     * @returns Validation result with confidence and any issues found
+     */
+    validate(corrected: CorrectedReasoning): ValidationResult;
+    /**
+     * Convenience method: run the full QEC pipeline on a problem.
+     *
+     * @param problem - The reasoning problem
+     * @returns Object containing paths, syndromes, corrected reasoning, and validation
+     */
+    process(problem: ReasoningProblem): {
+        paths: ReasoningPath[];
+        syndromes: Syndrome[];
+        corrected: CorrectedReasoning;
+        validation: ValidationResult;
+    };
+    /**
+     * Get current configuration.
+     */
+    getConfig(): Readonly<ReasoningQECConfig>;
+    /**
+     * Check if native backend is available.
+     */
+    isNativeAvailable(): boolean;
+    /**
+     * Generate steps for a single reasoning path from a given perspective.
+     */
+    private generatePathSteps;
+    /**
+     * Generate a conclusion for a step based on perspective and context.
+     *
+     * Each perspective prioritizes different aspects of the context, producing
+     * genuinely diverse conclusions rather than identical text with a path suffix.
+     *
+     * In production this would call an LLM or apply domain-specific heuristics.
+     * The TypeScript fallback uses deterministic derivation from inputs.
+     */
+    private generateStepConclusion;
+    /**
+     * Gather evidence for a step from the given perspective.
+     */
+    private gatherEvidence;
+    /**
+     * Derive a final conclusion from a set of completed steps.
+     */
+    private deriveConclusion;
+    /**
+     * Calculate confidence for a single path based on its steps.
+     */
+    private calculatePathConfidence;
+    /**
+     * Classify syndrome severity based on how many distinct conclusions exist.
+     */
+    private classifySyndromeSeverity;
+    /**
+     * Correct a single step by voting among paths.
+     *
+     * When votingMethod is 'weighted', each path's vote is weighted by its
+     * confidence score. When 'majority', simple count-based voting is used.
+     */
+    private correctStep;
+    /**
+     * Correct the final conclusion using voting among paths.
+     *
+     * When votingMethod is 'weighted', each path's vote is weighted by its
+     * confidence score. When 'majority', simple count-based voting is used.
+     */
+    private correctConclusion;
+    /**
+     * Calculate confidence for the corrected reasoning based on path agreement
+     * and syndrome severity.
+     */
+    private calculateCorrectedConfidence;
+}
+/**
+ * Create a new ReasoningQEC engine with optional configuration.
+ *
+ * @param config - Partial configuration overrides
+ * @returns Configured ReasoningQEC instance
+ */
+export declare function createReasoningQEC(config?: Partial<ReasoningQECConfig>): ReasoningQEC;
+/**
+ * Run the full QEC pipeline on a problem in one call.
+ *
+ * @param problem - The reasoning problem to process
+ * @param config - Optional configuration overrides
+ * @returns Pipeline result with paths, syndromes, corrected reasoning, and validation
+ */
+export declare function processReasoning(problem: ReasoningProblem, config?: Partial<ReasoningQECConfig>): {
+    paths: ReasoningPath[];
+    syndromes: Syndrome[];
+    corrected: CorrectedReasoning;
+    validation: ValidationResult;
+};
+//# sourceMappingURL=reasoning-qec.d.ts.map