recursive-llm-ts 4.4.1 → 4.6.0

package/dist/retry.js

@@ -0,0 +1,185 @@
+"use strict";
+/**
+ * Retry and resilience layer for recursive-llm-ts.
+ *
+ * Provides configurable retry with exponential backoff, jitter,
+ * and provider fallback chains.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withRetry = withRetry;
+exports.withFallback = withFallback;
+const errors_1 = require("./errors");
+const DEFAULT_RETRYABLE_ERRORS = new Set([
+    'RATE_LIMIT',
+    'TIMEOUT',
+    'PROVIDER',
+    'UNKNOWN',
+]);
+function resolveConfig(config = {}) {
+    var _a, _b, _c, _d, _e;
+    return {
+        maxRetries: (_a = config.maxRetries) !== null && _a !== void 0 ? _a : 3,
+        backoff: (_b = config.backoff) !== null && _b !== void 0 ? _b : 'exponential',
+        baseDelay: (_c = config.baseDelay) !== null && _c !== void 0 ? _c : 1000,
+        maxDelay: (_d = config.maxDelay) !== null && _d !== void 0 ? _d : 30000,
+        jitter: (_e = config.jitter) !== null && _e !== void 0 ? _e : true,
+        retryableErrors: config.retryableErrors
+            ? new Set(config.retryableErrors)
+            : DEFAULT_RETRYABLE_ERRORS,
+        onRetry: config.onRetry,
+    };
+}
+// ─── Delay Calculation ───────────────────────────────────────────────────────
+function calculateDelay(attempt, config) {
+    let delay;
+    switch (config.backoff) {
+        case 'exponential':
+            delay = config.baseDelay * Math.pow(2, attempt);
+            break;
+        case 'linear':
+            delay = config.baseDelay * (attempt + 1);
+            break;
+        case 'fixed':
+            delay = config.baseDelay;
+            break;
+        default:
+            delay = config.baseDelay;
+    }
+    // Cap at max
+    delay = Math.min(delay, config.maxDelay);
+    // Add jitter (0.5x to 1.5x)
+    if (config.jitter) {
+        delay = delay * (0.5 + Math.random());
+    }
+    return Math.round(delay);
+}
+// ─── Retryable Check ─────────────────────────────────────────────────────────
+function isRetryable(error, config) {
+    // Never retry abort errors
+    if (error instanceof errors_1.RLMAbortError)
+        return false;
+    // Check explicit retryable flag
+    if (error instanceof errors_1.RLMError) {
+        if (!error.retryable)
+            return false;
+        return config.retryableErrors.has(error.code);
+    }
+    // For non-RLM errors, check message heuristics
+    const msg = error.message.toLowerCase();
+    if (msg.includes('rate limit') || msg.includes('429'))
+        return true;
+    if (msg.includes('timeout') || msg.includes('etimedout'))
+        return true;
+    if (msg.includes('econnreset') || msg.includes('econnrefused'))
+        return true;
+    if (msg.includes('500') || msg.includes('502') || msg.includes('503') || msg.includes('504'))
+        return true;
+    return false;
+}
+// ─── Sleep Helper ────────────────────────────────────────────────────────────
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal === null || signal === void 0 ? void 0 : signal.aborted) {
+            reject(new errors_1.RLMAbortError());
+            return;
+        }
+        const timer = setTimeout(resolve, ms);
+        if (signal) {
+            const onAbort = () => {
+                clearTimeout(timer);
+                reject(new errors_1.RLMAbortError());
+            };
+            signal.addEventListener('abort', onAbort, { once: true });
+        }
+    });
+}
+// ─── Retry Executor ──────────────────────────────────────────────────────────
+/**
+ * Execute a function with retry logic.
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   () => rlm.completion(query, context),
+ *   { maxRetries: 3, backoff: 'exponential' }
+ * );
+ * ```
+ */
+function withRetry(fn, config, signal) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const resolved = resolveConfig(config);
+        let lastError;
+        for (let attempt = 0; attempt <= resolved.maxRetries; attempt++) {
+            try {
+                if (signal === null || signal === void 0 ? void 0 : signal.aborted)
+                    throw new errors_1.RLMAbortError();
+                return yield fn();
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                lastError = error;
+                // Check if we should retry
+                if (attempt >= resolved.maxRetries || !isRetryable(error, resolved)) {
+                    throw error;
+                }
+                // Special handling for rate limit with retry-after
+                let delay;
+                if (error instanceof errors_1.RLMRateLimitError && error.retryAfter) {
+                    delay = error.retryAfter * 1000;
+                }
+                else {
+                    delay = calculateDelay(attempt, resolved);
+                }
+                // Notify callback
+                (_a = resolved.onRetry) === null || _a === void 0 ? void 0 : _a.call(resolved, attempt + 1, error, delay);
+                // Wait before retrying
+                yield sleep(delay, signal);
+            }
+        }
+        throw lastError || new Error('Retry failed');
+    });
+}
+/**
+ * Execute a function with fallback models.
+ * Tries each model in order until one succeeds.
+ *
+ * @example
+ * ```typescript
+ * const result = await withFallback(
+ *   (model) => rlm.completion(query, context, model),
+ *   { models: ['gpt-4o', 'claude-sonnet-4-20250514', 'gemini-2.0-flash'] }
+ * );
+ * ```
+ */
+function withFallback(fn, fallbackConfig, retryConfig, signal) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const models = fallbackConfig.models || [];
+        if (models.length === 0) {
+            throw new errors_1.RLMError('No models configured for fallback', { code: 'CONFIG', retryable: false });
+        }
+        let lastError;
+        for (const model of models) {
+            try {
+                if (signal === null || signal === void 0 ? void 0 : signal.aborted)
+                    throw new errors_1.RLMAbortError();
+                const result = yield withRetry(() => fn(model), retryConfig, signal);
+                return Object.assign(Object.assign({}, result), { _usedModel: model });
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err : new Error(String(err));
+                // Continue to next model
+            }
+        }
+        throw lastError || new Error('All fallback models failed');
+    });
+}

package/dist/rlm.d.ts

@@ -1,41 +1,367 @@
-import { RLMConfig, RLMResult, TraceEvent, FileStorageConfig } from './bridge-interface';
+/**
+ * Main RLM (Recursive Language Model) class.
+ *
+ * Provides the primary API for recursive completions, structured output,
+ * streaming, file-based context, caching, retry/resilience, and events.
+ *
+ * @example
+ * ```typescript
+ * import { RLM } from 'recursive-llm-ts';
+ *
+ * const rlm = new RLM('gpt-4o-mini', { api_key: process.env.OPENAI_API_KEY });
+ * const result = await rlm.completion('Summarize this', longDocument);
+ * console.log(result.result);
+ * ```
+ */
+import { RLMConfig, RLMResult, RLMStats, TraceEvent, FileStorageConfig, ContextOverflowConfig } from './bridge-interface';
 import { BridgeType } from './bridge-factory';
 import { z } from 'zod';
 import { StructuredRLMResult } from './structured-types';
 import { FileStorageResult } from './file-storage';
+import { RLMEventType, RLMEventMap } from './events';
+import { CacheConfig } from './cache';
+import { RetryConfig } from './retry';
+import { RLMStream, StreamOptions } from './streaming';
+import { RLMExtendedConfig, ValidationResult } from './config';
+/** Extended result with cache information */
+export interface RLMCompletionResult extends RLMResult {
+    /** Whether this result was served from cache */
+    cached: boolean;
+    /** Model that was actually used (relevant with fallback) */
+    model: string;
+}
+/** Pretty-printable result wrapper */
+export declare class RLMResultFormatter {
+    readonly result: string;
+    readonly stats: RLMStats;
+    readonly cached: boolean;
+    readonly model: string;
+    readonly trace_events?: TraceEvent[] | undefined;
+    constructor(result: string, stats: RLMStats, cached: boolean, model: string, trace_events?: TraceEvent[] | undefined);
+    /** Format stats as a concise one-liner */
+    prettyStats(): string;
+    /** Serialize to a JSON-safe object */
+    toJSON(): Record<string, unknown>;
+    /** Format as Markdown */
+    toMarkdown(): string;
+}
+/**
+ * Fluent builder for configuring RLM instances.
+ *
+ * @example
+ * ```typescript
+ * const rlm = RLM.builder('gpt-4o-mini')
+ *   .maxDepth(10)
+ *   .withMetaAgent()
+ *   .withDebug()
+ *   .withCache({ strategy: 'exact' })
+ *   .withRetry({ maxRetries: 3 })
+ *   .build();
+ * ```
+ */
+export declare class RLMBuilder {
+    private model;
+    private config;
+    private bridgeType;
+    constructor(model: string);
+    /** Set the API key */
+    apiKey(key: string): this;
+    /** Set the API base URL */
+    apiBase(url: string): this;
+    /** Set maximum recursion depth */
+    maxDepth(depth: number): this;
+    /** Set maximum iterations */
+    maxIterations(iterations: number): this;
+    /** Enable meta-agent query optimization */
+    withMetaAgent(config?: {
+        model?: string;
+        max_optimize_len?: number;
+    }): this;
+    /** Enable debug mode */
+    withDebug(logOutput?: string): this;
+    /** Configure observability */
+    withObservability(config: RLMConfig['observability']): this;
+    /** Configure caching */
+    withCache(config?: CacheConfig): this;
+    /** Configure retry behavior */
+    withRetry(config?: RetryConfig): this;
+    /** Configure fallback models */
+    withFallback(models: string[]): this;
+    /** Set the bridge type */
+    bridge(type: BridgeType): this;
+    /** Configure context overflow recovery */
+    withContextOverflow(config?: ContextOverflowConfig): this;
+    /** Set the Go binary path */
+    binaryPath(path: string): this;
+    /** Add LiteLLM passthrough parameters */
+    litellmParams(params: Record<string, unknown>): this;
+    /** Build the RLM instance */
+    build(): RLM;
+}
 export declare class RLM {
     private bridge;
     private model;
     private rlmConfig;
     private bridgeType;
     private lastTraceEvents;
-    constructor(model: string, rlmConfig?: RLMConfig, bridgeType?: BridgeType);
+    private events;
+    private cache;
+    /**
+     * Create a new RLM instance.
+     *
+     * @param model - The LLM model identifier (e.g., 'gpt-4o-mini', 'claude-sonnet-4-20250514')
+     * @param rlmConfig - Configuration options for the RLM engine
+     * @param bridgeType - Bridge selection: 'auto' (default), 'go', 'pythonia', 'bunpy'
+     *
+     * @example
+     * ```typescript
+     * const rlm = new RLM('gpt-4o-mini', {
+     *   api_key: process.env.OPENAI_API_KEY,
+     *   max_depth: 5,
+     *   cache: { enabled: true },
+     *   retry: { maxRetries: 3 },
+     * });
+     * ```
+     */
+    constructor(model: string, rlmConfig?: RLMExtendedConfig, bridgeType?: BridgeType);
+    /**
+     * Create an RLM instance using environment variables for configuration.
+     *
+     * @param model - The LLM model identifier
+     * @returns RLM instance configured from environment
+     *
+     * @example
+     * ```typescript
+     * // Uses OPENAI_API_KEY from environment
+     * const rlm = RLM.fromEnv('gpt-4o-mini');
+     * ```
+     */
+    static fromEnv(model: string): RLM;
+    /**
+     * Create an RLM instance with debug logging enabled.
+     *
+     * @param model - The LLM model identifier
+     * @param config - Additional configuration options
+     * @returns RLM instance with debug mode active
+     */
+    static withDebug(model: string, config?: RLMExtendedConfig): RLM;
+    /**
+     * Create an RLM instance configured for Azure OpenAI.
+     *
+     * @param deploymentName - Azure deployment name
+     * @param config - Azure-specific configuration
+     * @returns RLM instance configured for Azure
+     */
+    static forAzure(deploymentName: string, config: {
+        apiBase: string;
+        apiKey?: string;
+        apiVersion?: string;
+    }): RLM;
+    /**
+     * Create a fluent builder for advanced configuration.
+     *
+     * @param model - The LLM model identifier
+     * @returns Builder instance
+     *
+     * @example
+     * ```typescript
+     * const rlm = RLM.builder('gpt-4o-mini')
+     *   .apiKey(process.env.OPENAI_API_KEY!)
+     *   .maxDepth(10)
+     *   .withMetaAgent()
+     *   .withCache({ strategy: 'exact' })
+     *   .build();
+     * ```
+     */
+    static builder(model: string): RLMBuilder;
     private normalizeConfig;
     private ensureBridge;
-    completion(query: string, context: string): Promise<RLMResult>;
+    /**
+     * Register an event listener.
+     *
+     * @param event - Event type to listen for
+     * @param listener - Callback function
+     *
+     * @example
+     * ```typescript
+     * rlm.on('llm_call', (e) => console.log(`Calling ${e.model}`));
+     * rlm.on('error', (e) => reportError(e.error));
+     * rlm.on('cache', (e) => console.log(`Cache ${e.action}`));
+     * ```
+     */
+    on<K extends RLMEventType>(event: K, listener: (event: RLMEventMap[K]) => void): this;
+    /**
+     * Register a one-time event listener.
+     *
+     * @param event - Event type to listen for
+     * @param listener - Callback function (called once then removed)
+     */
+    once<K extends RLMEventType>(event: K, listener: (event: RLMEventMap[K]) => void): this;
+    /**
+     * Remove an event listener.
+     *
+     * @param event - Event type
+     * @param listener - The listener function to remove
+     */
+    off<K extends RLMEventType>(event: K, listener: (event: RLMEventMap[K]) => void): this;
+    /** Remove all event listeners */
+    removeAllListeners(event?: RLMEventType): this;
+    /**
+     * Execute a completion against an LLM with recursive decomposition.
+     *
+     * @param query - The question or instruction for the LLM
+     * @param context - The document or data to process (can be very large)
+     * @param options - Optional completion settings
+     * @returns The LLM response with execution statistics
+     *
+     * @example
+     * ```typescript
+     * const result = await rlm.completion('Summarize the key points', longDocument);
+     * console.log(result.result);
+     * console.log(`Used ${result.stats.llm_calls} LLM calls`);
+     * ```
+     */
+    completion(query: string, context: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<RLMCompletionResult>;
+    /**
+     * Extract structured, typed data from context using a Zod schema.
+     *
+     * @param query - The extraction task to perform
+     * @param context - The document or data to process
+     * @param schema - Zod schema defining the expected output structure
+     * @param options - Execution options (parallelExecution, maxRetries, signal)
+     * @returns Typed result matching your Zod schema
+     *
+     * @example
+     * ```typescript
+     * const schema = z.object({
+     *   summary: z.string(),
+     *   score: z.number().min(1).max(10),
+     *   tags: z.array(z.string()),
+     * });
+     *
+     * const result = await rlm.structuredCompletion('Analyze this document', doc, schema);
+     * console.log(result.result.summary);  // string
+     * console.log(result.result.score);    // number
+     * console.log(result.result.tags);     // string[]
+     * ```
+     */
     structuredCompletion<T>(query: string, context: string, schema: z.ZodSchema<T>, options?: {
         maxRetries?: number;
         parallelExecution?: boolean;
+        signal?: AbortSignal;
     }): Promise<StructuredRLMResult<T>>;
     /**
-     * Returns trace events from the last operation.
-     * Only populated when observability is enabled in the config.
+     * Stream a completion with progressive text output.
+     *
+     * Returns an async iterable of stream chunks. Supports AbortController
+     * for cancellation.
+     *
+     * Note: Currently simulates streaming by chunking the full response.
+     * Full streaming support (from the Go binary) is planned.
+     *
+     * @param query - The question or instruction for the LLM
+     * @param context - The document or data to process
+     * @param options - Stream options including AbortController signal
+     * @returns Async iterable stream of chunks
+     *
+     * @example
+     * ```typescript
+     * const stream = rlm.streamCompletion(query, context);
+     * for await (const chunk of stream) {
+     *   if (chunk.type === 'text') process.stdout.write(chunk.text);
+     * }
+     *
+     * // Or collect as string
+     * const text = await rlm.streamCompletion(query, context).toText();
+     *
+     * // With abort
+     * const controller = new AbortController();
+     * const stream = rlm.streamCompletion(query, context, { signal: controller.signal });
+     * setTimeout(() => controller.abort(), 5000);
+     * ```
      */
-    getTraceEvents(): TraceEvent[];
-    private zodToJsonSchema;
-    private escapeRegex;
+    streamCompletion(query: string, context: string, options?: StreamOptions): RLMStream;
+    /**
+     * Stream a structured completion with partial object updates.
+     *
+     * @param query - The extraction task to perform
+     * @param context - The document or data to process
+     * @param schema - Zod schema for the output structure
+     * @param options - Stream and execution options
+     * @returns Async iterable stream with partial object chunks
+     */
+    streamStructuredCompletion<T>(query: string, context: string, schema: z.ZodSchema<T>, options?: StreamOptions & {
+        maxRetries?: number;
+        parallelExecution?: boolean;
+    }): RLMStream<T>;
+    /**
+     * Execute multiple completions in parallel with concurrency control.
+     *
+     * @param queries - Array of query+context pairs to process
+     * @param options - Batch options including concurrency limit
+     * @returns Array of results in the same order as input
+     *
+     * @example
+     * ```typescript
+     * const results = await rlm.batchCompletion([
+     *   { query: 'Summarize chapter 1', context: ch1 },
+     *   { query: 'Summarize chapter 2', context: ch2 },
+     *   { query: 'Summarize chapter 3', context: ch3 },
+     * ], { concurrency: 2 });
+     * ```
+     */
+    batchCompletion(queries: Array<{
+        query: string;
+        context: string;
+    }>, options?: {
+        concurrency?: number;
+        signal?: AbortSignal;
+    }): Promise<Array<RLMCompletionResult | Error>>;
+    /**
+     * Execute multiple structured completions in parallel.
+     *
+     * @param queries - Array of query+context+schema triples
+     * @param options - Batch options including concurrency limit
+     * @returns Array of typed results
+     */
+    batchStructuredCompletion<T>(queries: Array<{
+        query: string;
+        context: string;
+        schema: z.ZodSchema<T>;
+    }>, options?: {
+        concurrency?: number;
+        signal?: AbortSignal;
+    }): Promise<Array<StructuredRLMResult<T> | Error>>;
     /**
      * Run a completion using files from a folder (local or S3) as context.
-     * The folder is read recursively, files are filtered and concatenated
-     * into a structured context string that the LLM can work through.
+     *
+     * @param query - The question or task to perform
+     * @param fileConfig - File storage configuration (local path or S3 bucket)
+     * @returns Result with fileStorage metadata (files included, skipped, total size)
+     *
+     * @example
+     * ```typescript
+     * const result = await rlm.completionFromFiles(
+     *   'Summarize the architecture',
+     *   { type: 'local', path: './src', extensions: ['.ts'] }
+     * );
+     * console.log(result.result);
+     * console.log(`Processed ${result.fileStorage.files.length} files`);
+     * ```
      */
-    completionFromFiles(query: string, fileConfig: FileStorageConfig): Promise<RLMResult & {
+    completionFromFiles(query: string, fileConfig: FileStorageConfig): Promise<RLMCompletionResult & {
         fileStorage: FileStorageResult;
     }>;
     /**
      * Run a structured completion using files from a folder (local or S3) as context.
-     * The folder is read recursively, files are filtered and concatenated
-     * into a structured context string that the LLM can work through.
+     *
+     * @param query - The extraction task to perform
+     * @param fileConfig - File storage configuration
+     * @param schema - Zod schema for the output structure
+     * @param options - Execution options
+     * @returns Typed result with fileStorage metadata
      */
     structuredCompletionFromFiles<T>(query: string, fileConfig: FileStorageConfig, schema: z.ZodSchema<T>, options?: {
         maxRetries?: number;
@@ -46,12 +372,64 @@ export declare class RLM {
     /**
      * Preview which files would be included from a file storage config
      * without actually reading them. Useful for dry-runs.
+     *
+     * @param fileConfig - File storage configuration
+     * @returns Array of relative file paths that match the config
      */
     previewFiles(fileConfig: FileStorageConfig): Promise<string[]>;
     /**
      * Build context from a file storage config without running a completion.
      * Useful for inspecting the generated context string.
+     *
+     * @param fileConfig - File storage configuration
+     * @returns Built context with metadata
      */
     buildFileContext(fileConfig: FileStorageConfig): Promise<FileStorageResult>;
+    /**
+     * Returns trace events from the last operation.
+     * Only populated when observability is enabled in the config.
+     *
+     * @returns Array of trace events from the most recent completion
+     */
+    getTraceEvents(): TraceEvent[];
+    /**
+     * Get cache statistics (hits, misses, hit rate).
+     *
+     * @returns Cache performance statistics
+     */
+    getCacheStats(): import("./cache").CacheStats;
+    /** Clear the completion cache */
+    clearCache(): void;
+    /**
+     * Validate the current configuration without making any API calls.
+     * Checks binary existence, config validity, and connectivity hints.
+     *
+     * @returns Validation result with issues
+     *
+     * @example
+     * ```typescript
+     * const issues = rlm.validate();
+     * if (!issues.valid) {
+     *   console.error('Config issues:', issues.issues);
+     * }
+     * ```
+     */
+    validate(): ValidationResult;
+    /**
+     * Create a formatted result wrapper from a completion result.
+     *
+     * @param result - The completion result to format
+     * @returns Formatter with prettyStats(), toJSON(), and toMarkdown() methods
+     */
+    formatResult(result: RLMCompletionResult): RLMResultFormatter;
+    /**
+     * Clean up the bridge connection and free resources.
+     * Call this when you're done using the RLM instance.
+     */
     cleanup(): Promise<void>;
+    /**
+     * Support for `Symbol.asyncDispose` (Node 22+ `await using`).
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    private zodToJsonSchema;
 }