cursor-recursive-rag 0.2.0-alpha.2 → 0.2.0

package/dist/services/rlmSafeguards.d.ts

@@ -0,0 +1,273 @@
+/**
+ * RLM Safeguards - Anti-Pattern Mitigations
+ *
+ * Based on the Recursive Language Models paper's Negative Results (Appendix A),
+ * this service implements safeguards to prevent common anti-patterns:
+ *
+ * 1. Model-specific configurations (not one-size-fits-all)
+ * 2. Capability detection for code execution ability
+ * 3. Token budget management (reserve for answers)
+ * 4. Multi-signal termination detection (not just tags)
+ * 5. Sub-call throttling and caching
+ * 6. Circuit breaker for runaway trajectories
+ * 7. Model prior-based pre-filtering
+ */
+import type { EnhancedChunk } from '../types/memory.js';
+import type { LLMService } from './contextEnvironment.js';
+export type CodeExecutionCapability = 'excellent' | 'good' | 'limited' | 'none';
+export type RetrievalStrategy = 'direct' | 'iterative' | 'recursive';
+export type CircuitBreakerState = 'closed' | 'open' | 'half-open';
+export interface ModelCapabilities {
+    codeExecution: CodeExecutionCapability;
+    contextWindow: number;
+    outputTokens: number;
+    supportsStreaming: boolean;
+    supportsToolUse: boolean;
+}
+export interface ModelConfig {
+    maxSubCalls: number;
+    maxIterations: number;
+    warnOnExcessiveCalls: boolean;
+    costMultiplier: number;
+    requiresExtraWarnings: boolean;
+    preferredChunkSize: number;
+}
+export declare const DEFAULT_MODEL_CAPABILITIES: ModelCapabilities;
+export declare const MODEL_CONFIGS: Record<string, ModelConfig>;
+export declare const MODEL_CAPABILITIES: Record<string, ModelCapabilities>;
+export interface TokenBudget {
+    totalOutputTokens: number;
+    reservedForAnswer: number;
+    maxThinkingTokens: number;
+    currentUsed: number;
+}
+export interface TerminationSignals {
+    explicitTag: boolean;
+    confidenceStatement: boolean;
+    noMoreActions: boolean;
+    answerValidation: boolean;
+    iterationLimitReached: boolean;
+    budgetExhausted: boolean;
+}
+export interface ValidationResult {
+    valid: boolean;
+    reason?: string;
+    confidence?: number;
+}
+/**
+ * Get model configuration, with fallback to default
+ */
+export declare function getModelConfig(modelName: string): ModelConfig;
+/**
+ * Get model capabilities, with fallback to default
+ */
+export declare function getModelCapabilities(modelName: string): ModelCapabilities;
+/**
+ * Choose retrieval strategy based on model capabilities and query complexity
+ */
+export declare function chooseRetrievalStrategy(capabilities: ModelCapabilities, queryComplexity: 'simple' | 'moderate' | 'complex'): RetrievalStrategy;
+/**
+ * Token Budget Manager
+ * Reserves output tokens for final answers to prevent running out
+ */
+export declare class TokenBudgetManager {
+    private budget;
+    constructor(modelName: string, reserveRatio?: number);
+    canUseTokens(count: number): boolean;
+    useTokens(count: number): void;
+    getRemainingThinkingTokens(): number;
+    getReservedForAnswer(): number;
+    getBudget(): TokenBudget;
+    reset(): void;
+}
+/**
+ * Multi-Signal Termination Detector
+ * Uses multiple signals to determine when to terminate, not just tags
+ */
+export declare class TerminationDetector {
+    private signals;
+    private requiredSignals;
+    constructor(requiredSignals?: number);
+    /**
+     * Check if response contains explicit termination tags
+     */
+    checkExplicitTag(response: string): boolean;
+    /**
+     * Check if response expresses confidence in the answer
+     */
+    checkConfidenceStatement(response: string): boolean;
+    /**
+     * Check if response doesn't request more operations
+     */
+    checkNoMoreActions(response: string): boolean;
+    /**
+     * Validate that answer is actually an answer, not a plan
+     */
+    validateAnswer(answer: string, query: string): ValidationResult;
+    /**
+     * Set iteration limit reached
+     */
+    setIterationLimitReached(): void;
+    /**
+     * Set budget exhausted
+     */
+    setBudgetExhausted(): void;
+    /**
+     * Check if we should terminate based on multiple signals
+     */
+    shouldTerminate(): {
+        terminate: boolean;
+        reason: string;
+        confidence: number;
+    };
+    /**
+     * Get current signals
+     */
+    getSignals(): TerminationSignals;
+    /**
+     * Reset signals
+     */
+    reset(): void;
+}
+/**
+ * Circuit Breaker for runaway trajectories
+ * Prevents excessive failures from consuming resources
+ */
+export declare class CircuitBreaker {
+    private failures;
+    private lastFailure;
+    private state;
+    private threshold;
+    private resetTimeMs;
+    constructor(threshold?: number, resetTimeMs?: number);
+    execute<T>(operation: () => Promise<T>): Promise<T>;
+    private onSuccess;
+    private onFailure;
+    getState(): CircuitBreakerState;
+    getFailures(): number;
+    reset(): void;
+}
+/**
+ * Sub-Call Throttler with Caching
+ * Prevents excessive sub-calls and caches results
+ */
+export declare class SubCallThrottler {
+    private callCounts;
+    private cache;
+    private maxCallsPerKey;
+    private cacheTtlMs;
+    constructor(maxCallsPerKey?: number, cacheTtlMs?: number);
+    throttledCall(key: string, llm: LLMService, prompt: string, options?: {
+        maxTokens?: number;
+        temperature?: number;
+    }): Promise<string>;
+    private hashPrompt;
+    getCallCount(key: string): number;
+    getCacheSize(): number;
+    clearCache(): void;
+    reset(): void;
+}
+/**
+ * Model Prior-Based Pre-Filter
+ * Filters context using patterns before semantic analysis
+ */
+export declare class PriorBasedFilter {
+    /**
+     * Pre-filter chunks using keyword patterns
+     */
+    filterByKeywords(chunks: EnhancedChunk[], keywords: string[], options?: {
+        matchAll?: boolean;
+        caseSensitive?: boolean;
+    }): EnhancedChunk[];
+    /**
+     * Extract keywords from query using heuristics
+     */
+    extractQueryKeywords(query: string): string[];
+    /**
+     * Smart pre-filter that combines multiple strategies
+     */
+    smartPreFilter(chunks: EnhancedChunk[], query: string, maxChunks?: number): EnhancedChunk[];
+}
+/**
+ * RLM Safeguards Coordinator
+ * Combines all safeguards into a single interface
+ */
+export declare class RLMSafeguards {
+    private tokenBudget;
+    private terminationDetector;
+    private circuitBreaker;
+    private throttler;
+    private priorFilter;
+    private modelConfig;
+    private modelCapabilities;
+    constructor(modelName: string, options?: {
+        requiredTerminationSignals?: number;
+        circuitBreakerThreshold?: number;
+        circuitBreakerResetMs?: number;
+        maxSubCallsPerKey?: number;
+        cacheTtlMs?: number;
+    });
+    /**
+     * Choose appropriate retrieval strategy
+     */
+    chooseStrategy(queryComplexity: 'simple' | 'moderate' | 'complex'): RetrievalStrategy;
+    /**
+     * Pre-filter chunks before processing
+     */
+    preFilter(chunks: EnhancedChunk[], query: string, maxChunks?: number): EnhancedChunk[];
+    /**
+     * Execute a sub-call with all safeguards
+     */
+    safeSubCall(key: string, llm: LLMService, prompt: string, options?: {
+        maxTokens?: number;
+        temperature?: number;
+    }): Promise<string>;
+    /**
+     * Check response and update termination signals
+     */
+    checkResponse(response: string, query: string): {
+        terminate: boolean;
+        reason: string;
+        confidence: number;
+    };
+    /**
+     * Mark iteration limit reached
+     */
+    markIterationLimitReached(): void;
+    /**
+     * Mark budget exhausted
+     */
+    markBudgetExhausted(): void;
+    /**
+     * Get model configuration
+     */
+    getModelConfig(): ModelConfig;
+    /**
+     * Get model capabilities
+     */
+    getModelCapabilities(): ModelCapabilities;
+    /**
+     * Get current state
+     */
+    getState(): {
+        tokenBudget: TokenBudget;
+        terminationSignals: TerminationSignals;
+        circuitBreakerState: CircuitBreakerState;
+        cacheSize: number;
+    };
+    /**
+     * Reset all state
+     */
+    reset(): void;
+}
+export interface RLMSafeguardsOptions {
+    requiredTerminationSignals?: number;
+    circuitBreakerThreshold?: number;
+    circuitBreakerResetMs?: number;
+    maxSubCallsPerKey?: number;
+    cacheTtlMs?: number;
+}
+export declare function createRLMSafeguards(modelName: string, options?: RLMSafeguardsOptions): RLMSafeguards;
+export declare function getRLMSafeguards(modelName?: string, options?: RLMSafeguardsOptions): RLMSafeguards;
+export declare function resetRLMSafeguards(): void;
+//# sourceMappingURL=rlmSafeguards.d.ts.map

package/dist/services/rlmSafeguards.d.ts.map

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