recursive-llm-ts 5.0.2 → 5.2.3

package/dist/esm/bridge-interface.d.ts

@@ -0,0 +1,269 @@
+export interface RLMStats {
+    llm_calls: number;
+    iterations: number;
+    depth: number;
+    parsing_retries?: number;
+    total_tokens?: number;
+    prompt_tokens?: number;
+    completion_tokens?: number;
+}
+export interface RLMResult {
+    result: string;
+    stats: RLMStats;
+    structured_result?: boolean;
+    trace_events?: TraceEvent[];
+}
+export interface MetaAgentConfig {
+    enabled: boolean;
+    model?: string;
+    max_optimize_len?: number;
+}
+export interface ObservabilityConfig {
+    debug?: boolean;
+    trace_enabled?: boolean;
+    trace_endpoint?: string;
+    service_name?: string;
+    log_output?: string;
+    langfuse_enabled?: boolean;
+    langfuse_public_key?: string;
+    langfuse_secret_key?: string;
+    langfuse_host?: string;
+}
+export interface TraceEvent {
+    timestamp: string;
+    type: string;
+    name: string;
+    attributes: Record<string, string>;
+    duration?: number;
+    trace_id?: string;
+    span_id?: string;
+    parent_id?: string;
+}
+export interface ContextOverflowConfig {
+    /** Enable automatic context overflow recovery (default: true) */
+    enabled?: boolean;
+    /** Override detected model token limit (0 = auto-detect from API errors) */
+    max_model_tokens?: number;
+    /** Strategy: 'mapreduce' (default), 'truncate', 'chunked', 'tfidf', 'textrank', or 'refine' */
+    strategy?: 'mapreduce' | 'truncate' | 'chunked' | 'tfidf' | 'textrank' | 'refine';
+    /** Fraction of token budget to reserve for prompts/overhead (default: 0.15) */
+    safety_margin?: number;
+    /** Maximum reduction attempts before giving up (default: 3) */
+    max_reduction_attempts?: number;
+}
+export interface LCMConfig {
+    /** Enable LCM context management (default: false for backward compat) */
+    enabled?: boolean;
+    /** Soft token threshold — async compaction begins above this (default: 70% of model limit) */
+    soft_threshold?: number;
+    /** Hard token threshold — blocking compaction above this (default: 90% of model limit) */
+    hard_threshold?: number;
+    /** Number of messages to compact at once (default: 10) */
+    compaction_block_size?: number;
+    /** Target tokens per summary node (default: 500) */
+    summary_target_tokens?: number;
+    /** Large file handling configuration */
+    file_handling?: LCMFileConfig;
+    /** Episode-based context grouping configuration */
+    episodes?: EpisodeConfig;
+    /** Persistence backend configuration (default: in-memory) */
+    store_backend?: StoreBackendConfig;
+}
+export interface LCMFileConfig {
+    /** Token count above which files are stored externally with exploration summaries (default: 25000) */
+    token_threshold?: number;
+}
+export interface EpisodeConfig {
+    /** Max tokens before auto-closing an episode (default: 2000) */
+    max_episode_tokens?: number;
+    /** Max messages before auto-closing an episode (default: 20) */
+    max_episode_messages?: number;
+    /** Topic change sensitivity 0-1 (reserved for future semantic detection) */
+    topic_change_threshold?: number;
+    /** Auto-generate summary when episode closes (default: true) */
+    auto_compact_after_close?: boolean;
+}
+export interface Episode {
+    id: string;
+    title: string;
+    message_ids: string[];
+    start_time: string;
+    end_time: string;
+    tokens: number;
+    summary?: string;
+    summary_tokens?: number;
+    status: 'active' | 'compacted' | 'archived';
+    tags?: string[];
+    parent_episode_id?: string;
+}
+export interface StoreBackendConfig {
+    /** Backend type: 'memory' (default) or 'sqlite' */
+    type?: 'memory' | 'sqlite';
+    /** Path for SQLite database file (required when type is 'sqlite', use ':memory:' for in-memory SQLite) */
+    path?: string;
+}
+export interface LLMMapConfig {
+    /** Path to JSONL input file */
+    input_path: string;
+    /** Path to JSONL output file */
+    output_path: string;
+    /** Prompt template — use {{item}} as placeholder for each item */
+    prompt: string;
+    /** JSON Schema for output validation */
+    output_schema?: Record<string, any>;
+    /** Worker pool concurrency (default: 16) */
+    concurrency?: number;
+    /** Per-item retry limit (default: 3) */
+    max_retries?: number;
+    /** Model to use (defaults to engine model) */
+    model?: string;
+}
+export interface LLMMapResult {
+    total_items: number;
+    completed: number;
+    failed: number;
+    output_path: string;
+    duration_ms: number;
+    tokens_used: number;
+}
+export interface AgenticMapConfig {
+    /** Path to JSONL input file */
+    input_path: string;
+    /** Path to JSONL output file */
+    output_path: string;
+    /** Prompt template — use {{item}} as placeholder for each item */
+    prompt: string;
+    /** JSON Schema for output validation */
+    output_schema?: Record<string, any>;
+    /** Worker pool concurrency (default: 8) */
+    concurrency?: number;
+    /** Per-item retry limit (default: 2) */
+    max_retries?: number;
+    /** Model for sub-agents (defaults to engine model) */
+    model?: string;
+    /** If true, sub-agents cannot modify filesystem */
+    read_only?: boolean;
+    /** Max recursion depth for sub-agents (default: 3) */
+    max_depth?: number;
+    /** Max iterations per sub-agent (default: 15) */
+    max_iterations?: number;
+}
+export interface AgenticMapResult {
+    total_items: number;
+    completed: number;
+    failed: number;
+    output_path: string;
+    duration_ms: number;
+    tokens_used: number;
+}
+export interface DelegationRequest {
+    /** Task description for the sub-agent */
+    prompt: string;
+    /** Specific slice of work being handed off (required for non-root) */
+    delegated_scope?: string;
+    /** Work the caller retains (required for non-root) */
+    kept_work?: string;
+    /** Read-only exploration agent (exempt from guard) */
+    read_only?: boolean;
+    /** Parallel decomposition (exempt from guard) */
+    parallel?: boolean;
+}
+export interface LCMStoreStats {
+    total_messages: number;
+    total_summaries: number;
+    active_context_items: number;
+    active_context_tokens: number;
+    immutable_store_tokens: number;
+    compression_ratio: number;
+}
+export interface LCMGrepResult {
+    message_id: string;
+    role: string;
+    content: string;
+    summary_id?: string;
+    match_line: string;
+}
+export interface LCMDescribeResult {
+    type: 'message' | 'summary';
+    id: string;
+    tokens: number;
+    role?: string;
+    kind?: 'leaf' | 'condensed';
+    level?: number;
+    covered_ids?: string[];
+    file_ids?: string[];
+    content?: string;
+}
+export interface EpisodeListResult {
+    episodes: Episode[];
+    active_episode_id?: string;
+    total_episodes: number;
+}
+export interface RLMConfig {
+    recursive_model?: string;
+    api_base?: string;
+    api_key?: string;
+    max_depth?: number;
+    max_iterations?: number;
+    go_binary_path?: string;
+    meta_agent?: MetaAgentConfig;
+    observability?: ObservabilityConfig;
+    context_overflow?: ContextOverflowConfig;
+    lcm?: LCMConfig;
+    debug?: boolean;
+    api_version?: string;
+    timeout?: number;
+    temperature?: number;
+    max_tokens?: number;
+    structured?: any;
+    [key: string]: any;
+}
+export interface FileStorageConfig {
+    /** Storage type: 'local' or 's3' */
+    type: 'local' | 's3';
+    /** For local: root directory path. For S3: bucket name */
+    path: string;
+    /** For S3: the prefix (folder path) within the bucket */
+    prefix?: string;
+    /** For S3: AWS region (falls back to AWS_REGION env var, then 'us-east-1') */
+    region?: string;
+    /**
+     * For S3: explicit credentials.
+     * Resolution order:
+     * 1. This field (explicit credentials)
+     * 2. Environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN
+     * 3. AWS SDK default credential chain (IAM role, ~/.aws/credentials, ECS task role, etc.)
+     */
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+        sessionToken?: string;
+    };
+    /**
+     * For S3: custom endpoint URL.
+     * Use for S3-compatible services: MinIO, LocalStack, DigitalOcean Spaces, Backblaze B2.
+     * When set, forcePathStyle is automatically enabled.
+     */
+    endpoint?: string;
+    /**
+     * For S3: force path-style addressing (bucket in path, not subdomain).
+     * Automatically true when endpoint is set.
+     */
+    forcePathStyle?: boolean;
+    /** Glob patterns to include (e.g. ['*.ts', '*.md']) */
+    includePatterns?: string[];
+    /** Glob patterns to exclude (e.g. ['node_modules/**']) */
+    excludePatterns?: string[];
+    /** Maximum file size in bytes to include (default: 1MB) */
+    maxFileSize?: number;
+    /** Maximum total context size in bytes (default: 10MB) */
+    maxTotalSize?: number;
+    /** Maximum number of files to include (default: 1000) */
+    maxFiles?: number;
+    /** File extensions to include (e.g. ['.ts', '.md', '.txt']) */
+    extensions?: string[];
+}
+export interface Bridge {
+    completion(model: string, query: string, context: string, rlmConfig: RLMConfig): Promise<RLMResult>;
+    cleanup(): Promise<void>;
+}

package/dist/esm/bridge-interface.js

@@ -0,0 +1 @@
+export {};

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;