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.
Create a new RLM instance.
| Parameter | Type | Description |
|---|---|---|
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) |
Process a query with the given context using recursive language models. The context can be arbitrarily large — it will be recursively decomposed.
| Parameter | Type | Description |
|---|---|---|
query |
string |
The question or task to perform |
context |
string |
The document/context to process (any size) |
Promise<RLMResult>
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.
| Parameter | Type | Description |
|---|---|---|
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) |
Promise<StructuredRLMResult<T>>
Process a query using files from local or S3 storage as context. Recursively traverses directories, applies filters, and builds context automatically.
| Parameter | Type | Description |
|---|---|---|
query |
string |
The question or task |
fileConfig |
FileStorageConfig |
File storage configuration |
Promise<RLMResult & { fileStorage?: FileStorageResult }>
Extract structured data from file-based context. Combines file traversal with Zod schema extraction.
| Parameter | Type | Description |
|---|---|---|
query |
string |
The extraction task |
fileConfig |
FileStorageConfig |
File storage configuration |
schema |
ZodSchema<T> |
Zod schema for output |
options |
object |
Same as structuredCompletion options |
Promise<StructuredRLMResult<T> & { fileStorage?: FileStorageResult }>
Returns trace events from the last operation. Only populated when observability is enabled.
TraceEvent[]
Clean up the bridge and free resources. Call this when done with the RLM instance.
Promise<void>
Stream a completion as an async iterable of chunks. Each chunk contains either text or metadata.
| Parameter | Type | Description |
|---|---|---|
query |
string |
The question or task to perform |
context |
string |
The document/context to process |
signal |
AbortSignal |
Optional abort signal for cancellation |
Promise<RLMStream<string>>
Stream a structured completion. Returns partial objects as they are built.
Promise<RLMStream<T>>
Process multiple completion requests concurrently with configurable concurrency limits.
| Parameter | Type | Description |
|---|---|---|
items |
Array<{query, context}> |
Array of query/context pairs |
options.concurrency |
number |
Max parallel requests (default: 3) |
Promise<RLMCompletionResult[]>
Subscribe to lifecycle events. Available events: llm_call, llm_response, error, cache, retry, completion_start, completion_end, validation_retry, recursion, meta_agent.
void
Remove a previously registered event handler.
void
Subscribe to an event for a single emission only.
void
Validate the current configuration and return issues with severity levels.
ValidationResult — { valid: boolean, issues: ValidationIssue[] }
Get current cache statistics including hits, misses, hit rate, and eviction count.
CacheStats | null
Clear all cached responses.
void
Create a result formatter for pretty printing, JSON export, or Markdown generation.
RLMResultFormatter — with .prettyStats(), .toJSON(), .toMarkdown() methods
Static Factory Methods
Create an RLM instance using environment variables for configuration. Auto-detects OPENAI_API_KEY, RLM_DEBUG, etc.
RLM
Quick setup with debug logging enabled. Uses environment variables for API key.
RLM
Create an RLM instance pre-configured for Azure OpenAI deployments.
RLM
Create a fluent builder for step-by-step configuration. See RLMBuilder.
RLMBuilder
RLMAgentCoordinator
Advanced coordinator for complex multi-field schema extraction. Wraps RLM with schema decomposition and parallel processing.
| Parameter | Type | Description |
|---|---|---|
model |
string |
LLM model identifier |
rlmConfig |
RLMConfig |
Optional RLM configuration |
bridgeType |
BridgeType |
Bridge selection |
coordinatorConfig |
CoordinatorConfig |
Coordinator options (e.g., { parallelExecution: true }) |
Process a complex extraction task with schema decomposition.
Promise<StructuredRLMResult<T>>
FileContextBuilder
Utility for building LLM context from file trees. Supports local filesystem and S3-compatible storage.
| Parameter | Type | Description |
|---|---|---|
config |
FileStorageConfig |
File storage configuration |
List files that match the configuration filters without reading their content. Useful for previewing what will be processed.
Promise<string[]>
Build the full context string from matching files. Includes file contents with delimiters.
Promise<FileStorageResult>
RLMBuilder
Fluent builder for constructing RLM instances with complex configuration. All methods return this for chaining.
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.
| Property | Type | Default | Description |
|---|---|---|---|
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.
| Property | Type | Default | Description |
|---|---|---|---|
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.
| Property | Type | Default | Description |
|---|---|---|---|
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.
| Property | Type | Default | Description |
|---|---|---|---|
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.
| Property | Type | Default | Description |
|---|---|---|---|
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.
| Property | Type | Description |
|---|---|---|
enabled | boolean | Enable LCM context management (default: false) |
soft_threshold | number | Async compaction begins above this token count (default: 70% of model limit) |
hard_threshold | number | Blocking compaction above this (default: 90% of model limit) |
compaction_block_size | number | Messages to compact at once (default: 10) |
summary_target_tokens | number | Target tokens per summary node (default: 500) |
episodes | EpisodeConfig | Episode-based context grouping config |
store_backend | StoreBackendConfig | Persistence backend config |
EpisodeConfig
| Property | Type | Description |
|---|---|---|
max_episode_tokens | number | Auto-close episode above this (default: 2000) |
max_episode_messages | number | Auto-close episode above this (default: 20) |
auto_compact_after_close | boolean | Generate summary when episode closes (default: true) |
StoreBackendConfig
| Property | Type | Description |
|---|---|---|
type | 'memory' | 'sqlite' | Backend type (default: 'memory') |
path | string | SQLite database path (required for 'sqlite', use ':memory:' for in-memory) |
LLMMapConfig
Configuration for parallel batch processing via LLM-Map operator.
| Property | Type | Description |
|---|---|---|
input_path | string | Path to JSONL input file |
output_path | string | Path to JSONL output file |
prompt | string | Prompt template — use {{item}} placeholder |
output_schema | object | JSON Schema for per-item output validation |
concurrency | number | Worker pool size (default: 16) |
max_retries | number | Per-item retry limit (default: 3) |
AgenticMapConfig
Configuration for sub-agent batch processing via Agentic-Map operator.
| Property | Type | Description |
|---|---|---|
input_path | string | Path to JSONL input file |
output_path | string | Path to JSONL output file |
prompt | string | Prompt template — use {{item}} placeholder |
concurrency | number | Worker pool size (default: 8) |
read_only | boolean | Sub-agents cannot modify filesystem |
max_depth | number | Max recursion depth per sub-agent (default: 3) |
max_iterations | number | Max iterations per sub-agent (default: 15) |
DelegationRequest
Request structure for task delegation with infinite recursion guard.
| Property | Type | Description |
|---|---|---|
prompt | string | Task description for the sub-agent |
delegated_scope | string | Specific slice of work being handed off |
kept_work | string | Work the caller retains (must be non-trivial) |
read_only | boolean | Read-only exploration agent (exempt from guard) |
parallel | boolean | Parallel decomposition (exempt from guard) |
RLMResult
Return type for completion() and completionFromFiles().
interface RLMResult {
result: string; // The answer
stats: RLMStats; // Execution statistics
trace_events?: TraceEvent[]; // Observability events (when enabled)
}
RLMStats
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>
interface StructuredRLMResult<T> {
result: T; // Typed result matching your Zod schema
stats: RLMStats; // Execution statistics
trace_events?: TraceEvent[]; // Observability events
}
TraceEvent
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
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.
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
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
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
interface FallbackConfig {
models: string[]; // Ordered list of model fallbacks
}
StreamChunk<T>
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.
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.
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.
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
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
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
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
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
| Variable | Required | Description |
|---|---|---|
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
| Variable | Required | Description |
|---|---|---|
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
| Variable | Required | Description |
|---|---|---|
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 |