agentic-qe 2.3.5 → 2.5.0

package/dist/core/optimization/RecursiveOptimizer.d.ts

@@ -0,0 +1,233 @@
+/**
+ * RecursiveOptimizer - TRM-based recursive optimization with binary cache
+ *
+ * Implements iterative refinement optimization using Test-time Reasoning
+ * & Metacognition (TRM) patterns. Features:
+ * - Recursive quality improvement with convergence detection
+ * - Binary cache for fast pattern retrieval
+ * - SONA integration for adaptive learning
+ * - EWC++ for preventing catastrophic forgetting
+ *
+ * @module core/optimization/RecursiveOptimizer
+ * @version 1.0.0
+ */
+/**
+ * Optimization configuration
+ */
+export interface RecursiveOptimizerConfig {
+    /** Maximum optimization iterations */
+    maxIterations?: number;
+    /** Convergence threshold (0-1) - stop when improvement below this */
+    convergenceThreshold?: number;
+    /** Quality metric to optimize */
+    qualityMetric?: 'coherence' | 'coverage' | 'diversity' | 'composite';
+    /** Minimum acceptable quality */
+    minQuality?: number;
+    /** Enable binary cache for patterns */
+    enableCache?: boolean;
+    /** Cache file path */
+    cachePath?: string;
+    /** Enable SONA learning */
+    enableSONA?: boolean;
+    /** LoRA rank for adapters */
+    loraRank?: number;
+    /** Pattern similarity threshold */
+    similarityThreshold?: number;
+}
+/**
+ * Optimization result
+ */
+export interface OptimizationResult<T> {
+    /** Optimized output */
+    output: T;
+    /** Final quality score (0-1) */
+    quality: number;
+    /** Number of iterations performed */
+    iterations: number;
+    /** Whether convergence was achieved */
+    converged: boolean;
+    /** Quality history per iteration */
+    qualityHistory: number[];
+    /** Total optimization time (ms) */
+    duration: number;
+    /** Pattern ID if cached */
+    patternId?: string;
+    /** Metadata about the optimization */
+    metadata: {
+        metric: string;
+        initialQuality: number;
+        improvement: number;
+        avgIterationTime: number;
+        cacheHit: boolean;
+    };
+}
+/**
+ * Optimization step function type
+ */
+export type OptimizationStep<T> = (current: T, iteration: number, previousQuality: number) => Promise<T>;
+/**
+ * Quality evaluation function type
+ */
+export type QualityEvaluator<T> = (output: T, metric: string) => number;
+/**
+ * RecursiveOptimizer - TRM-based recursive optimization
+ *
+ * Uses iterative refinement with convergence detection to optimize
+ * outputs. Patterns are cached for fast retrieval on similar inputs.
+ */
+export declare class RecursiveOptimizer {
+    private readonly logger;
+    private readonly config;
+    private cache;
+    private initialized;
+    private stats;
+    private ruvllm?;
+    private sonaCoordinator?;
+    constructor(config?: RecursiveOptimizerConfig);
+    /**
+     * Initialize the optimizer
+     */
+    initialize(): Promise<void>;
+    /**
+     * Optimize an output using recursive refinement
+     *
+     * @param initial - Initial output to optimize
+     * @param refine - Function to refine the output in each iteration
+     * @param evaluate - Function to evaluate output quality
+     * @param options - Override configuration options
+     * @returns Optimization result
+     */
+    optimize<T>(initial: T, refine: OptimizationStep<T>, evaluate: QualityEvaluator<T>, options?: Partial<RecursiveOptimizerConfig>): Promise<OptimizationResult<T>>;
+    /**
+     * Optimize with default text quality evaluation
+     */
+    optimizeText(initial: string, refine: OptimizationStep<string>, options?: Partial<RecursiveOptimizerConfig>): Promise<OptimizationResult<string>>;
+    /**
+     * Batch optimize multiple outputs
+     */
+    optimizeBatch<T>(items: T[], refine: OptimizationStep<T>, evaluate: QualityEvaluator<T>, options?: Partial<RecursiveOptimizerConfig> & {
+        parallel?: boolean;
+    }): Promise<OptimizationResult<T>[]>;
+    /**
+     * Get optimizer statistics
+     */
+    getStats(): typeof this.stats;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        entries: number;
+        hitRate: number;
+        avgAccessCount: number;
+        oldestEntry: number;
+        newestEntry: number;
+    };
+    /**
+     * Clear the optimization cache
+     */
+    clearCache(): void;
+    /**
+     * Reset optimizer statistics
+     */
+    resetStats(): void;
+    private ensureInitialized;
+    private checkCache;
+    private cacheResult;
+    private trackOptimizationTrajectory;
+    private updateStats;
+    private hashInput;
+    /**
+     * Generates embeddings for text input.
+     *
+     * When ruvLLM is available, uses proper transformer-based embeddings.
+     * Falls back to a simple character-based heuristic when ruvLLM is unavailable.
+     *
+     * @warning The fallback implementation is a PLACEHOLDER HEURISTIC.
+     * The character-based embedding:
+     * - Maps character codes to 768-dimensional space
+     * - Normalizes to unit magnitude
+     * - Does NOT capture semantic meaning
+     *
+     * This fallback is only used when:
+     * - ruvLLM native module fails to load
+     * - Running in test environment without ruvLLM server
+     *
+     * Production usage should always have ruvLLM available for proper embeddings.
+     */
+    private generateEmbedding;
+    /**
+     * Default text quality evaluator using heuristic metrics.
+     *
+     * @warning All metrics currently use PLACEHOLDER HEURISTICS.
+     * See individual measure* methods for details on what proper implementations
+     * would look like. These heuristics are sufficient for testing TRM iteration
+     * mechanics but should not be used for production quality assessment.
+     *
+     * Available metrics:
+     * - 'coherence': Sentence structure analysis (heuristic)
+     * - 'coverage': Unique word ratio (heuristic)
+     * - 'diversity': Vocabulary variety (heuristic)
+     * - 'composite': Weighted combination (40% coherence, 30% coverage, 30% diversity)
+     *
+     * @todo M4 milestone: Replace with ML-based evaluation using ruvLLM
+     */
+    private defaultTextEvaluator;
+    /**
+     * HEURISTIC: Measures text coherence using simple sentence structure analysis.
+     *
+     * @warning This is a PLACEHOLDER HEURISTIC, not a proper ML-based evaluation.
+     * Current implementation uses:
+     * - Average sentence length (normalized to 0-1)
+     * - Sentence count (normalized to 0-1)
+     *
+     * A proper implementation would use:
+     * - Transformer-based coherence models (e.g., sentence embeddings + cosine similarity)
+     * - Discourse structure analysis
+     * - Named entity consistency tracking
+     * - Coreference resolution scoring
+     *
+     * @todo Replace with ML-based coherence scoring in M4
+     */
+    private measureCoherence;
+    /**
+     * HEURISTIC: Measures text coverage using unique word ratio.
+     *
+     * @warning This is a PLACEHOLDER HEURISTIC, not a proper ML-based evaluation.
+     * Current implementation uses:
+     * - Ratio of unique words to total words
+     *
+     * A proper implementation would use:
+     * - Topic modeling (LDA, BERTopic) to measure topic coverage
+     * - Information density metrics
+     * - Semantic role coverage analysis
+     * - Requirement traceability scoring
+     *
+     * @todo Replace with ML-based coverage analysis in M4
+     */
+    private measureCoverage;
+    /**
+     * HEURISTIC: Measures text diversity using vocabulary variety.
+     *
+     * @warning This is a PLACEHOLDER HEURISTIC, not a proper ML-based evaluation.
+     * Current implementation uses:
+     * - Ratio of unique words (>3 chars) with 2x scaling
+     *
+     * A proper implementation would use:
+     * - Type-token ratio with smoothing
+     * - Lexical diversity indices (MTLD, HD-D, vocd-D)
+     * - N-gram entropy measures
+     * - Semantic embedding cluster analysis
+     *
+     * @todo Replace with ML-based diversity metrics in M4
+     */
+    private measureDiversity;
+}
+/**
+ * Create a pre-configured RecursiveOptimizer for test generation
+ */
+export declare function createTestGenerationOptimizer(): RecursiveOptimizer;
+/**
+ * Create a pre-configured RecursiveOptimizer for code analysis
+ */
+export declare function createCodeAnalysisOptimizer(): RecursiveOptimizer;
+//# sourceMappingURL=RecursiveOptimizer.d.ts.map

package/dist/core/optimization/RecursiveOptimizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecursiveOptimizer.d.ts","sourceRoot":"","sources":["../../../src/core/optimization/RecursiveOptimizer.ts"],"names":[],"mappings":"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"}