recursive-llm-ts 4.4.1 → 4.6.0

package/dist/rlm.js

@@ -1,4 +1,19 @@
 "use strict";
+/**
+ * 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);
+ * ```
+ */
 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) {
@@ -9,17 +24,265 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RLM = void 0;
+exports.RLM = exports.RLMBuilder = exports.RLMResultFormatter = void 0;
 const bridge_factory_1 = require("./bridge-factory");
 const file_storage_1 = require("./file-storage");
+const events_1 = require("./events");
+const cache_1 = require("./cache");
+const retry_1 = require("./retry");
+const streaming_1 = require("./streaming");
+const config_1 = require("./config");
+const errors_1 = require("./errors");
+/** Pretty-printable result wrapper */
+class RLMResultFormatter {
+    constructor(result, stats, cached, model, trace_events) {
+        this.result = result;
+        this.stats = stats;
+        this.cached = cached;
+        this.model = model;
+        this.trace_events = trace_events;
+    }
+    /** Format stats as a concise one-liner */
+    prettyStats() {
+        const parts = [
+            `LLM Calls: ${this.stats.llm_calls}`,
+            `Iterations: ${this.stats.iterations}`,
+            `Depth: ${this.stats.depth}`,
+        ];
+        if (this.stats.parsing_retries) {
+            parts.push(`Retries: ${this.stats.parsing_retries}`);
+        }
+        if (this.cached) {
+            parts.push('(cached)');
+        }
+        return parts.join(' | ');
+    }
+    /** Serialize to a JSON-safe object */
+    toJSON() {
+        return {
+            result: this.result,
+            stats: this.stats,
+            cached: this.cached,
+            model: this.model,
+            trace_events: this.trace_events,
+        };
+    }
+    /** Format as Markdown */
+    toMarkdown() {
+        const lines = [
+            '## Result',
+            '',
+            this.result,
+            '',
+            '## Stats',
+            '',
+            `| Metric | Value |`,
+            `|--------|-------|`,
+            `| LLM Calls | ${this.stats.llm_calls} |`,
+            `| Iterations | ${this.stats.iterations} |`,
+            `| Depth | ${this.stats.depth} |`,
+        ];
+        if (this.stats.parsing_retries) {
+            lines.push(`| Parsing Retries | ${this.stats.parsing_retries} |`);
+        }
+        lines.push(`| Cached | ${this.cached} |`);
+        lines.push(`| Model | ${this.model} |`);
+        return lines.join('\n');
+    }
+}
+exports.RLMResultFormatter = RLMResultFormatter;
+// ─── Builder ─────────────────────────────────────────────────────────────────
+/**
+ * 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();
+ * ```
+ */
+class RLMBuilder {
+    constructor(model) {
+        this.config = {};
+        this.bridgeType = 'auto';
+        this.model = model;
+    }
+    /** Set the API key */
+    apiKey(key) {
+        this.config.api_key = key;
+        return this;
+    }
+    /** Set the API base URL */
+    apiBase(url) {
+        this.config.api_base = url;
+        return this;
+    }
+    /** Set maximum recursion depth */
+    maxDepth(depth) {
+        this.config.max_depth = depth;
+        return this;
+    }
+    /** Set maximum iterations */
+    maxIterations(iterations) {
+        this.config.max_iterations = iterations;
+        return this;
+    }
+    /** Enable meta-agent query optimization */
+    withMetaAgent(config) {
+        this.config.meta_agent = Object.assign({ enabled: true }, config);
+        return this;
+    }
+    /** Enable debug mode */
+    withDebug(logOutput) {
+        this.config.debug = true;
+        if (logOutput) {
+            this.config.observability = Object.assign(Object.assign({}, this.config.observability), { debug: true, log_output: logOutput });
+        }
+        return this;
+    }
+    /** Configure observability */
+    withObservability(config) {
+        this.config.observability = config;
+        return this;
+    }
+    /** Configure caching */
+    withCache(config) {
+        this.config.cache = Object.assign({ enabled: true }, config);
+        return this;
+    }
+    /** Configure retry behavior */
+    withRetry(config) {
+        this.config.retry = config;
+        return this;
+    }
+    /** Configure fallback models */
+    withFallback(models) {
+        this.config.fallback = { models, strategy: 'sequential' };
+        return this;
+    }
+    /** Set the bridge type */
+    bridge(type) {
+        this.bridgeType = type;
+        return this;
+    }
+    /** Configure context overflow recovery */
+    withContextOverflow(config) {
+        this.config.context_overflow = Object.assign({ enabled: true }, config);
+        return this;
+    }
+    /** Set the Go binary path */
+    binaryPath(path) {
+        this.config.go_binary_path = path;
+        return this;
+    }
+    /** Add LiteLLM passthrough parameters */
+    litellmParams(params) {
+        this.config.litellm_params = params;
+        return this;
+    }
+    /** Build the RLM instance */
+    build() {
+        return new RLM(this.model, this.config, this.bridgeType);
+    }
+}
+exports.RLMBuilder = RLMBuilder;
+// ─── Main RLM Class ──────────────────────────────────────────────────────────
 class RLM {
+    /**
+     * 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, rlmConfig = {}, bridgeType = 'auto') {
         this.bridge = null;
         this.lastTraceEvents = [];
         this.model = model;
         this.rlmConfig = this.normalizeConfig(rlmConfig);
         this.bridgeType = bridgeType;
+        this.events = new events_1.RLMEventEmitter();
+        this.cache = new cache_1.RLMCache(rlmConfig.cache);
     }
+    // ─── Static Factory Methods ──────────────────────────────────────────────
+    /**
+     * 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) {
+        return new RLM(model, {
+            api_key: process.env.OPENAI_API_KEY,
+            api_base: process.env.OPENAI_API_BASE,
+            debug: process.env.RLM_DEBUG === '1' || process.env.RLM_DEBUG === 'true',
+        });
+    }
+    /**
+     * 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, config = {}) {
+        return new RLM(model, Object.assign(Object.assign({}, config), { debug: true }));
+    }
+    /**
+     * 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, config) {
+        return new RLM(deploymentName, {
+            api_base: config.apiBase,
+            api_key: config.apiKey || process.env.AZURE_API_KEY,
+            litellm_params: { api_version: config.apiVersion || '2024-02-15-preview' },
+        });
+    }
+    /**
+     * 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) {
+        return new RLMBuilder(model);
+    }
+    // ─── Config Normalization ────────────────────────────────────────────────
     normalizeConfig(config) {
         // Normalize debug shorthand into observability config
         if (config.debug && !config.observability) {
@@ -30,6 +293,7 @@ class RLM {
         }
         return config;
     }
+    // ─── Bridge Management ───────────────────────────────────────────────────
     ensureBridge() {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.bridge) {
@@ -38,46 +302,544 @@ class RLM {
             return this.bridge;
         });
     }
-    completion(query, context) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const bridge = yield this.ensureBridge();
-            const result = yield bridge.completion(this.model, query, context, this.rlmConfig);
-            if (result.trace_events) {
-                this.lastTraceEvents = result.trace_events;
+    // ─── Event System ────────────────────────────────────────────────────────
+    /**
+     * 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(event, listener) {
+        this.events.on(event, listener);
+        return this;
+    }
+    /**
+     * Register a one-time event listener.
+     *
+     * @param event - Event type to listen for
+     * @param listener - Callback function (called once then removed)
+     */
+    once(event, listener) {
+        this.events.once(event, listener);
+        return this;
+    }
+    /**
+     * Remove an event listener.
+     *
+     * @param event - Event type
+     * @param listener - The listener function to remove
+     */
+    off(event, listener) {
+        this.events.off(event, listener);
+        return this;
+    }
+    /** Remove all event listeners */
+    removeAllListeners(event) {
+        this.events.removeAllListeners(event);
+        return this;
+    }
+    // ─── Core Completions ────────────────────────────────────────────────────
+    /**
+     * 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_1, context_1) {
+        return __awaiter(this, arguments, void 0, function* (query, context, options = {}) {
+            const startTime = Date.now();
+            this.events.emit('completion_start', {
+                timestamp: startTime,
+                type: 'completion_start',
+                model: this.model,
+                query,
+                contextLength: context.length,
+                structured: false,
+            });
+            // Check cache
+            const cached = this.cache.lookup(this.model, query, context);
+            if (cached.hit && cached.value) {
+                this.events.emit('cache', { timestamp: Date.now(), type: 'cache', action: 'hit' });
+                this.events.emit('completion_end', {
+                    timestamp: Date.now(),
+                    type: 'completion_end',
+                    model: this.model,
+                    duration: Date.now() - startTime,
+                    stats: cached.value.stats,
+                    cached: true,
+                });
+                return Object.assign(Object.assign({}, cached.value), { cached: true, model: this.model });
+            }
+            this.events.emit('cache', { timestamp: Date.now(), type: 'cache', action: 'miss' });
+            // Execute with retry
+            const execute = () => __awaiter(this, void 0, void 0, function* () {
+                const bridge = yield this.ensureBridge();
+                this.events.emit('llm_call', {
+                    timestamp: Date.now(),
+                    type: 'llm_call',
+                    model: this.model,
+                    queryLength: query.length,
+                    contextLength: context.length,
+                });
+                const result = yield bridge.completion(this.model, query, context, this.rlmConfig);
+                this.events.emit('llm_response', {
+                    timestamp: Date.now(),
+                    type: 'llm_response',
+                    model: this.model,
+                    duration: Date.now() - startTime,
+                });
+                return result;
+            });
+            try {
+                const result = yield (0, retry_1.withRetry)(execute, this.rlmConfig.retry, options.signal);
+                if (result.trace_events) {
+                    this.lastTraceEvents = result.trace_events;
+                }
+                // Store in cache
+                this.cache.store(this.model, query, context, result);
+                this.events.emit('cache', { timestamp: Date.now(), type: 'cache', action: 'store' });
+                this.events.emit('completion_end', {
+                    timestamp: Date.now(),
+                    type: 'completion_end',
+                    model: this.model,
+                    duration: Date.now() - startTime,
+                    stats: result.stats,
+                    cached: false,
+                });
+                return Object.assign(Object.assign({}, result), { cached: false, model: this.model });
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                this.events.emit('error', {
+                    timestamp: Date.now(),
+                    type: 'error',
+                    error,
+                    operation: 'completion',
+                });
+                throw err instanceof errors_1.RLMError ? err : (0, errors_1.classifyError)(error);
             }
-            return result;
         });
     }
+    /**
+     * 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(query_1, context_1, schema_1) {
         return __awaiter(this, arguments, void 0, function* (query, context, schema, options = {}) {
-            var _a, _b;
-            const bridge = yield this.ensureBridge();
+            const startTime = Date.now();
+            this.events.emit('completion_start', {
+                timestamp: startTime,
+                type: 'completion_start',
+                model: this.model,
+                query,
+                contextLength: context.length,
+                structured: true,
+            });
             const jsonSchema = this.zodToJsonSchema(schema);
-            const structuredConfig = {
-                schema: jsonSchema,
-                parallelExecution: (_a = options.parallelExecution) !== null && _a !== void 0 ? _a : true,
-                maxRetries: (_b = options.maxRetries) !== null && _b !== void 0 ? _b : 3
-            };
-            const result = yield bridge.completion(this.model, query, context, Object.assign(Object.assign({}, this.rlmConfig), { structured: structuredConfig }));
-            if (result.trace_events) {
-                this.lastTraceEvents = result.trace_events;
+            const execute = () => __awaiter(this, void 0, void 0, function* () {
+                var _a, _b;
+                const bridge = yield this.ensureBridge();
+                const structuredConfig = {
+                    schema: jsonSchema,
+                    parallelExecution: (_a = options.parallelExecution) !== null && _a !== void 0 ? _a : true,
+                    maxRetries: (_b = options.maxRetries) !== null && _b !== void 0 ? _b : 3,
+                };
+                this.events.emit('llm_call', {
+                    timestamp: Date.now(),
+                    type: 'llm_call',
+                    model: this.model,
+                    queryLength: query.length,
+                    contextLength: context.length,
+                });
+                const result = yield bridge.completion(this.model, query, context, Object.assign(Object.assign({}, this.rlmConfig), { structured: structuredConfig }));
+                return result;
+            });
+            try {
+                const result = yield (0, retry_1.withRetry)(execute, this.rlmConfig.retry, options.signal);
+                if (result.trace_events) {
+                    this.lastTraceEvents = result.trace_events;
+                }
+                // Validate result against Zod schema for type safety
+                let validated;
+                try {
+                    validated = schema.parse(result.result);
+                }
+                catch (zodErr) {
+                    throw new errors_1.RLMValidationError({
+                        message: `Structured output failed Zod validation: ${zodErr.message}`,
+                        expected: jsonSchema,
+                        received: result.result,
+                        zodErrors: zodErr.errors || zodErr.issues,
+                    });
+                }
+                this.events.emit('completion_end', {
+                    timestamp: Date.now(),
+                    type: 'completion_end',
+                    model: this.model,
+                    duration: Date.now() - startTime,
+                    stats: result.stats,
+                    cached: false,
+                });
+                return {
+                    result: validated,
+                    stats: result.stats,
+                    trace_events: result.trace_events,
+                };
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                this.events.emit('error', {
+                    timestamp: Date.now(),
+                    type: 'error',
+                    error,
+                    operation: 'structuredCompletion',
+                });
+                throw err;
+            }
+        });
+    }
+    // ─── Streaming ───────────────────────────────────────────────────────────
+    /**
+     * 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, context, options = {}) {
+        const stream = new streaming_1.RLMStream(options.signal);
+        (() => __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            try {
+                const result = yield this.completion(query, context, { signal: options.signal });
+                const text = typeof result.result === 'string' ? result.result : JSON.stringify(result.result);
+                // Simulate streaming by chunking
+                const chunkSize = 20;
+                for (let i = 0; i < text.length; i += chunkSize) {
+                    if ((_a = options.signal) === null || _a === void 0 ? void 0 : _a.aborted)
+                        return;
+                    const chunk = text.slice(i, i + chunkSize);
+                    stream.push({ type: 'text', text: chunk, timestamp: Date.now() });
+                    if (options.onChunk) {
+                        options.onChunk({ type: 'text', text: chunk, timestamp: Date.now() });
+                    }
+                    // Yield to event loop
+                    yield new Promise(resolve => setImmediate(resolve));
+                }
+                stream.complete(result.stats);
             }
-            // Validate result against Zod schema for type safety
-            const validated = schema.parse(result.result);
+            catch (err) {
+                stream.pushError(err instanceof Error ? err : new Error(String(err)));
+            }
+        }))();
+        return stream;
+    }
+    /**
+     * 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(query, context, schema, options = {}) {
+        const stream = new streaming_1.RLMStream(options.signal);
+        (() => __awaiter(this, void 0, void 0, function* () {
+            try {
+                const result = yield this.structuredCompletion(query, context, schema, options);
+                stream.push({
+                    type: 'partial_object',
+                    object: result.result,
+                    timestamp: Date.now(),
+                });
+                stream.complete(result.stats);
+            }
+            catch (err) {
+                stream.pushError(err instanceof Error ? err : new Error(String(err)));
+            }
+        }))();
+        return stream;
+    }
+    // ─── Batch Operations ────────────────────────────────────────────────────
+    /**
+     * 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_1) {
+        return __awaiter(this, arguments, void 0, function* (queries, options = {}) {
+            var _a;
+            const concurrency = (_a = options.concurrency) !== null && _a !== void 0 ? _a : 3;
+            const results = new Array(queries.length);
+            let index = 0;
+            const worker = () => __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                while (index < queries.length) {
+                    if ((_a = options.signal) === null || _a === void 0 ? void 0 : _a.aborted)
+                        return;
+                    const i = index++;
+                    try {
+                        results[i] = yield this.completion(queries[i].query, queries[i].context, { signal: options.signal });
+                    }
+                    catch (err) {
+                        results[i] = err instanceof Error ? err : new Error(String(err));
+                    }
+                }
+            });
+            const workers = Array.from({ length: Math.min(concurrency, queries.length) }, () => worker());
+            yield Promise.all(workers);
+            return results;
+        });
+    }
+    /**
+     * 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(queries_1) {
+        return __awaiter(this, arguments, void 0, function* (queries, options = {}) {
+            var _a;
+            const concurrency = (_a = options.concurrency) !== null && _a !== void 0 ? _a : 3;
+            const results = new Array(queries.length);
+            let index = 0;
+            const worker = () => __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                while (index < queries.length) {
+                    if ((_a = options.signal) === null || _a === void 0 ? void 0 : _a.aborted)
+                        return;
+                    const i = index++;
+                    try {
+                        results[i] = yield this.structuredCompletion(queries[i].query, queries[i].context, queries[i].schema, { signal: options.signal });
+                    }
+                    catch (err) {
+                        results[i] = err instanceof Error ? err : new Error(String(err));
+                    }
+                }
+            });
+            const workers = Array.from({ length: Math.min(concurrency, queries.length) }, () => worker());
+            yield Promise.all(workers);
+            return results;
+        });
+    }
+    // ─── File-Based Completions ──────────────────────────────────────────────
+    /**
+     * 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, fileConfig) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const builder = new file_storage_1.FileContextBuilder(fileConfig);
+            const storageResult = yield builder.buildContext();
+            const result = yield this.completion(query, storageResult.context);
+            return Object.assign(Object.assign({}, result), { fileStorage: storageResult });
+        });
+    }
+    /**
+     * 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(query_1, fileConfig_1, schema_1) {
+        return __awaiter(this, arguments, void 0, function* (query, fileConfig, schema, options = {}) {
+            const builder = new file_storage_1.FileContextBuilder(fileConfig);
+            const storageResult = yield builder.buildContext();
+            const result = yield this.structuredCompletion(query, storageResult.context, schema, options);
             return {
-                result: validated,
+                result: result.result,
                 stats: result.stats,
-                trace_events: result.trace_events
+                trace_events: result.trace_events,
+                fileStorage: storageResult,
             };
         });
     }
+    /**
+     * 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) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const builder = new file_storage_1.FileContextBuilder(fileConfig);
+            return builder.listMatchingFiles();
+        });
+    }
+    /**
+     * 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) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const builder = new file_storage_1.FileContextBuilder(fileConfig);
+            return builder.buildContext();
+        });
+    }
+    // ─── Observability ───────────────────────────────────────────────────────
     /**
      * 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() {
         return this.lastTraceEvents;
     }
+    /**
+     * Get cache statistics (hits, misses, hit rate).
+     *
+     * @returns Cache performance statistics
+     */
+    getCacheStats() {
+        return this.cache.getStats();
+    }
+    /** Clear the completion cache */
+    clearCache() {
+        this.cache.clear();
+    }
+    // ─── Validation ──────────────────────────────────────────────────────────
+    /**
+     * 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() {
+        return (0, config_1.validateConfig)(this.rlmConfig);
+    }
+    // ─── Result Formatting ───────────────────────────────────────────────────
+    /**
+     * 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) {
+        return new RLMResultFormatter(typeof result.result === 'string' ? result.result : JSON.stringify(result.result), result.stats, result.cached, result.model, result.trace_events);
+    }
+    // ─── Cleanup ─────────────────────────────────────────────────────────────
+    /**
+     * Clean up the bridge connection and free resources.
+     * Call this when you're done using the RLM instance.
+     */
+    cleanup() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.bridge) {
+                yield this.bridge.cleanup();
+                this.bridge = null;
+            }
+            this.events.removeAllListeners();
+        });
+    }
+    /**
+     * Support for `Symbol.asyncDispose` (Node 22+ `await using`).
+     */
+    [Symbol.asyncDispose]() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.cleanup();
+        });
+    }
+    // ─── Zod to JSON Schema Conversion ───────────────────────────────────────
     zodToJsonSchema(schema) {
         var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
         const def = schema._def;
@@ -88,7 +850,7 @@ class RLM {
             if (defType === 'nullable') {
                 return Object.assign(Object.assign({}, inner), { nullable: true });
             }
-            return inner; // Optional/Default/Catch don't change the schema, just validation
+            return inner;
         }
         // Handle effects (refine, transform, preprocess) - unwrap to inner type
         if (defType === 'effects') {
@@ -100,13 +862,11 @@ class RLM {
         }
         // Handle lazy schemas - unwrap the getter
         if (defType === 'lazy') {
-            // For lazy schemas, we need to call the getter to get the actual schema
             try {
                 const actualSchema = def.getter();
                 return this.zodToJsonSchema(actualSchema);
             }
             catch (e) {
-                // If lazy getter fails, fall back to generic object
                 return { type: 'object' };
             }
         }
@@ -120,7 +880,6 @@ class RLM {
         }
         // Handle literals
         if (defType === 'literal') {
-            // Literals in this Zod version use 'values' array
             if (def.values && def.values.length > 0) {
                 const value = def.values[0];
                 const valueType = typeof value;
@@ -129,7 +888,6 @@ class RLM {
                     enum: [value]
                 };
             }
-            // Fallback for other literal formats
             const value = def.value;
             if (value !== undefined) {
                 const valueType = typeof value;
@@ -164,7 +922,6 @@ class RLM {
             const required = [];
             for (const [key, value] of Object.entries(shape)) {
                 properties[key] = this.zodToJsonSchema(value);
-                // A field is required if it's not optional and doesn't have a default
                 const valueDef = value._def;
                 const isOptional = (_d = (_c = (_b = value).isOptional) === null || _c === void 0 ? void 0 : _c.call(_b)) !== null && _d !== void 0 ? _d : false;
                 const hasDefault = (valueDef === null || valueDef === void 0 ? void 0 : valueDef.type) === 'default';
@@ -172,30 +929,20 @@ class RLM {
                     required.push(key);
                 }
             }
-            const result = {
-                type: 'object',
-                properties
-            };
-            if (required.length > 0) {
+            const result = { type: 'object', properties };
+            if (required.length > 0)
                 result.required = required;
-            }
-            // Handle unknown keys via catchall
             if (def.catchall) {
                 const catchallType = (_e = def.catchall._def) === null || _e === void 0 ? void 0 : _e.type;
-                if (catchallType === 'unknown') {
+                if (catchallType === 'unknown')
                     result.additionalProperties = true;
-                }
-                else if (catchallType === 'never') {
+                else if (catchallType === 'never')
                     result.additionalProperties = false;
-                }
             }
-            // Also check legacy unknownKeys
-            if (def.unknownKeys === 'passthrough') {
+            if (def.unknownKeys === 'passthrough')
                 result.additionalProperties = true;
-            }
-            else if (def.unknownKeys === 'strict') {
+            else if (def.unknownKeys === 'strict')
                 result.additionalProperties = false;
-            }
             return result;
         }
         // Handle array type
@@ -205,7 +952,6 @@ class RLM {
                 type: 'array',
                 items: this.zodToJsonSchema(itemSchema)
             };
-            // Handle array length constraints from checks
             if (def.checks && Array.isArray(def.checks)) {
                 for (const check of def.checks) {
                     const checkDef = ((_f = check._zod) === null || _f === void 0 ? void 0 : _f.def) || check.def || check;
@@ -223,7 +969,6 @@ class RLM {
                     }
                 }
             }
-            // Also check direct properties (legacy)
             if (def.minLength)
                 result.minItems = def.minLength.value || def.minLength;
             if (def.maxLength)
@@ -244,52 +989,31 @@ class RLM {
                 minItems: items.length,
                 maxItems: def.rest ? undefined : items.length
             };
-            // Handle rest element
-            if (def.rest) {
+            if (def.rest)
                 result.items = this.zodToJsonSchema(def.rest);
-            }
-            else {
-                result.items = false; // No additional items allowed
-            }
+            else
+                result.items = false;
             return result;
         }
-        // Handle set - convert to array
         if (defType === 'set') {
-            return {
-                type: 'array',
-                uniqueItems: true,
-                items: def.valueType ? this.zodToJsonSchema(def.valueType) : {}
-            };
+            return { type: 'array', uniqueItems: true, items: def.valueType ? this.zodToJsonSchema(def.valueType) : {} };
         }
-        // Handle map - convert to object
         if (defType === 'map') {
-            return {
-                type: 'object',
-                additionalProperties: def.valueType ? this.zodToJsonSchema(def.valueType) : true
-            };
+            return { type: 'object', additionalProperties: def.valueType ? this.zodToJsonSchema(def.valueType) : true };
         }
-        // Handle record
         if (defType === 'record') {
-            return {
-                type: 'object',
-                additionalProperties: def.valueType ? this.zodToJsonSchema(def.valueType) : true
-            };
+            return { type: 'object', additionalProperties: def.valueType ? this.zodToJsonSchema(def.valueType) : true };
         }
-        // Handle enum
         if (defType === 'enum' || defType === 'nativeEnum') {
-            if (def.values && Array.isArray(def.values)) {
+            if (def.values && Array.isArray(def.values))
                 return { type: 'string', enum: def.values };
-            }
-            if (def.entries) {
+            if (def.entries)
                 return { type: 'string', enum: Object.keys(def.entries) };
-            }
         }
-        // Handle string with constraints
         if (defType === 'string') {
             const result = { type: 'string' };
             if (def.checks && Array.isArray(def.checks)) {
                 for (const check of def.checks) {
-                    // Access the actual check data via _zod.def
                     const checkDef = ((_h = check._zod) === null || _h === void 0 ? void 0 : _h.def) || check.def || check;
                     switch (checkDef.check) {
                         case 'min_length':
@@ -314,9 +1038,8 @@ class RLM {
                                     result.format = 'uuid';
                                     break;
                                 case 'regex':
-                                    if (checkDef.pattern) {
+                                    if (checkDef.pattern)
                                         result.pattern = checkDef.pattern.source || checkDef.pattern;
-                                    }
                                     break;
                             }
                             break;
@@ -324,7 +1047,6 @@ class RLM {
                             result.pattern = ((_j = checkDef.pattern) === null || _j === void 0 ? void 0 : _j.source) || checkDef.pattern;
                             break;
                     }
-                    // Also check nested def for formats
                     if (check.def && check.def.format) {
                         switch (check.def.format) {
                             case 'email':
@@ -342,144 +1064,55 @@ class RLM {
             }
             return result;
         }
-        // Handle number/bigint with constraints
         if (defType === 'number' || defType === 'bigint') {
             const result = { type: defType === 'bigint' ? 'integer' : 'number' };
             if (def.checks && Array.isArray(def.checks)) {
                 for (const check of def.checks) {
-                    // Access the actual check data via _zod.def
                     const checkDef = ((_k = check._zod) === null || _k === void 0 ? void 0 : _k.def) || check.def || check;
                     switch (checkDef.check) {
                         case 'number_format':
-                            if (checkDef.format === 'safeint') {
+                            if (checkDef.format === 'safeint')
                                 result.type = 'integer';
-                            }
                             break;
                         case 'greater_than':
                             result.minimum = checkDef.value;
-                            if (!checkDef.inclusive) {
+                            if (!checkDef.inclusive)
                                 result.exclusiveMinimum = true;
-                            }
                             break;
                         case 'less_than':
                             result.maximum = checkDef.value;
-                            if (!checkDef.inclusive) {
+                            if (!checkDef.inclusive)
                                 result.exclusiveMaximum = true;
-                            }
                             break;
                         case 'multiple_of':
                             result.multipleOf = checkDef.value;
                             break;
                     }
-                    // Also check direct properties (legacy support)
-                    if (check.isInt === true) {
+                    if (check.isInt === true)
                         result.type = 'integer';
-                    }
                 }
             }
             return result;
         }
-        // Handle boolean
-        if (defType === 'boolean') {
+        if (defType === 'boolean')
             return { type: 'boolean' };
-        }
-        // Handle date
-        if (defType === 'date') {
+        if (defType === 'date')
             return { type: 'string', format: 'date-time' };
-        }
-        // Handle null
-        if (defType === 'null') {
+        if (defType === 'null')
             return { type: 'null' };
-        }
-        // Handle undefined (not really JSON-serializable, but treat as null)
-        if (defType === 'undefined') {
+        if (defType === 'undefined')
             return { type: 'null' };
-        }
-        // Handle void (same as undefined)
-        if (defType === 'void') {
+        if (defType === 'void')
             return { type: 'null' };
-        }
-        // Handle any/unknown - no constraints
-        if (defType === 'any' || defType === 'unknown') {
-            return {}; // Empty schema accepts anything
-        }
-        // Handle never - impossible to satisfy
-        if (defType === 'never') {
-            return { not: {} }; // Schema that matches nothing
-        }
-        // Handle promise - unwrap to inner type
-        if (defType === 'promise') {
+        if (defType === 'any' || defType === 'unknown')
+            return {};
+        if (defType === 'never')
+            return { not: {} };
+        if (defType === 'promise')
             return this.zodToJsonSchema(def.innerType || def.type);
-        }
-        // Handle function - not JSON-serializable
-        if (defType === 'function') {
+        if (defType === 'function')
             return { type: 'string', description: 'Function (not serializable)' };
-        }
-        // Default fallback
-        console.warn(`Unknown Zod type: ${defType}, falling back to string`);
         return { type: 'string' };
     }
-    escapeRegex(str) {
-        return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    }
-    /**
-     * 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.
-     */
-    completionFromFiles(query, fileConfig) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const builder = new file_storage_1.FileContextBuilder(fileConfig);
-            const storageResult = yield builder.buildContext();
-            const result = yield this.completion(query, storageResult.context);
-            return Object.assign(Object.assign({}, result), { fileStorage: storageResult });
-        });
-    }
-    /**
-     * 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.
-     */
-    structuredCompletionFromFiles(query_1, fileConfig_1, schema_1) {
-        return __awaiter(this, arguments, void 0, function* (query, fileConfig, schema, options = {}) {
-            const builder = new file_storage_1.FileContextBuilder(fileConfig);
-            const storageResult = yield builder.buildContext();
-            const result = yield this.structuredCompletion(query, storageResult.context, schema, options);
-            return {
-                result: result.result,
-                stats: result.stats,
-                trace_events: result.trace_events,
-                fileStorage: storageResult,
-            };
-        });
-    }
-    /**
-     * Preview which files would be included from a file storage config
-     * without actually reading them. Useful for dry-runs.
-     */
-    previewFiles(fileConfig) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const builder = new file_storage_1.FileContextBuilder(fileConfig);
-            return builder.listMatchingFiles();
-        });
-    }
-    /**
-     * Build context from a file storage config without running a completion.
-     * Useful for inspecting the generated context string.
-     */
-    buildFileContext(fileConfig) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const builder = new file_storage_1.FileContextBuilder(fileConfig);
-            return builder.buildContext();
-        });
-    }
-    cleanup() {
-        return __awaiter(this, void 0, void 0, function* () {
-            if (this.bridge) {
-                yield this.bridge.cleanup();
-                this.bridge = null;
-            }
-        });
-    }
 }
 exports.RLM = RLM;