API Reference

Complete reference for all classes, methods, and types exported by recursive-llm-ts.

RLM

Main class for recursive language model completions. Manages the Go binary bridge and provides methods for processing queries with unbounded context.

constructor(model, rlmConfig?, bridgeType?)

Create a new RLM instance.

ParameterTypeDescription
model string LLM model identifier (e.g., 'gpt-4o-mini', 'claude-3-sonnet')
rlmConfig RLMConfig Optional configuration object
bridgeType BridgeType Optional bridge selection: 'go' | 'pythonia' | 'bunpy' | 'auto'. Defaults to 'auto' (prefers Go)
completion(query, context) async

Process a query with the given context using recursive language models. The context can be arbitrarily large — it will be recursively decomposed.

ParameterTypeDescription
query string The question or task to perform
context string The document/context to process (any size)
Returns
Promise<RLMResult>
structuredCompletion<T>(query, context, schema, options?) async generic

Extract structured, typed data from context using a Zod schema. Supports complex nested objects, arrays, enums, and constraints. Automatically validates and retries on schema mismatch.

ParameterTypeDescription
query string The extraction task
context string The document to extract from
schema ZodSchema<T> Zod schema defining the output structure
options.parallelExecution boolean Enable parallel processing of schema fields (default: true)
options.maxRetries number Max validation retries per field (default: 3)
Returns
Promise<StructuredRLMResult<T>>
completionFromFiles(query, fileConfig) async

Process a query using files from local or S3 storage as context. Recursively traverses directories, applies filters, and builds context automatically.

ParameterTypeDescription
query string The question or task
fileConfig FileStorageConfig File storage configuration
Returns
Promise<RLMResult & { fileStorage?: FileStorageResult }>
structuredCompletionFromFiles<T>(query, fileConfig, schema, options?) async generic

Extract structured data from file-based context. Combines file traversal with Zod schema extraction.

ParameterTypeDescription
query string The extraction task
fileConfig FileStorageConfig File storage configuration
schema ZodSchema<T> Zod schema for output
options object Same as structuredCompletion options
Returns
Promise<StructuredRLMResult<T> & { fileStorage?: FileStorageResult }>
getTraceEvents()

Returns trace events from the last operation. Only populated when observability is enabled.

Returns
TraceEvent[]
cleanup() async

Clean up the bridge and free resources. Call this when done with the RLM instance.

Returns
Promise<void>
streamCompletion(query, context, signal?) async

Stream a completion as an async iterable of chunks. Each chunk contains either text or metadata.

ParameterTypeDescription
query string The question or task to perform
context string The document/context to process
signal AbortSignal Optional abort signal for cancellation
Returns
Promise<RLMStream<string>>
streamStructuredCompletion<T>(query, context, schema, options?) async generic

Stream a structured completion. Returns partial objects as they are built.

Returns
Promise<RLMStream<T>>
batchCompletion(items, options?) async

Process multiple completion requests concurrently with configurable concurrency limits.

ParameterTypeDescription
items Array<{query, context}> Array of query/context pairs
options.concurrency number Max parallel requests (default: 3)
Returns
Promise<RLMCompletionResult[]>
on(event, handler)

Subscribe to lifecycle events. Available events: llm_call, llm_response, error, cache, retry, completion_start, completion_end, validation_retry, recursion, meta_agent.

Returns
void
off(event, handler)

Remove a previously registered event handler.

Returns
void
once(event, handler)

Subscribe to an event for a single emission only.

Returns
void
validate()

Validate the current configuration and return issues with severity levels.

Returns
ValidationResult — { valid: boolean, issues: ValidationIssue[] }
getCacheStats()

Get current cache statistics including hits, misses, hit rate, and eviction count.

Returns
CacheStats | null
clearCache()

Clear all cached responses.

Returns
void
formatResult(result)

Create a result formatter for pretty printing, JSON export, or Markdown generation.

Returns
RLMResultFormatter — with .prettyStats(), .toJSON(), .toMarkdown() methods

Static Factory Methods

RLM.fromEnv(model?) static

Create an RLM instance using environment variables for configuration. Auto-detects OPENAI_API_KEY, RLM_DEBUG, etc.

Returns
RLM
RLM.withDebug(model?) static

Quick setup with debug logging enabled. Uses environment variables for API key.

Returns
RLM
RLM.forAzure(model, endpoint, apiKey) static

Create an RLM instance pre-configured for Azure OpenAI deployments.

Returns
RLM
RLM.builder() static

Create a fluent builder for step-by-step configuration. See RLMBuilder.

Returns
RLMBuilder

RLMAgentCoordinator

Advanced coordinator for complex multi-field schema extraction. Wraps RLM with schema decomposition and parallel processing.

constructor(model, rlmConfig?, bridgeType?, coordinatorConfig?)
ParameterTypeDescription
model string LLM model identifier
rlmConfig RLMConfig Optional RLM configuration
bridgeType BridgeType Bridge selection
coordinatorConfig CoordinatorConfig Coordinator options (e.g., { parallelExecution: true })
processComplex<T>(query, context, schema) async generic

Process a complex extraction task with schema decomposition.

Returns
Promise<StructuredRLMResult<T>>

FileContextBuilder

Utility for building LLM context from file trees. Supports local filesystem and S3-compatible storage.

constructor(config)
ParameterTypeDescription
config FileStorageConfig File storage configuration
listMatchingFiles() async

List files that match the configuration filters without reading their content. Useful for previewing what will be processed.

Returns
Promise<string[]>
buildContext() async

Build the full context string from matching files. Includes file contents with delimiters.

Returns
Promise<FileStorageResult>

RLMBuilder

Fluent builder for constructing RLM instances with complex configuration. All methods return this for chaining.

TypeScript
class RLMBuilder {
  model(model: string): this;
  apiKey(key: string): this;
  apiBase(base: string): this;
  maxDepth(depth: number): this;
  maxIterations(iterations: number): this;
  enableMetaAgent(model?: string): this;
  enableDebug(): this;
  enableCache(config?: Partial<CacheConfig>): this;
  enableRetry(config?: Partial<RetryConfig>): this;
  withContextOverflow(config?: Partial<ContextOverflowConfig>): this;
  build(): RLM;
}

RLMConfig

Configuration object for the RLM constructor.

PropertyTypeDefaultDescription
api_key string OPENAI_API_KEY env API key for LLM provider
api_base string OpenAI default Custom API endpoint URL (Azure, vLLM, etc.)
max_depth number 5 Maximum recursion depth
max_iterations number 30 Maximum REPL iterations per call
recursive_model string same as model Cheaper model for recursive calls
go_binary_path string auto-detected Override path to Go binary
meta_agent MetaAgentConfig — Meta-agent configuration
observability ObservabilityConfig — Observability configuration
debug boolean false Shorthand for observability.debug
temperature number — LLM sampling temperature
max_tokens number — Maximum tokens in response
timeout number — Request timeout in seconds
cache CacheConfig — Response caching configuration
retry RetryConfig — Retry configuration with backoff
fallback FallbackConfig — Multi-provider fallback chain
context_overflow ContextOverflowConfig enabled Context overflow recovery configuration
[key: string] any — Passthrough params for LiteLLM (e.g., custom_llm_provider, top_p)

MetaAgentConfig

Configuration for the query optimization meta-agent.

PropertyTypeDefaultDescription
enabled boolean false Enable the meta-agent
model string main model Model for query optimization
max_optimize_len number 0 Max context length before optimization (0 = always)

ObservabilityConfig

Configuration for tracing, logging, and observability integrations.

PropertyTypeDefaultDescription
debug boolean false Enable verbose debug logging
trace_enabled boolean false Enable OpenTelemetry tracing
trace_endpoint string — OTLP/HTTP endpoint (e.g., "http://localhost:4318")
service_name string "rlm" Service name for traces
log_output string "stderr" Log destination: "stderr", "stdout", or file path
langfuse_enabled boolean false Enable Langfuse integration
langfuse_public_key string — Langfuse public key
langfuse_secret_key string — Langfuse secret key
langfuse_host string "https://cloud.langfuse.com" Langfuse API host

FileStorageConfig

Configuration for file-based context building. Supports local filesystem and S3-compatible storage.

PropertyTypeDefaultDescription
type 'local' | 's3' — Storage provider type (required)
path string — Local dir path or S3 bucket name (required)
prefix string — S3 key prefix (folder path)
region string 'us-east-1' AWS region
credentials object — { accessKeyId, secretAccessKey, sessionToken? }
endpoint string — Custom S3 endpoint (MinIO, LocalStack)
forcePathStyle boolean auto Force path-style URLs (auto with custom endpoint)
extensions string[] all File extensions to include (e.g., ['.ts', '.md'])
includePatterns string[] — Glob patterns to include
excludePatterns string[] — Glob patterns to exclude
maxFileSize number 1048576 (1MB) Max individual file size in bytes
maxTotalSize number 10485760 (10MB) Max total context size in bytes
maxFiles number 1000 Max number of files to include

ContextOverflowConfig

Configuration for automatic context overflow recovery. Enabled by default.

PropertyTypeDefaultDescription
enabled boolean true Enable automatic overflow recovery
strategy string 'mapreduce' Reduction strategy: 'mapreduce', 'truncate', 'chunked', 'tfidf', 'textrank', or 'refine'
safety_margin number 0.15 Fraction of token budget reserved for prompts/overhead (0.0–1.0)
max_reduction_attempts number 3 Maximum reduction retries before failing
max_model_tokens number 0 Override model token limit (0 = auto-detect from API errors)

LCMConfig

Configuration for Lossless Context Management. New in v5.0.

LCMConfig
PropertyTypeDescription
enabledbooleanEnable LCM context management (default: false)
soft_thresholdnumberAsync compaction begins above this token count (default: 70% of model limit)
hard_thresholdnumberBlocking compaction above this (default: 90% of model limit)
compaction_block_sizenumberMessages to compact at once (default: 10)
summary_target_tokensnumberTarget tokens per summary node (default: 500)
episodesEpisodeConfigEpisode-based context grouping config
store_backendStoreBackendConfigPersistence backend config

EpisodeConfig

EpisodeConfig
PropertyTypeDescription
max_episode_tokensnumberAuto-close episode above this (default: 2000)
max_episode_messagesnumberAuto-close episode above this (default: 20)
auto_compact_after_closebooleanGenerate summary when episode closes (default: true)

StoreBackendConfig

StoreBackendConfig
PropertyTypeDescription
type'memory' | 'sqlite'Backend type (default: 'memory')
pathstringSQLite database path (required for 'sqlite', use ':memory:' for in-memory)

LLMMapConfig

Configuration for parallel batch processing via LLM-Map operator.

LLMMapConfig
PropertyTypeDescription
input_pathstringPath to JSONL input file
output_pathstringPath to JSONL output file
promptstringPrompt template — use {{item}} placeholder
output_schemaobjectJSON Schema for per-item output validation
concurrencynumberWorker pool size (default: 16)
max_retriesnumberPer-item retry limit (default: 3)

AgenticMapConfig

Configuration for sub-agent batch processing via Agentic-Map operator.

AgenticMapConfig
PropertyTypeDescription
input_pathstringPath to JSONL input file
output_pathstringPath to JSONL output file
promptstringPrompt template — use {{item}} placeholder
concurrencynumberWorker pool size (default: 8)
read_onlybooleanSub-agents cannot modify filesystem
max_depthnumberMax recursion depth per sub-agent (default: 3)
max_iterationsnumberMax iterations per sub-agent (default: 15)

DelegationRequest

Request structure for task delegation with infinite recursion guard.

DelegationRequest
PropertyTypeDescription
promptstringTask description for the sub-agent
delegated_scopestringSpecific slice of work being handed off
kept_workstringWork the caller retains (must be non-trivial)
read_onlybooleanRead-only exploration agent (exempt from guard)
parallelbooleanParallel decomposition (exempt from guard)

RLMResult

Return type for completion() and completionFromFiles().

TypeScript
interface RLMResult {
  result: string;                // The answer
  stats: RLMStats;               // Execution statistics
  trace_events?: TraceEvent[];   // Observability events (when enabled)
}

RLMStats

TypeScript
interface RLMStats {
  llm_calls: number;         // Total LLM API calls made
  iterations: number;        // Total REPL iterations
  depth: number;             // Maximum recursion depth reached
  parsing_retries?: number;  // Schema validation retries (structured)
}

StructuredRLMResult<T>

TypeScript
interface StructuredRLMResult<T> {
  result: T;                     // Typed result matching your Zod schema
  stats: RLMStats;               // Execution statistics
  trace_events?: TraceEvent[];   // Observability events
}

TraceEvent

TypeScript
interface TraceEvent {
  timestamp: string;                      // ISO 8601 timestamp
  type: string;                           // "span_start" | "span_end" | "llm_call" | "error" | "event"
  name: string;                           // Event name
  attributes: Record<string, string>;     // Event metadata
  duration?: number;                      // Duration in milliseconds
  trace_id?: string;                      // OpenTelemetry trace ID
  span_id?: string;                       // OpenTelemetry span ID
}

FileStorageResult

TypeScript
interface FileStorageResult {
  context: string;           // Built context string with file contents
  files: Array<{
    relativePath: string;    // File path relative to root
    size: number;            // File size in bytes
  }>;
  totalSize: number;         // Total size of all included files
  skipped: Array<{
    relativePath: string;    // Skipped file path
    reason: string;          // Why it was skipped
  }>;
}

S3StorageError

Typed error class with actionable remediation messages for S3 operations.

TypeScript
class S3StorageError extends Error {
  code: string;    // Error code
  cause?: Error;   // Original error
}

// Error codes:
// 'AUTH_FAILED'      - Missing or invalid credentials
// 'ACCESS_DENIED'    - Insufficient permissions
// 'BUCKET_NOT_FOUND' - Bucket does not exist
// 'KEY_NOT_FOUND'    - Object not found
// 'NETWORK_ERROR'    - Connection failed
// 'REGION_MISMATCH'  - Wrong region configured

CacheConfig

TypeScript
interface CacheConfig {
  enabled: boolean;
  maxEntries?: number;   // Default: 1000
  ttl?: number;          // TTL in ms (default: 3600000 = 1h)
  backend?: 'memory' | 'file';
  directory?: string;    // For file backend
}

RetryConfig

TypeScript
interface RetryConfig {
  maxRetries?: number;                       // Default: 3
  baseDelay?: number;                        // Base delay in ms (default: 1000)
  maxDelay?: number;                         // Max delay cap in ms (default: 30000)
  backoff?: 'exponential' | 'linear' | 'fixed'; // Default: 'exponential'
  jitter?: boolean;                          // Add randomness (default: true)
  onRetry?: (attempt: number, error: Error, delay: number) => void;
}

FallbackConfig

TypeScript
interface FallbackConfig {
  models: string[];  // Ordered list of model fallbacks
}

StreamChunk<T>

TypeScript
type StreamChunk<T> =
  | { type: 'text'; text: string; timestamp: number }
  | { type: 'partial_object'; object: Partial<T>; timestamp: number }
  | { type: 'metadata'; stats: RLMStats; timestamp: number }
  | { type: 'error'; error: Error; timestamp: number }
  | { type: 'done'; stats: RLMStats; timestamp: number };

Error Hierarchy

All errors extend RLMError with structured metadata.

TypeScript
class RLMError extends Error {
  code: string;
  retryable: boolean;
  suggestion?: string;
  context?: Record<string, unknown>;
}

class RLMValidationError extends RLMError { field?: string; }
class RLMRateLimitError extends RLMError  { retryAfter?: number; }
class RLMTimeoutError extends RLMError    { timeout?: number; }
class RLMProviderError extends RLMError   { provider?: string; statusCode?: number; }
class RLMBinaryError extends RLMError     { binaryPath?: string; }
class RLMConfigError extends RLMError     { }
class RLMSchemaError extends RLMError     { }
class RLMAbortError extends RLMError      { }
class RLMContextOverflowError extends RLMError {
  modelLimit?: number;       // Max tokens the model supports
  requestTokens?: number;    // Tokens in the request
  strategy?: string;         // Recovery strategy attempted
}

classifyError()

Auto-classify raw errors into the appropriate RLM error type based on error message and context.

TypeScript
function classifyError(
  error: unknown,
  context?: { binaryPath?: string; provider?: string }
): RLMError;

// Examples:
classifyError(new Error('rate limit exceeded'));
// => RLMRateLimitError

classifyError(new Error('ENOENT'), { binaryPath: '/bin/rlm-go' });
// => RLMBinaryError

RLMStream<T>

Async iterable stream for consuming completions in real-time.

TypeScript
class RLMStream<T> implements AsyncIterable<StreamChunk<T>> {
  // Producer methods
  push(chunk: StreamChunk<T>): void;
  pushError(error: Error): void;
  complete(stats: RLMStats): void;

  // Consumer methods
  toText(): Promise<string>;      // Collect all text chunks
  toObject(): Promise<T | null>;   // Get final structured object

  // AsyncIterable
  [Symbol.asyncIterator](): AsyncIterator<StreamChunk<T>>;
}

Cache API

TypeScript
interface CacheStats {
  hits: number;
  misses: number;
  hitRate: number;
  size: number;
  evictions: number;
}

class MemoryCache { /* LRU + TTL in-memory cache */ }
class FileCache   { /* Persistent file-based cache */ }

RLMEventEmitter

TypeScript
type RLMEventMap = {
  llm_call: { model: string; queryLength: number; contextLength: number };
  llm_response: { model: string; tokensUsed: number; duration: number };
  error: { error: Error; operation: string };
  cache: { action: 'hit' | 'miss' | 'set' | 'evict' };
  retry: { attempt: number; error: Error; delay: number };
  completion_start: { model: string; query: string; contextLength: number };
  completion_end: { model: string; duration: number; stats: RLMStats };
  validation_retry: { field: string; attempt: number; error: string };
  recursion: { depth: number; chunkIndex: number; totalChunks: number };
  meta_agent: { originalQuery: string; optimizedQuery: string };
};

Config Validation

TypeScript
function validateConfig(config: Partial<RLMConfig>): ValidationResult;
function assertValidConfig(config: Partial<RLMConfig>): void; // throws RLMConfigError

interface ValidationResult {
  valid: boolean;
  issues: ValidationIssue[];
}

interface ValidationIssue {
  level: 'error' | 'warning' | 'info';
  field: string;
  message: string;
}

Retry Utilities

TypeScript
function withRetry<T>(
  fn: () => Promise<T>,
  config?: RetryConfig,
  signal?: AbortSignal
): Promise<T>;

function withFallback<T>(
  fn: (model: string) => Promise<T>,
  fallbackConfig: FallbackConfig,
  retryConfig?: RetryConfig
): Promise<T & { _usedModel: string }>;

Environment Variables

All environment variables used by recursive-llm-ts.

Core

VariableRequiredDescription
OPENAI_API_KEY Required API key for OpenAI (or compatible provider). Can also be passed via config.api_key.
AZURE_API_KEY Optional API key for Azure OpenAI deployments
RLM_GO_BINARY Optional Override path to the Go binary
RLM_DEBUG Optional Set to 1 to enable debug mode

Observability

VariableRequiredDescription
OTEL_EXPORTER_OTLP_ENDPOINT Optional OTLP endpoint for OpenTelemetry (auto-enables tracing)
LANGFUSE_PUBLIC_KEY Optional Langfuse public key (auto-enables Langfuse)
LANGFUSE_SECRET_KEY Optional Langfuse secret key
LANGFUSE_HOST Optional Langfuse API host (default: https://cloud.langfuse.com)

S3 File Storage

VariableRequiredDescription
AWS_ACCESS_KEY_ID Optional AWS access key for S3 (if not using explicit credentials)
AWS_SECRET_ACCESS_KEY Optional AWS secret key for S3
AWS_SESSION_TOKEN Optional AWS session token (for temporary credentials)
AWS_REGION Optional AWS region (default: us-east-1)
AWS_DEFAULT_REGION Optional Fallback for AWS_REGION