recursive-llm-ts 4.4.1 → 4.6.0

package/dist/cache.js

@@ -0,0 +1,246 @@
+"use strict";
+/**
+ * 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.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RLMCache = exports.FileCache = exports.MemoryCache = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const crypto = __importStar(require("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 ─────────────────────────────────────────────────────────
+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;
+    }
+}
+exports.MemoryCache = MemoryCache;
+// ─── File-Based Cache ────────────────────────────────────────────────────────
+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;
+    }
+}
+exports.FileCache = FileCache;
+// ─── RLM Cache Manager ──────────────────────────────────────────────────────
+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;
+    }
+}
+exports.RLMCache = RLMCache;

package/dist/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/config.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * Configuration validation for recursive-llm-ts.
+ *
+ * Validates RLMConfig at construction time with clear error messages.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateConfig = validateConfig;
+exports.assertValidConfig = assertValidConfig;
+const errors_1 = require("./errors");
+// ─── Known Config Keys ───────────────────────────────────────────────────────
+const KNOWN_CONFIG_KEYS = new Set([
+    'recursive_model',
+    'api_base',
+    'api_key',
+    'max_depth',
+    'max_iterations',
+    'pythonia_timeout',
+    '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.
+ */
+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' });
+        }
+    }
+    if (config.pythonia_timeout !== undefined) {
+        if (typeof config.pythonia_timeout !== 'number' || config.pythonia_timeout < 0) {
+            issues.push({ level: 'error', field: 'pythonia_timeout', message: 'pythonia_timeout must be a non-negative number (milliseconds)' });
+        }
+    }
+    // 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.
+ */
+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 errors_1.RLMConfigError({
+            message: `Invalid RLM config: ${errors.map(e => e.message).join('; ')}`,
+            field: errors[0].field,
+            value: config[errors[0].field],
+        });
+    }
+}

package/dist/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;