recursive-llm-ts 5.1.1 → 5.2.3

package/dist/esm/rlm.d.ts

@@ -0,0 +1,435 @@
+/**
+ * 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;
+    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: 'go' (default)
+     *
+     * @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;
+    /**
+     * 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>>;
+    /**
+     * 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);
+     * ```
+     */
+    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.
+     *
+     * @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<RLMCompletionResult & {
+        fileStorage: FileStorageResult;
+    }>;
+    /**
+     * Run a structured completion using files from a folder (local or S3) as context.
+     *
+     * @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;
+        parallelExecution?: boolean;
+    }): Promise<StructuredRLMResult<T> & {
+        fileStorage: FileStorageResult;
+    }>;
+    /**
+     * 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;
+}