recursive-llm-ts 4.4.1 → 4.6.0

package/dist/errors.js

@@ -0,0 +1,219 @@
+"use strict";
+/**
+ * Structured error hierarchy for recursive-llm-ts.
+ *
+ * All library errors extend {@link RLMError}, which adds:
+ * - `code` – machine-readable error identifier
+ * - `retryable` – whether the caller should retry
+ * - `suggestion` – human-readable remediation hint
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RLMAbortError = exports.RLMContextOverflowError = exports.RLMSchemaError = exports.RLMConfigError = exports.RLMBinaryError = exports.RLMProviderError = exports.RLMTimeoutError = exports.RLMRateLimitError = exports.RLMValidationError = exports.RLMError = void 0;
+exports.classifyError = classifyError;
+// ─── Base Error ──────────────────────────────────────────────────────────────
+class RLMError extends Error {
+    constructor(message, opts) {
+        var _a;
+        super(message);
+        this.name = 'RLMError';
+        this.code = opts.code;
+        this.retryable = (_a = opts.retryable) !== null && _a !== void 0 ? _a : false;
+        this.suggestion = opts.suggestion;
+    }
+}
+exports.RLMError = RLMError;
+// ─── Validation Errors ───────────────────────────────────────────────────────
+/** Thrown when a structured output fails schema validation. */
+class RLMValidationError extends RLMError {
+    constructor(opts) {
+        super(opts.message, {
+            code: 'VALIDATION',
+            retryable: true,
+            suggestion: 'The LLM returned output that did not match the Zod schema. Try a more capable model, simplify your schema, or increase maxRetries.',
+        });
+        this.name = 'RLMValidationError';
+        this.expected = opts.expected;
+        this.received = opts.received;
+        this.zodErrors = opts.zodErrors;
+    }
+}
+exports.RLMValidationError = RLMValidationError;
+// ─── Rate Limit ──────────────────────────────────────────────────────────────
+/** Thrown when the LLM provider returns a 429 rate limit response. */
+class RLMRateLimitError extends RLMError {
+    constructor(opts) {
+        super(opts.message, {
+            code: 'RATE_LIMIT',
+            retryable: true,
+            suggestion: opts.retryAfter
+                ? `Rate limited. Retry after ${opts.retryAfter}s.`
+                : 'Rate limited. Implement exponential backoff or upgrade your API tier.',
+        });
+        this.name = 'RLMRateLimitError';
+        this.retryAfter = opts.retryAfter;
+    }
+}
+exports.RLMRateLimitError = RLMRateLimitError;
+// ─── Timeout ─────────────────────────────────────────────────────────────────
+/** Thrown when an operation exceeds its time limit. */
+class RLMTimeoutError extends RLMError {
+    constructor(opts) {
+        super(opts.message, {
+            code: 'TIMEOUT',
+            retryable: true,
+            suggestion: `Operation timed out after ${opts.elapsed}ms (limit: ${opts.limit}ms). Increase the timeout or reduce context size.`,
+        });
+        this.name = 'RLMTimeoutError';
+        this.elapsed = opts.elapsed;
+        this.limit = opts.limit;
+    }
+}
+exports.RLMTimeoutError = RLMTimeoutError;
+// ─── Provider / API ──────────────────────────────────────────────────────────
+/** Thrown when the LLM provider returns an HTTP error. */
+class RLMProviderError extends RLMError {
+    constructor(opts) {
+        const retryable = opts.statusCode >= 500 || opts.statusCode === 429;
+        super(opts.message, {
+            code: 'PROVIDER',
+            retryable,
+            suggestion: retryable
+                ? `Provider "${opts.provider}" returned ${opts.statusCode}. This is likely transient – retry with backoff.`
+                : `Provider "${opts.provider}" returned ${opts.statusCode}. Check your API key, model name, and request parameters.`,
+        });
+        this.name = 'RLMProviderError';
+        this.statusCode = opts.statusCode;
+        this.provider = opts.provider;
+        this.responseBody = opts.responseBody;
+    }
+}
+exports.RLMProviderError = RLMProviderError;
+// ─── Binary / Bridge ─────────────────────────────────────────────────────────
+/** Thrown when the Go binary cannot be found or fails to start. */
+class RLMBinaryError extends RLMError {
+    constructor(opts) {
+        super(opts.message, {
+            code: 'BINARY',
+            retryable: false,
+            suggestion: `Go binary not found at "${opts.binaryPath}". Build it with: npm run build:go (or node scripts/build-go-binary.js)`,
+        });
+        this.name = 'RLMBinaryError';
+        this.binaryPath = opts.binaryPath;
+    }
+}
+exports.RLMBinaryError = RLMBinaryError;
+// ─── Configuration ───────────────────────────────────────────────────────────
+/** Thrown when the RLM configuration is invalid. */
+class RLMConfigError extends RLMError {
+    constructor(opts) {
+        super(opts.message, {
+            code: 'CONFIG',
+            retryable: false,
+            suggestion: `Invalid configuration for "${opts.field}". Check the RLMConfig documentation.`,
+        });
+        this.name = 'RLMConfigError';
+        this.field = opts.field;
+        this.value = opts.value;
+    }
+}
+exports.RLMConfigError = RLMConfigError;
+// ─── Schema ──────────────────────────────────────────────────────────────────
+/** Thrown when a JSON Schema is malformed or unsupported. */
+class RLMSchemaError extends RLMError {
+    constructor(opts) {
+        super(opts.message, {
+            code: 'SCHEMA',
+            retryable: false,
+            suggestion: `Schema issue at "${opts.path}": ${opts.constraint}. Simplify your Zod schema or check for unsupported types.`,
+        });
+        this.name = 'RLMSchemaError';
+        this.path = opts.path;
+        this.constraint = opts.constraint;
+    }
+}
+exports.RLMSchemaError = RLMSchemaError;
+// ─── Context Overflow ─────────────────────────────────────────────────────────
+/** Thrown when the request exceeds the model's context window. */
+class RLMContextOverflowError extends RLMError {
+    constructor(opts) {
+        super(opts.message, {
+            code: 'CONTEXT_OVERFLOW',
+            retryable: true,
+            suggestion: `Request has ${opts.requestTokens} tokens but model limit is ${opts.modelLimit}. ` +
+                'Enable context_overflow handling or reduce your context size.',
+        });
+        this.name = 'RLMContextOverflowError';
+        this.modelLimit = opts.modelLimit;
+        this.requestTokens = opts.requestTokens;
+    }
+}
+exports.RLMContextOverflowError = RLMContextOverflowError;
+// ─── Abort ───────────────────────────────────────────────────────────────────
+/** Thrown when an operation is aborted via AbortController. */
+class RLMAbortError extends RLMError {
+    constructor(message = 'Operation was aborted') {
+        super(message, {
+            code: 'ABORTED',
+            retryable: false,
+            suggestion: 'The operation was cancelled. This is expected when using AbortController.',
+        });
+        this.name = 'RLMAbortError';
+    }
+}
+exports.RLMAbortError = RLMAbortError;
+// ─── Error Classification Helper ─────────────────────────────────────────────
+/**
+ * Classify a raw Error into the appropriate RLM error type.
+ * Used internally by the bridge layer to wrap Go binary errors.
+ */
+function classifyError(err, context) {
+    var _a;
+    const msg = typeof err === 'string' ? err : err.message;
+    // Context overflow
+    if (msg.toLowerCase().includes('maximum context length') || msg.toLowerCase().includes('context_length_exceeded') || msg.toLowerCase().includes('too many input tokens')) {
+        const limitMatch = msg.match(/maximum context length is (\d[\d,]*)/i);
+        const requestMatch = msg.match(/(?:has|requested) (\d[\d,]*)\s*(?:input )?tokens/i);
+        const modelLimit = limitMatch ? parseInt(limitMatch[1].replace(/,/g, ''), 10) : 0;
+        const requestTokens = requestMatch ? parseInt(requestMatch[1].replace(/,/g, ''), 10) : 0;
+        return new RLMContextOverflowError({ message: msg, modelLimit, requestTokens });
+    }
+    // Rate limit
+    if (msg.includes('429') || msg.toLowerCase().includes('rate limit') || msg.toLowerCase().includes('too many requests')) {
+        const retryMatch = msg.match(/retry.after[:\s]+(\d+)/i);
+        return new RLMRateLimitError({
+            message: msg,
+            retryAfter: retryMatch ? parseInt(retryMatch[1], 10) : undefined,
+        });
+    }
+    // Timeout
+    if (msg.toLowerCase().includes('timeout') || msg.includes('ETIMEDOUT') || msg.includes('ESOCKETTIMEDOUT')) {
+        return new RLMTimeoutError({ message: msg, elapsed: 0, limit: 0 });
+    }
+    // Binary not found
+    if ((msg.includes('not found') && msg.includes('binary')) || (msg.includes('ENOENT') && (context === null || context === void 0 ? void 0 : context.binaryPath))) {
+        return new RLMBinaryError({ message: msg, binaryPath: (_a = context === null || context === void 0 ? void 0 : context.binaryPath) !== null && _a !== void 0 ? _a : 'unknown' });
+    }
+    // Provider errors with HTTP codes
+    const statusMatch = msg.match(/(?:status|code)[:\s]+(\d{3})/i);
+    if (statusMatch) {
+        const statusCode = parseInt(statusMatch[1], 10);
+        if (statusCode === 429) {
+            return new RLMRateLimitError({ message: msg });
+        }
+        return new RLMProviderError({
+            message: msg,
+            statusCode,
+            provider: (context === null || context === void 0 ? void 0 : context.provider) || 'unknown',
+        });
+    }
+    // Validation
+    if (msg.toLowerCase().includes('validation') || msg.toLowerCase().includes('schema') || msg.toLowerCase().includes('parse')) {
+        return new RLMValidationError({
+            message: msg,
+            expected: undefined,
+            received: undefined,
+        });
+    }
+    // Fallback
+    return new RLMError(msg, { code: 'UNKNOWN', retryable: false });
+}

package/dist/events.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Event system for recursive-llm-ts.
+ *
+ * Provides typed event emission for monitoring LLM operations,
+ * validation retries, recursion progress, and more.
+ */
+export interface RLMEventMap {
+    /** Fired when an LLM API call is made */
+    'llm_call': LLMCallEvent;
+    /** Fired when an LLM API call completes */
+    'llm_response': LLMResponseEvent;
+    /** Fired when a validation retry occurs */
+    'validation_retry': ValidationRetryEvent;
+    /** Fired when recursion depth changes */
+    'recursion': RecursionEvent;
+    /** Fired when meta-agent optimizes a query */
+    'meta_agent': MetaAgentEvent;
+    /** Fired on any error */
+    'error': ErrorEvent;
+    /** Fired when a completion starts */
+    'completion_start': CompletionStartEvent;
+    /** Fired when a completion ends */
+    'completion_end': CompletionEndEvent;
+    /** Fired when a cache lookup occurs */
+    'cache': CacheEvent;
+    /** Fired when a retry occurs */
+    'retry': RetryEvent;
+}
+export type RLMEventType = keyof RLMEventMap;
+interface BaseEvent {
+    timestamp: number;
+    type: string;
+}
+export interface LLMCallEvent extends BaseEvent {
+    type: 'llm_call';
+    model: string;
+    queryLength: number;
+    contextLength: number;
+}
+export interface LLMResponseEvent extends BaseEvent {
+    type: 'llm_response';
+    model: string;
+    duration: number;
+    tokenCount?: number;
+}
+export interface ValidationRetryEvent extends BaseEvent {
+    type: 'validation_retry';
+    attempt: number;
+    maxRetries: number;
+    error: string;
+}
+export interface RecursionEvent extends BaseEvent {
+    type: 'recursion';
+    depth: number;
+    maxDepth: number;
+    iteration: number;
+}
+export interface MetaAgentEvent extends BaseEvent {
+    type: 'meta_agent';
+    originalQuery: string;
+    optimizedQuery: string;
+    skipped: boolean;
+    reason?: string;
+}
+export interface ErrorEvent extends BaseEvent {
+    type: 'error';
+    error: Error;
+    operation: string;
+}
+export interface CompletionStartEvent extends BaseEvent {
+    type: 'completion_start';
+    model: string;
+    query: string;
+    contextLength: number;
+    structured: boolean;
+}
+export interface CompletionEndEvent extends BaseEvent {
+    type: 'completion_end';
+    model: string;
+    duration: number;
+    stats: {
+        llm_calls: number;
+        iterations: number;
+        depth: number;
+    };
+    cached: boolean;
+}
+export interface CacheEvent extends BaseEvent {
+    type: 'cache';
+    action: 'hit' | 'miss' | 'store';
+    key?: string;
+}
+export interface RetryEvent extends BaseEvent {
+    type: 'retry';
+    attempt: number;
+    maxRetries: number;
+    delay: number;
+    error: string;
+}
+type EventListener<T> = (event: T) => void;
+/**
+ * Typed event emitter for RLM operations.
+ *
+ * @example
+ * ```typescript
+ * const rlm = new RLM('gpt-4o-mini');
+ * rlm.on('llm_call', (event) => console.log('LLM call:', event.model));
+ * rlm.on('error', (event) => reportToSentry(event.error));
+ * ```
+ */
+export declare class RLMEventEmitter {
+    private listeners;
+    /** Register an event listener */
+    on<K extends RLMEventType>(event: K, listener: EventListener<RLMEventMap[K]>): this;
+    /** Register a one-time event listener */
+    once<K extends RLMEventType>(event: K, listener: EventListener<RLMEventMap[K]>): this;
+    /** Remove an event listener */
+    off<K extends RLMEventType>(event: K, listener: EventListener<RLMEventMap[K]>): this;
+    /** Remove all listeners for an event (or all events) */
+    removeAllListeners(event?: RLMEventType): this;
+    /** Emit an event to all registered listeners */
+    emit<K extends RLMEventType>(event: K, data: RLMEventMap[K]): void;
+    /** Get the number of listeners for an event */
+    listenerCount(event: RLMEventType): number;
+}
+export {};

package/dist/events.js

@@ -0,0 +1,77 @@
+"use strict";
+/**
+ * Event system for recursive-llm-ts.
+ *
+ * Provides typed event emission for monitoring LLM operations,
+ * validation retries, recursion progress, and more.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RLMEventEmitter = void 0;
+// ─── Event Emitter ───────────────────────────────────────────────────────────
+/**
+ * Typed event emitter for RLM operations.
+ *
+ * @example
+ * ```typescript
+ * const rlm = new RLM('gpt-4o-mini');
+ * rlm.on('llm_call', (event) => console.log('LLM call:', event.model));
+ * rlm.on('error', (event) => reportToSentry(event.error));
+ * ```
+ */
+class RLMEventEmitter {
+    constructor() {
+        this.listeners = new Map();
+    }
+    /** Register an event listener */
+    on(event, listener) {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, new Set());
+        }
+        this.listeners.get(event).add(listener);
+        return this;
+    }
+    /** Register a one-time event listener */
+    once(event, listener) {
+        const wrapper = (e) => {
+            this.off(event, wrapper);
+            listener(e);
+        };
+        return this.on(event, wrapper);
+    }
+    /** Remove an event listener */
+    off(event, listener) {
+        var _a;
+        (_a = this.listeners.get(event)) === null || _a === void 0 ? void 0 : _a.delete(listener);
+        return this;
+    }
+    /** Remove all listeners for an event (or all events) */
+    removeAllListeners(event) {
+        if (event) {
+            this.listeners.delete(event);
+        }
+        else {
+            this.listeners.clear();
+        }
+        return this;
+    }
+    /** Emit an event to all registered listeners */
+    emit(event, data) {
+        const eventListeners = this.listeners.get(event);
+        if (eventListeners) {
+            for (const listener of eventListeners) {
+                try {
+                    listener(data);
+                }
+                catch (_a) {
+                    // Don't let listener errors break the emitter
+                }
+            }
+        }
+    }
+    /** Get the number of listeners for an event */
+    listenerCount(event) {
+        var _a, _b;
+        return (_b = (_a = this.listeners.get(event)) === null || _a === void 0 ? void 0 : _a.size) !== null && _b !== void 0 ? _b : 0;
+    }
+}
+exports.RLMEventEmitter = RLMEventEmitter;

package/dist/index.d.ts

@@ -1,6 +1,12 @@
-export { RLM } from './rlm';
-export { RLMConfig, RLMResult, RLMStats, MetaAgentConfig, ObservabilityConfig, TraceEvent, FileStorageConfig } from './bridge-interface';
+export { RLM, RLMBuilder, RLMCompletionResult, RLMResultFormatter } from './rlm';
+export { RLMConfig, RLMResult, RLMStats, MetaAgentConfig, ObservabilityConfig, TraceEvent, FileStorageConfig, ContextOverflowConfig } from './bridge-interface';
 export { BridgeType } from './bridge-factory';
 export { StructuredRLMResult, SubTask, CoordinatorConfig, SchemaDecomposition } from './structured-types';
+export { RLMExtendedConfig, ValidationResult, ValidationIssue, ValidationLevel, validateConfig, assertValidConfig } from './config';
+export { RLMError, RLMValidationError, RLMRateLimitError, RLMTimeoutError, RLMProviderError, RLMBinaryError, RLMConfigError, RLMSchemaError, RLMContextOverflowError, RLMAbortError, classifyError, } from './errors';
+export { RLMStream, StreamOptions, StreamChunk, StreamChunkType, TextStreamChunk, PartialObjectStreamChunk, UsageStreamChunk, ErrorStreamChunk, DoneStreamChunk, createSimulatedStream, } from './streaming';
+export { RLMCache, CacheConfig, CacheStats, CacheProvider, MemoryCache, FileCache } from './cache';
+export { RetryConfig, FallbackConfig, withRetry, withFallback } from './retry';
+export { RLMEventEmitter, RLMEventMap, RLMEventType, LLMCallEvent, LLMResponseEvent, ValidationRetryEvent, RecursionEvent, MetaAgentEvent, ErrorEvent, CompletionStartEvent, CompletionEndEvent, CacheEvent, RetryEvent, } from './events';
 export { RLMAgentCoordinator } from './coordinator';
 export { FileContextBuilder, FileStorageProvider, FileStorageResult, FileEntry, LocalFileStorage, S3FileStorage, S3StorageError, buildFileContext, } from './file-storage';

package/dist/index.js

@@ -1,10 +1,47 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildFileContext = exports.S3StorageError = exports.S3FileStorage = exports.LocalFileStorage = exports.FileContextBuilder = exports.RLMAgentCoordinator = exports.RLM = void 0;
+exports.buildFileContext = exports.S3StorageError = exports.S3FileStorage = exports.LocalFileStorage = exports.FileContextBuilder = exports.RLMAgentCoordinator = exports.RLMEventEmitter = exports.withFallback = exports.withRetry = exports.FileCache = exports.MemoryCache = exports.RLMCache = exports.createSimulatedStream = exports.RLMStream = exports.classifyError = exports.RLMAbortError = exports.RLMContextOverflowError = exports.RLMSchemaError = exports.RLMConfigError = exports.RLMBinaryError = exports.RLMProviderError = exports.RLMTimeoutError = exports.RLMRateLimitError = exports.RLMValidationError = exports.RLMError = exports.assertValidConfig = exports.validateConfig = exports.RLMResultFormatter = exports.RLMBuilder = exports.RLM = void 0;
+// ─── Core ────────────────────────────────────────────────────────────────────
 var rlm_1 = require("./rlm");
 Object.defineProperty(exports, "RLM", { enumerable: true, get: function () { return rlm_1.RLM; } });
+Object.defineProperty(exports, "RLMBuilder", { enumerable: true, get: function () { return rlm_1.RLMBuilder; } });
+Object.defineProperty(exports, "RLMResultFormatter", { enumerable: true, get: function () { return rlm_1.RLMResultFormatter; } });
+var config_1 = require("./config");
+Object.defineProperty(exports, "validateConfig", { enumerable: true, get: function () { return config_1.validateConfig; } });
+Object.defineProperty(exports, "assertValidConfig", { enumerable: true, get: function () { return config_1.assertValidConfig; } });
+// ─── Errors ──────────────────────────────────────────────────────────────────
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "RLMError", { enumerable: true, get: function () { return errors_1.RLMError; } });
+Object.defineProperty(exports, "RLMValidationError", { enumerable: true, get: function () { return errors_1.RLMValidationError; } });
+Object.defineProperty(exports, "RLMRateLimitError", { enumerable: true, get: function () { return errors_1.RLMRateLimitError; } });
+Object.defineProperty(exports, "RLMTimeoutError", { enumerable: true, get: function () { return errors_1.RLMTimeoutError; } });
+Object.defineProperty(exports, "RLMProviderError", { enumerable: true, get: function () { return errors_1.RLMProviderError; } });
+Object.defineProperty(exports, "RLMBinaryError", { enumerable: true, get: function () { return errors_1.RLMBinaryError; } });
+Object.defineProperty(exports, "RLMConfigError", { enumerable: true, get: function () { return errors_1.RLMConfigError; } });
+Object.defineProperty(exports, "RLMSchemaError", { enumerable: true, get: function () { return errors_1.RLMSchemaError; } });
+Object.defineProperty(exports, "RLMContextOverflowError", { enumerable: true, get: function () { return errors_1.RLMContextOverflowError; } });
+Object.defineProperty(exports, "RLMAbortError", { enumerable: true, get: function () { return errors_1.RLMAbortError; } });
+Object.defineProperty(exports, "classifyError", { enumerable: true, get: function () { return errors_1.classifyError; } });
+// ─── Streaming ───────────────────────────────────────────────────────────────
+var streaming_1 = require("./streaming");
+Object.defineProperty(exports, "RLMStream", { enumerable: true, get: function () { return streaming_1.RLMStream; } });
+Object.defineProperty(exports, "createSimulatedStream", { enumerable: true, get: function () { return streaming_1.createSimulatedStream; } });
+// ─── Cache ───────────────────────────────────────────────────────────────────
+var cache_1 = require("./cache");
+Object.defineProperty(exports, "RLMCache", { enumerable: true, get: function () { return cache_1.RLMCache; } });
+Object.defineProperty(exports, "MemoryCache", { enumerable: true, get: function () { return cache_1.MemoryCache; } });
+Object.defineProperty(exports, "FileCache", { enumerable: true, get: function () { return cache_1.FileCache; } });
+// ─── Retry / Resilience ──────────────────────────────────────────────────────
+var retry_1 = require("./retry");
+Object.defineProperty(exports, "withRetry", { enumerable: true, get: function () { return retry_1.withRetry; } });
+Object.defineProperty(exports, "withFallback", { enumerable: true, get: function () { return retry_1.withFallback; } });
+// ─── Events ──────────────────────────────────────────────────────────────────
+var events_1 = require("./events");
+Object.defineProperty(exports, "RLMEventEmitter", { enumerable: true, get: function () { return events_1.RLMEventEmitter; } });
+// ─── Coordinator ─────────────────────────────────────────────────────────────
 var coordinator_1 = require("./coordinator");
 Object.defineProperty(exports, "RLMAgentCoordinator", { enumerable: true, get: function () { return coordinator_1.RLMAgentCoordinator; } });
+// ─── File Storage ────────────────────────────────────────────────────────────
 var file_storage_1 = require("./file-storage");
 Object.defineProperty(exports, "FileContextBuilder", { enumerable: true, get: function () { return file_storage_1.FileContextBuilder; } });
 Object.defineProperty(exports, "LocalFileStorage", { enumerable: true, get: function () { return file_storage_1.LocalFileStorage; } });

package/dist/retry.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Retry and resilience layer for recursive-llm-ts.
+ *
+ * Provides configurable retry with exponential backoff, jitter,
+ * and provider fallback chains.
+ */
+export interface RetryConfig {
+    /** Maximum number of retries (default: 3) */
+    maxRetries?: number;
+    /** Backoff strategy (default: 'exponential') */
+    backoff?: 'exponential' | 'linear' | 'fixed';
+    /** Base delay in milliseconds (default: 1000) */
+    baseDelay?: number;
+    /** Maximum delay in milliseconds (default: 30000) */
+    maxDelay?: number;
+    /** Add jitter to delays (default: true) */
+    jitter?: boolean;
+    /** Error types that should be retried */
+    retryableErrors?: string[];
+    /** Called before each retry with retry info */
+    onRetry?: (attempt: number, error: Error, delay: number) => void;
+}
+/** Fallback model configuration */
+export interface FallbackConfig {
+    /** Ordered list of fallback models to try */
+    models?: string[];
+    /** Strategy for fallback selection */
+    strategy?: 'sequential' | 'round-robin';
+}
+/**
+ * Execute a function with retry logic.
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   () => rlm.completion(query, context),
+ *   { maxRetries: 3, backoff: 'exponential' }
+ * );
+ * ```
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, config?: RetryConfig, signal?: AbortSignal): Promise<T>;
+/**
+ * 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'] }
+ * );
+ * ```
+ */
+export declare function withFallback<T>(fn: (model: string) => Promise<T>, fallbackConfig: FallbackConfig, retryConfig?: RetryConfig, signal?: AbortSignal): Promise<T & {
+    _usedModel?: string;
+}>;