recursive-llm-ts 5.1.1 → 5.2.4

package/dist/esm/cache.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Caching layer for recursive-llm-ts completions.
+ *
+ * Provides exact-match caching to avoid redundant API calls for
+ * identical query+context pairs. Supports in-memory and file-based storage.
+ */
+export interface CacheConfig {
+    /** Enable/disable caching (default: false) */
+    enabled?: boolean;
+    /** Cache strategy (default: 'exact') */
+    strategy?: 'exact' | 'none';
+    /** Maximum number of cached entries (default: 1000) */
+    maxEntries?: number;
+    /** Time-to-live in seconds (default: 3600 = 1 hour) */
+    ttl?: number;
+    /** Storage backend (default: 'memory') */
+    storage?: 'memory' | 'file';
+    /** Directory for file-based cache (default: .rlm-cache) */
+    cacheDir?: string;
+}
+export interface CacheStats {
+    hits: number;
+    misses: number;
+    size: number;
+    hitRate: number;
+    evictions: number;
+}
+export interface CacheProvider {
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T, ttl: number): void;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    clear(): void;
+    size(): number;
+}
+export declare class MemoryCache implements CacheProvider {
+    private store;
+    private maxEntries;
+    constructor(maxEntries?: number);
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T, ttl: number): void;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    clear(): void;
+    size(): number;
+}
+export declare class FileCache implements CacheProvider {
+    private cacheDir;
+    private maxEntries;
+    constructor(cacheDir?: string, maxEntries?: number);
+    private filePath;
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T, ttl: number): void;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    clear(): void;
+    size(): number;
+}
+export declare class RLMCache {
+    private provider;
+    private config;
+    private stats;
+    constructor(config?: CacheConfig);
+    /** Check if caching is enabled */
+    get enabled(): boolean;
+    /** Look up a cached result */
+    lookup<T>(model: string, query: string, context: string, extra?: Record<string, unknown>): {
+        hit: boolean;
+        value?: T;
+    };
+    /** Store a result in the cache */
+    store<T>(model: string, query: string, context: string, value: T, extra?: Record<string, unknown>): void;
+    /** Get cache statistics */
+    getStats(): CacheStats;
+    /** Clear the cache */
+    clear(): void;
+    private updateHitRate;
+}

package/dist/esm/cache.js

@@ -0,0 +1,207 @@
+/**
+ * Caching layer for recursive-llm-ts completions.
+ *
+ * Provides exact-match caching to avoid redundant API calls for
+ * identical query+context pairs. Supports in-memory and file-based storage.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as crypto from 'crypto';
+// ─── Cache Key Generator ─────────────────────────────────────────────────────
+function generateCacheKey(model, query, context, config) {
+    const data = JSON.stringify({ model, query, context, config });
+    return crypto.createHash('sha256').update(data).digest('hex');
+}
+// ─── In-Memory Cache ─────────────────────────────────────────────────────────
+export class MemoryCache {
+    constructor(maxEntries = 1000) {
+        this.store = new Map();
+        this.maxEntries = maxEntries;
+    }
+    get(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return undefined;
+        // Check TTL
+        if (Date.now() - entry.createdAt > entry.ttl * 1000) {
+            this.store.delete(key);
+            return undefined;
+        }
+        entry.hitCount++;
+        return entry.value;
+    }
+    set(key, value, ttl) {
+        // Evict oldest if at capacity
+        if (this.store.size >= this.maxEntries && !this.store.has(key)) {
+            const oldestKey = this.store.keys().next().value;
+            if (oldestKey !== undefined) {
+                this.store.delete(oldestKey);
+            }
+        }
+        this.store.set(key, {
+            key,
+            value,
+            createdAt: Date.now(),
+            ttl,
+            hitCount: 0,
+        });
+    }
+    has(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return false;
+        if (Date.now() - entry.createdAt > entry.ttl * 1000) {
+            this.store.delete(key);
+            return false;
+        }
+        return true;
+    }
+    delete(key) {
+        return this.store.delete(key);
+    }
+    clear() {
+        this.store.clear();
+    }
+    size() {
+        // Clean expired entries
+        const now = Date.now();
+        for (const [key, entry] of this.store) {
+            if (now - entry.createdAt > entry.ttl * 1000) {
+                this.store.delete(key);
+            }
+        }
+        return this.store.size;
+    }
+}
+// ─── File-Based Cache ────────────────────────────────────────────────────────
+export class FileCache {
+    constructor(cacheDir = '.rlm-cache', maxEntries = 1000) {
+        this.cacheDir = path.resolve(cacheDir);
+        this.maxEntries = maxEntries;
+        if (!fs.existsSync(this.cacheDir)) {
+            fs.mkdirSync(this.cacheDir, { recursive: true });
+        }
+    }
+    filePath(key) {
+        return path.join(this.cacheDir, `${key}.json`);
+    }
+    get(key) {
+        const fp = this.filePath(key);
+        if (!fs.existsSync(fp))
+            return undefined;
+        try {
+            const data = JSON.parse(fs.readFileSync(fp, 'utf-8'));
+            if (Date.now() - data.createdAt > data.ttl * 1000) {
+                fs.unlinkSync(fp);
+                return undefined;
+            }
+            return data.value;
+        }
+        catch (_a) {
+            return undefined;
+        }
+    }
+    set(key, value, ttl) {
+        const entry = {
+            key,
+            value,
+            createdAt: Date.now(),
+            ttl,
+            hitCount: 0,
+        };
+        try {
+            fs.writeFileSync(this.filePath(key), JSON.stringify(entry), 'utf-8');
+        }
+        catch (_a) {
+            // Silently fail on write errors
+        }
+    }
+    has(key) {
+        return this.get(key) !== undefined;
+    }
+    delete(key) {
+        const fp = this.filePath(key);
+        if (fs.existsSync(fp)) {
+            fs.unlinkSync(fp);
+            return true;
+        }
+        return false;
+    }
+    clear() {
+        if (fs.existsSync(this.cacheDir)) {
+            const files = fs.readdirSync(this.cacheDir);
+            for (const file of files) {
+                if (file.endsWith('.json')) {
+                    fs.unlinkSync(path.join(this.cacheDir, file));
+                }
+            }
+        }
+    }
+    size() {
+        if (!fs.existsSync(this.cacheDir))
+            return 0;
+        return fs.readdirSync(this.cacheDir).filter(f => f.endsWith('.json')).length;
+    }
+}
+// ─── RLM Cache Manager ──────────────────────────────────────────────────────
+export class RLMCache {
+    constructor(config = {}) {
+        var _a, _b, _c, _d, _e, _f;
+        this.stats = { hits: 0, misses: 0, size: 0, hitRate: 0, evictions: 0 };
+        this.config = {
+            enabled: (_a = config.enabled) !== null && _a !== void 0 ? _a : false,
+            strategy: (_b = config.strategy) !== null && _b !== void 0 ? _b : 'exact',
+            maxEntries: (_c = config.maxEntries) !== null && _c !== void 0 ? _c : 1000,
+            ttl: (_d = config.ttl) !== null && _d !== void 0 ? _d : 3600,
+            storage: (_e = config.storage) !== null && _e !== void 0 ? _e : 'memory',
+            cacheDir: (_f = config.cacheDir) !== null && _f !== void 0 ? _f : '.rlm-cache',
+        };
+        if (this.config.storage === 'file') {
+            this.provider = new FileCache(this.config.cacheDir, this.config.maxEntries);
+        }
+        else {
+            this.provider = new MemoryCache(this.config.maxEntries);
+        }
+    }
+    /** Check if caching is enabled */
+    get enabled() {
+        return this.config.enabled && this.config.strategy !== 'none';
+    }
+    /** Look up a cached result */
+    lookup(model, query, context, extra) {
+        if (!this.enabled)
+            return { hit: false };
+        const key = generateCacheKey(model, query, context, extra);
+        const value = this.provider.get(key);
+        if (value !== undefined) {
+            this.stats.hits++;
+            this.updateHitRate();
+            return { hit: true, value };
+        }
+        this.stats.misses++;
+        this.updateHitRate();
+        return { hit: false };
+    }
+    /** Store a result in the cache */
+    store(model, query, context, value, extra) {
+        if (!this.enabled)
+            return;
+        const key = generateCacheKey(model, query, context, extra);
+        this.provider.set(key, value, this.config.ttl);
+        this.stats.size = this.provider.size();
+    }
+    /** Get cache statistics */
+    getStats() {
+        this.stats.size = this.provider.size();
+        return Object.assign({}, this.stats);
+    }
+    /** Clear the cache */
+    clear() {
+        this.provider.clear();
+        this.stats = { hits: 0, misses: 0, size: 0, hitRate: 0, evictions: 0 };
+    }
+    updateHitRate() {
+        const total = this.stats.hits + this.stats.misses;
+        this.stats.hitRate = total > 0 ? this.stats.hits / total : 0;
+    }
+}

package/dist/esm/config.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Configuration validation for recursive-llm-ts.
+ *
+ * Validates RLMConfig at construction time with clear error messages.
+ */
+import { RLMConfig } from './bridge-interface';
+import { CacheConfig } from './cache';
+import { RetryConfig, FallbackConfig } from './retry';
+export interface RLMExtendedConfig extends RLMConfig {
+    /** Cache configuration */
+    cache?: CacheConfig;
+    /** Retry configuration */
+    retry?: RetryConfig;
+    /** Fallback model configuration */
+    fallback?: FallbackConfig;
+    /** LiteLLM passthrough parameters */
+    litellm_params?: Record<string, unknown>;
+}
+export type ValidationLevel = 'error' | 'warning' | 'info';
+export interface ValidationIssue {
+    level: ValidationLevel;
+    field: string;
+    message: string;
+}
+export interface ValidationResult {
+    valid: boolean;
+    issues: ValidationIssue[];
+}
+/**
+ * Validate an RLM configuration.
+ * Returns issues rather than throwing, allowing callers to handle gracefully.
+ */
+export declare function validateConfig(config: RLMExtendedConfig): ValidationResult;
+/**
+ * Validate config and throw on errors. Logs warnings.
+ */
+export declare function assertValidConfig(config: RLMExtendedConfig): void;

package/dist/esm/config.js

@@ -0,0 +1,152 @@
+/**
+ * Configuration validation for recursive-llm-ts.
+ *
+ * Validates RLMConfig at construction time with clear error messages.
+ */
+import { RLMConfigError } from './errors.js';
+// ─── Known Config Keys ───────────────────────────────────────────────────────
+const KNOWN_CONFIG_KEYS = new Set([
+    'recursive_model',
+    'api_base',
+    'api_key',
+    'max_depth',
+    'max_iterations',
+    'go_binary_path',
+    'meta_agent',
+    'observability',
+    'debug',
+    'cache',
+    'retry',
+    'fallback',
+    'litellm_params',
+    // Legacy LiteLLM passthrough keys (commonly used)
+    'api_version',
+    'timeout',
+    'temperature',
+    'max_tokens',
+]);
+// ─── Config Validator ────────────────────────────────────────────────────────
+/**
+ * Validate an RLM configuration.
+ * Returns issues rather than throwing, allowing callers to handle gracefully.
+ */
+export function validateConfig(config) {
+    const issues = [];
+    // Check for unknown keys (likely typos)
+    for (const key of Object.keys(config)) {
+        if (!KNOWN_CONFIG_KEYS.has(key)) {
+            issues.push({
+                level: 'warning',
+                field: key,
+                message: `Unknown config key "${key}". This may be a typo. Known keys: ${Array.from(KNOWN_CONFIG_KEYS).join(', ')}`,
+            });
+        }
+    }
+    // Validate numeric fields
+    if (config.max_depth !== undefined) {
+        if (typeof config.max_depth !== 'number' || config.max_depth < 1) {
+            issues.push({ level: 'error', field: 'max_depth', message: 'max_depth must be a positive integer' });
+        }
+    }
+    if (config.max_iterations !== undefined) {
+        if (typeof config.max_iterations !== 'number' || config.max_iterations < 1) {
+            issues.push({ level: 'error', field: 'max_iterations', message: 'max_iterations must be a positive integer' });
+        }
+    }
+    // Validate API base URL
+    if (config.api_base !== undefined && typeof config.api_base === 'string') {
+        try {
+            new URL(config.api_base);
+        }
+        catch (_a) {
+            issues.push({ level: 'error', field: 'api_base', message: `api_base "${config.api_base}" is not a valid URL` });
+        }
+    }
+    // Validate meta_agent config
+    if (config.meta_agent) {
+        if (typeof config.meta_agent.enabled !== 'boolean') {
+            issues.push({ level: 'error', field: 'meta_agent.enabled', message: 'meta_agent.enabled must be a boolean' });
+        }
+        if (config.meta_agent.max_optimize_len !== undefined) {
+            if (typeof config.meta_agent.max_optimize_len !== 'number' || config.meta_agent.max_optimize_len < 0) {
+                issues.push({ level: 'error', field: 'meta_agent.max_optimize_len', message: 'max_optimize_len must be a non-negative number' });
+            }
+        }
+    }
+    // Validate observability config
+    if (config.observability) {
+        const obs = config.observability;
+        if (obs.trace_enabled && !obs.trace_endpoint) {
+            issues.push({
+                level: 'warning',
+                field: 'observability.trace_endpoint',
+                message: 'trace_enabled is true but no trace_endpoint is configured. Traces will not be exported.',
+            });
+        }
+        if (obs.langfuse_enabled) {
+            if (!obs.langfuse_public_key && !process.env.LANGFUSE_PUBLIC_KEY) {
+                issues.push({
+                    level: 'warning',
+                    field: 'observability.langfuse_public_key',
+                    message: 'langfuse_enabled is true but no public key is set (config or LANGFUSE_PUBLIC_KEY env var).',
+                });
+            }
+            if (!obs.langfuse_secret_key && !process.env.LANGFUSE_SECRET_KEY) {
+                issues.push({
+                    level: 'warning',
+                    field: 'observability.langfuse_secret_key',
+                    message: 'langfuse_enabled is true but no secret key is set (config or LANGFUSE_SECRET_KEY env var).',
+                });
+            }
+        }
+    }
+    // Validate cache config
+    if (config.cache) {
+        if (config.cache.maxEntries !== undefined && (typeof config.cache.maxEntries !== 'number' || config.cache.maxEntries < 1)) {
+            issues.push({ level: 'error', field: 'cache.maxEntries', message: 'cache.maxEntries must be a positive integer' });
+        }
+        if (config.cache.ttl !== undefined && (typeof config.cache.ttl !== 'number' || config.cache.ttl < 0)) {
+            issues.push({ level: 'error', field: 'cache.ttl', message: 'cache.ttl must be a non-negative number (seconds)' });
+        }
+    }
+    // Validate retry config
+    if (config.retry) {
+        if (config.retry.maxRetries !== undefined && (typeof config.retry.maxRetries !== 'number' || config.retry.maxRetries < 0)) {
+            issues.push({ level: 'error', field: 'retry.maxRetries', message: 'retry.maxRetries must be a non-negative integer' });
+        }
+        if (config.retry.baseDelay !== undefined && (typeof config.retry.baseDelay !== 'number' || config.retry.baseDelay < 0)) {
+            issues.push({ level: 'error', field: 'retry.baseDelay', message: 'retry.baseDelay must be a non-negative number (ms)' });
+        }
+    }
+    // Check for missing API key
+    if (!config.api_key && !process.env.OPENAI_API_KEY) {
+        issues.push({
+            level: 'info',
+            field: 'api_key',
+            message: 'No API key configured (api_key or OPENAI_API_KEY env var). Ensure it is set before making completions.',
+        });
+    }
+    return {
+        valid: issues.filter(i => i.level === 'error').length === 0,
+        issues,
+    };
+}
+/**
+ * Validate config and throw on errors. Logs warnings.
+ */
+export function assertValidConfig(config) {
+    const result = validateConfig(config);
+    for (const issue of result.issues) {
+        if (issue.level === 'warning') {
+            console.warn(`[recursive-llm-ts] Warning: ${issue.message}`);
+        }
+    }
+    const errors = result.issues.filter(i => i.level === 'error');
+    if (errors.length > 0) {
+        throw new RLMConfigError({
+            message: `Invalid RLM config: ${errors.map(e => e.message).join('; ')}`,
+            field: errors[0].field,
+            value: config[errors[0].field],
+        });
+    }
+}

package/dist/esm/coordinator.d.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import { RLMConfig } from './bridge-interface';
+import { BridgeType } from './bridge-factory';
+import { StructuredRLMResult, CoordinatorConfig } from './structured-types';
+export declare class RLMAgentCoordinator {
+    private rlm;
+    private config;
+    constructor(model: string, rlmConfig?: RLMConfig, bridgeType?: BridgeType, coordinatorConfig?: CoordinatorConfig);
+    /**
+     * Process a complex query with structured output using schema decomposition
+     */
+    processComplex<T>(query: string, context: string, schema: z.ZodSchema<T>): Promise<StructuredRLMResult<T>>;
+    /**
+     * Clean up resources
+     */
+    cleanup(): Promise<void>;
+}

package/dist/esm/coordinator.js

@@ -0,0 +1,41 @@
+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());
+    });
+};
+import { RLM } from './rlm.js';
+export class RLMAgentCoordinator {
+    constructor(model, rlmConfig = {}, bridgeType = 'go', coordinatorConfig = {}) {
+        var _a, _b, _c;
+        this.rlm = new RLM(model, rlmConfig, bridgeType);
+        this.config = {
+            parallelExecution: (_a = coordinatorConfig.parallelExecution) !== null && _a !== void 0 ? _a : true,
+            maxRetries: (_b = coordinatorConfig.maxRetries) !== null && _b !== void 0 ? _b : 3,
+            progressiveValidation: (_c = coordinatorConfig.progressiveValidation) !== null && _c !== void 0 ? _c : true
+        };
+    }
+    /**
+     * Process a complex query with structured output using schema decomposition
+     */
+    processComplex(query, context, schema) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Delegate to RLM which now handles everything in Go
+            return this.rlm.structuredCompletion(query, context, schema, {
+                maxRetries: this.config.maxRetries,
+                parallelExecution: this.config.parallelExecution
+            });
+        });
+    }
+    /**
+     * Clean up resources
+     */
+    cleanup() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.rlm.cleanup();
+        });
+    }
+}

package/dist/esm/errors.d.ts

@@ -0,0 +1,113 @@
+/**
+ * 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
+ */
+export declare class RLMError extends Error {
+    /** Machine-readable error code (e.g. "RATE_LIMIT", "VALIDATION") */
+    readonly code: string;
+    /** Whether this error is likely to succeed on retry */
+    readonly retryable: boolean;
+    /** Human-readable suggestion for resolving the error */
+    readonly suggestion?: string;
+    constructor(message: string, opts: {
+        code: string;
+        retryable?: boolean;
+        suggestion?: string;
+    });
+}
+/** Thrown when a structured output fails schema validation. */
+export declare class RLMValidationError extends RLMError {
+    readonly expected: unknown;
+    readonly received: unknown;
+    readonly zodErrors?: unknown;
+    constructor(opts: {
+        message: string;
+        expected: unknown;
+        received: unknown;
+        zodErrors?: unknown;
+    });
+}
+/** Thrown when the LLM provider returns a 429 rate limit response. */
+export declare class RLMRateLimitError extends RLMError {
+    readonly retryAfter?: number;
+    constructor(opts: {
+        message: string;
+        retryAfter?: number;
+    });
+}
+/** Thrown when an operation exceeds its time limit. */
+export declare class RLMTimeoutError extends RLMError {
+    readonly elapsed: number;
+    readonly limit: number;
+    constructor(opts: {
+        message: string;
+        elapsed: number;
+        limit: number;
+    });
+}
+/** Thrown when the LLM provider returns an HTTP error. */
+export declare class RLMProviderError extends RLMError {
+    readonly statusCode: number;
+    readonly provider: string;
+    readonly responseBody?: string;
+    constructor(opts: {
+        message: string;
+        statusCode: number;
+        provider: string;
+        responseBody?: string;
+    });
+}
+/** Thrown when the Go binary cannot be found or fails to start. */
+export declare class RLMBinaryError extends RLMError {
+    readonly binaryPath: string;
+    constructor(opts: {
+        message: string;
+        binaryPath: string;
+    });
+}
+/** Thrown when the RLM configuration is invalid. */
+export declare class RLMConfigError extends RLMError {
+    readonly field: string;
+    readonly value: unknown;
+    constructor(opts: {
+        message: string;
+        field: string;
+        value: unknown;
+    });
+}
+/** Thrown when a JSON Schema is malformed or unsupported. */
+export declare class RLMSchemaError extends RLMError {
+    readonly path: string;
+    readonly constraint: string;
+    constructor(opts: {
+        message: string;
+        path: string;
+        constraint: string;
+    });
+}
+/** Thrown when the request exceeds the model's context window. */
+export declare class RLMContextOverflowError extends RLMError {
+    readonly modelLimit: number;
+    readonly requestTokens: number;
+    constructor(opts: {
+        message: string;
+        modelLimit: number;
+        requestTokens: number;
+    });
+}
+/** Thrown when an operation is aborted via AbortController. */
+export declare class RLMAbortError extends RLMError {
+    constructor(message?: string);
+}
+/**
+ * Classify a raw Error into the appropriate RLM error type.
+ * Used internally by the bridge layer to wrap Go binary errors.
+ */
+export declare function classifyError(err: Error | string, context?: {
+    binaryPath?: string;
+    provider?: string;
+}): RLMError;