Guide

This guide covers installation, configuration, and usage patterns for recursive-llm-ts.

Installation

Bash
npm install recursive-llm-ts

The postinstall script automatically builds the Go binary. If Go is not available, it will warn but not fail.

Prerequisites

  • Node.js 16+ or Bun 1.0+
  • Go 1.25+ — only needed if building the Go binary from source
  • An OpenAI API key (or key for any OpenAI-compatible provider)
Pre-built binaries

On supported targets, npm installs a matching @recursive-llm/<platform> package automatically. For manual deployments, you can still use GitHub Releases and point RLM_GO_BINARY at the downloaded binary.

Configuration

Set your API key as an environment variable or pass it in the configuration.

Bash
export OPENAI_API_KEY='sk-...'

Or pass it directly:

TypeScript
const rlm = new RLM('gpt-4o-mini', {
  api_key: 'sk-...',
  max_iterations: 15,
  max_depth: 5,
});

First Completion

The simplest usage — pass a query and a large context string:

TypeScript
import { RLM } from 'recursive-llm-ts';

const rlm = new RLM('gpt-4o-mini', {
  api_key: process.env.OPENAI_API_KEY,
});

const result = await rlm.completion(
  'What are the key findings?',
  veryLargeDocument  // Any size - no token limit
);

console.log(result.result);
console.log('Stats:', result.stats);
// { llm_calls: 8, iterations: 12, depth: 2 }

await rlm.cleanup();

The engine automatically:

  • Splits the context into manageable chunks
  • Uses the LLM to write JavaScript analysis code
  • Executes the code in a sandboxed REPL
  • Recursively combines results

Recursive Decomposition

The core innovation from the RLM paper. When a context is too large for a single LLM call, the engine:

  1. Splits the context into chunks that fit the model's context window
  2. Processes each chunk with the LLM, which writes JavaScript code to analyze it
  3. Executes the code in a sandboxed JavaScript REPL (goja engine)
  4. Recurses if needed — results from subchunks become context for the next level
  5. Merges results back up the tree to produce the final answer

Control recursion with max_depth (default: 5) and max_iterations (default: 30).

Structured Outputs

Extract typed data using Zod schemas. The engine converts your schema to JSON Schema, decomposes complex schemas into subtasks, and validates results with retry logic.

TypeScript
import { z } from 'zod';

const schema = z.object({
  sentiment: z.number().min(1).max(5),
  summary: z.string(),
  topics: z.array(z.enum(['pricing', 'features', 'support'])),
  keyPhrases: z.array(z.object({
    phrase: z.string(),
    weight: z.number(),
  })),
});

const result = await rlm.structuredCompletion(
  'Analyze this transcript',
  transcript,
  schema,
  { parallelExecution: true, maxRetries: 3 }
);

// result.result is typed as z.infer<typeof schema>

How it works under the hood:

  • Zod schema is converted to JSON Schema
  • Meta-agent optimizes the query for extraction (if enabled)
  • Complex schemas are decomposed into per-field subtasks
  • Subtasks run in parallel via goroutines
  • Each field is validated against its JSON Schema
  • Failed fields get retried with error feedback (instructor-style)
  • Results are merged into the final typed object

Supported Zod types: objects, arrays, strings, numbers, booleans, enums, unions (z.union), intersections (z.intersection), optionals, nullables, and all constraints (min, max, length, pattern, etc.).

File Storage Context

Process files from local directories or S3-compatible storage as LLM context. Added in v4.4.0.

Local Files

TypeScript
const result = await rlm.completionFromFiles(
  'Describe the architecture',
  {
    type: 'local',
    path: './src',
    extensions: ['.ts', '.tsx'],
    excludePatterns: ['*.test.ts', 'node_modules/**'],
    maxFileSize: 100_000,
    maxTotalSize: 5_000_000,
    maxFiles: 100,
  }
);

S3 Storage

Works with AWS S3, MinIO, LocalStack, DigitalOcean Spaces, and Backblaze B2.

TypeScript
// AWS S3
const result = await rlm.completionFromFiles(
  'Summarize reports',
  {
    type: 's3',
    path: 'my-bucket',
    prefix: 'reports/',
    extensions: ['.md', '.txt'],
    region: 'us-west-2',
    // Credentials: explicit > env vars > AWS SDK chain
  }
);

// MinIO
const result2 = await rlm.completionFromFiles(
  'Analyze data',
  {
    type: 's3',
    path: 'local-bucket',
    endpoint: 'http://localhost:9000',
    credentials: {
      accessKeyId: 'minioadmin',
      secretAccessKey: 'minioadmin',
    },
  }
);
S3 Credential Resolution

Credentials are resolved in order: (1) explicit credentials in config, (2) environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN), (3) AWS SDK default chain (IAM role, ~/.aws/credentials, ECS task role).

Meta-Agent

The meta-agent automatically optimizes queries before processing. Useful for vague or non-specific queries.

TypeScript
const rlm = new RLM('gpt-4o-mini', {
  api_key: process.env.OPENAI_API_KEY,
  meta_agent: {
    enabled: true,
    model: 'gpt-4o',       // Stronger model for optimization
    max_optimize_len: 10000, // Skip for short contexts
  },
});

// "what happened?" becomes:
// "Provide a detailed summary including: key decisions,
//  action items, participants, and unresolved issues."
const result = await rlm.completion('what happened?', transcript);

Observability

Three observability backends available simultaneously:

Debug Logging

TypeScript
const rlm = new RLM('gpt-4o-mini', {
  debug: true, // Shorthand for observability.debug
});

OpenTelemetry

TypeScript
const rlm = new RLM('gpt-4o-mini', {
  observability: {
    trace_enabled: true,
    trace_endpoint: 'http://localhost:4318',
    service_name: 'my-service',
  },
});

Langfuse

TypeScript
const rlm = new RLM('gpt-4o-mini', {
  observability: {
    langfuse_enabled: true,
    langfuse_public_key: process.env.LANGFUSE_PUBLIC_KEY,
    langfuse_secret_key: process.env.LANGFUSE_SECRET_KEY,
  },
});

Accessing Trace Events

TypeScript
const result = await rlm.completion('Summarize', doc);

const events = rlm.getTraceEvents();
for (const e of events) {
  console.log(`[${e.type}] ${e.name}`, e.attributes);
  // [span_start] rlm.completion {trace_id: "abc..."}
  // [llm_call] gpt-4o-mini {tokens: 1247, duration_ms: 2341}
  // [span_end] rlm.completion {total_duration_ms: 5218}
}

Context Overflow Recovery

When your context exceeds the model's token limit, RLM automatically detects the overflow and reduces the context using one of 6 strategies. This works with any OpenAI-compatible API including vLLM, Ollama, and Azure.

Enabled by default

Context overflow recovery is enabled by default. No configuration needed — it detects overflow errors from the API and automatically retries with reduced context.

How It Works

  1. RLM sends the full context to the LLM API
  2. If the API returns a context overflow error, RLM parses the token counts
  3. The configured strategy reduces the context to fit within the model's limit
  4. The reduced context is sent to the LLM for processing
  5. Up to 3 reduction attempts (configurable) before giving up

Strategy Comparison

StrategyHow It WorksLLM CallsBest For
mapreduce Splits context into chunks, summarizes each with the LLM, combines summaries N + 1 General purpose, preserves key info across full document
truncate Keeps beginning and end of context, removes the middle 0 Fast, zero-cost; good when key info is at start/end
chunked Extracts relevant chunks via LLM, merges the best ones N + 1 Query-focused extraction from large documents
tfidf Scores sentences by TF-IDF relevance to the query, keeps top sentences 0 Fast, zero-cost; good for keyword-heavy queries
textrank Graph-based sentence ranking (like PageRank for text), keeps top sentences 0 Fast, zero-cost; good for extracting important sentences
refine Processes chunks sequentially, refining a running summary N Best quality for narrative/sequential content

Which Strategy to Use

  • Default (mapreduce) — Best all-around choice. Processes all chunks in parallel and combines results.
  • Cost-sensitive? Use truncate, tfidf, or textrank — zero LLM calls for reduction.
  • Query-focused? Use tfidf or chunked — they prioritize content relevant to your query.
  • Narrative content? Use refine — processes sequentially to maintain document flow.
  • Small models (<8K)? Use tfidf or textrank — pure algorithmic, no risk of recursive overflow.

Configuration

TypeScript
const rlm = new RLM('gpt-4o-mini', {
  api_key: process.env.OPENAI_API_KEY,
  max_tokens: 10000,

  // Context overflow configuration
  context_overflow: {
    enabled: true,              // Default: true
    strategy: 'mapreduce',      // Default: 'mapreduce'
    safety_margin: 0.15,        // Reserve 15% for overhead (default)
    max_reduction_attempts: 3,  // Max retries (default: 3)
    max_model_tokens: 0,        // 0 = auto-detect from API errors
  },
});

Strategy Examples

TypeScript
// Zero-cost TF-IDF for budget-conscious workloads
const rlm = new RLM('qwen3-8b', {
  api_base: 'http://localhost:8000/v1',
  max_tokens: 10000,
  context_overflow: {
    strategy: 'tfidf',  // No extra LLM calls
  },
});

// Refine for high-quality narrative summarization
const rlm2 = new RLM('gpt-4o', {
  context_overflow: {
    strategy: 'refine',
    safety_margin: 0.2,  // More headroom for longer responses
  },
});

// Disable overflow recovery (fail fast)
const rlm3 = new RLM('gpt-4o-mini', {
  context_overflow: { enabled: false },
});

Works with Structured Outputs

Context overflow recovery works seamlessly with structuredCompletion(). If the context overflows during structured extraction, the engine reduces context first, then retries the extraction.

TypeScript
// Even with 100K+ tokens of data, this works
const result = await rlm.structuredCompletion(
  'Extract customer insights',
  hugeDataset,  // Exceeds model limit
  schema,
  { parallelExecution: true }
);
// Context is automatically reduced before extraction
Response budget matters

If you set max_tokens, the overflow handler accounts for it when sizing chunks. For example, with a 32K model and max_tokens: 10000, only ~22K tokens are available for context. The handler automatically detects this from API errors like "max_tokens is too large".

Streaming

Stream completions in real-time using async iterables. Supports both text and structured object streaming with AbortController integration.

TypeScript
// Stream text tokens
const stream = await rlm.streamCompletion(
  'Summarize this document',
  longDocument
);

for await (const chunk of stream) {
  if (chunk.type === 'text') {
    process.stdout.write(chunk.text);
  }
}

// Collect all text at once
const text = await stream.toText();

// Stream structured objects
const objStream = await rlm.streamStructuredCompletion(
  'Extract key info', context, schema
);
const result = await objStream.toObject();

// With abort support
const controller = new AbortController();
setTimeout(() => controller.abort(), 30000);
const stream2 = await rlm.streamCompletion(
  'Summarize', doc, controller.signal
);

Caching

Enable response caching to avoid redundant LLM calls. Two backends available: in-memory (LRU with TTL) and file-based persistent cache.

TypeScript
const rlm = new RLM('gpt-4o-mini', {
  api_key: process.env.OPENAI_API_KEY,
  cache: {
    enabled: true,
    maxEntries: 1000,        // LRU eviction limit
    ttl: 3600000,            // 1 hour TTL
    backend: 'memory',       // or 'file'
    directory: '.rlm-cache', // for file backend
  },
});

// First call hits the LLM
const result1 = await rlm.completion('Summarize', doc);
console.log(result1.cached); // false

// Second identical call returns from cache
const result2 = await rlm.completion('Summarize', doc);
console.log(result2.cached); // true

// Check cache stats
const stats = rlm.getCacheStats();
console.log(stats); // { hits: 1, misses: 1, hitRate: 0.5, ... }

// Clear cache when needed
rlm.clearCache();

Retry & Resilience

Built-in retry logic with multiple backoff strategies. Rate-limit aware with automatic delay adjustment. Multi-provider fallback chains for high availability.

TypeScript
const rlm = new RLM('gpt-4o-mini', {
  api_key: process.env.OPENAI_API_KEY,
  retry: {
    maxRetries: 3,
    baseDelay: 1000,
    backoff: 'exponential', // or 'linear', 'fixed'
    jitter: true,
    onRetry: (attempt, error, delay) => {
      console.log(`Retry ${attempt} after ${delay}ms: ${error.message}`);
    },
  },
  fallback: {
    models: ['gpt-4o-mini', 'gpt-4o', 'claude-sonnet-4-20250514'],
  },
});

// Standalone retry utility
import { withRetry, withFallback } from 'recursive-llm-ts';

const result = await withRetry(
  () => fetch('https://api.example.com/data'),
  { maxRetries: 3, backoff: 'exponential' }
);

Error Handling

Structured error hierarchy with 9 typed error classes. Each error includes a code, retryability flag, and an actionable suggestion for resolution.

TypeScript
import {
  RLMError,
  RLMValidationError,
  RLMRateLimitError,
  RLMTimeoutError,
  RLMProviderError,
  RLMBinaryError,
  RLMConfigError,
  RLMSchemaError,
  RLMAbortError,
  classifyError,
} from 'recursive-llm-ts';

try {
  const result = await rlm.completion('query', context);
} catch (err) {
  if (err instanceof RLMRateLimitError) {
    console.log(`Rate limited. Retry after: ${err.retryAfter}s`);
  } else if (err instanceof RLMValidationError) {
    console.log(`Schema validation failed: ${err.field}`);
    console.log(`Suggestion: ${err.suggestion}`);
  } else if (err instanceof RLMTimeoutError) {
    console.log(`Timed out after ${err.timeout}ms`);
  } else if (err instanceof RLMError) {
    console.log(`RLM error [${err.code}]: ${err.message}`);
    console.log(`Retryable: ${err.retryable}`);
  }
}

// Auto-classify raw errors
const classified = classifyError(new Error('connection timeout'));
console.log(classified instanceof RLMTimeoutError); // true

Events

Subscribe to lifecycle events for monitoring, logging, and custom integrations. The typed event emitter supports 10 event types.

TypeScript
// Subscribe to events
rlm.on('llm_call', (event) => {
  console.log(`LLM call to ${event.model}, context: ${event.contextLength}`);
});

rlm.on('error', (event) => {
  console.error(`Error in ${event.operation}:`, event.error);
});

rlm.on('cache', (event) => {
  console.log(`Cache ${event.action}`); // 'hit' | 'miss' | 'set'
});

rlm.on('retry', (event) => {
  console.log(`Retry attempt ${event.attempt} after ${event.delay}ms`);
});

// One-time listener
rlm.once('completion_end', (event) => {
  console.log(`First completion done in ${event.duration}ms`);
});

// Remove listeners
const handler = (e: any) => console.log(e);
rlm.on('llm_call', handler);
rlm.off('llm_call', handler);

// Remove all listeners for an event
rlm.removeAllListeners('error');

Builder API

Fluent builder for complex configurations. Factory methods for common setups.

TypeScript
// Fluent builder
const rlm = RLM.builder()
  .model('gpt-4o-mini')
  .apiKey(process.env.OPENAI_API_KEY!)
  .maxDepth(5)
  .maxIterations(20)
  .enableMetaAgent('gpt-4o')
  .enableDebug()
  .enableCache({ maxEntries: 500 })
  .enableRetry({ maxRetries: 3, backoff: 'exponential' })
  .build();

// Factory methods
const rlm1 = RLM.fromEnv();               // Auto-detect from env
const rlm2 = RLM.withDebug('gpt-4o');     // Quick debug setup
const rlm3 = RLM.forAzure(                // Azure-specific
  'my-deployment',
  'https://my.openai.azure.com',
  process.env.AZURE_API_KEY!
);

Batch Operations

Process multiple queries concurrently with configurable concurrency limits.

TypeScript
// Batch text completions
const results = await rlm.batchCompletion([
  { query: 'Summarize chapter 1', context: chapter1 },
  { query: 'Summarize chapter 2', context: chapter2 },
  { query: 'Summarize chapter 3', context: chapter3 },
], { concurrency: 3 });

for (const r of results) {
  console.log(r.result);
}

// Batch structured completions
const structured = await rlm.batchStructuredCompletion(
  [
    { query: 'Extract from doc1', context: doc1 },
    { query: 'Extract from doc2', context: doc2 },
  ],
  schema,
  { concurrency: 2 }
);

Config Validation

Validate configuration before use. Catches typos, invalid values, and missing settings with actionable messages.

TypeScript
import { validateConfig, assertValidConfig } from 'recursive-llm-ts';

// Get detailed validation results
const result = validateConfig({
  api_key: 'sk-...',
  max_detph: 5, // typo!
  max_iterations: -1, // invalid!
});

for (const issue of result.issues) {
  console.log(`[${issue.level}] ${issue.field}: ${issue.message}`);
}
// [warning] max_detph: Unknown config key "max_detph" (possible typo for "max_depth")
// [error] max_iterations: max_iterations must be positive

// Or throw on errors
assertValidConfig({ max_depth: -1 });
// throws RLMConfigError

Lossless Context Management (LCM)

LCM is an opt-in context management layer that replaces legacy message pruning with a deterministic, DAG-based architecture. Every message is persisted in an immutable store, and context is managed via a hierarchical summary DAG.

New in v5.0

LCM is optional and backward-compatible. Enable it by setting lcm.enabled: true in your config. Without it, the engine behaves exactly as before.

LCM Configuration

TypeScript
const rlm = new RLM('gpt-4o', {
  api_key: process.env.OPENAI_API_KEY,
  lcm: {
    enabled: true,
    soft_threshold: 90000,   // 70% of 128k (async compaction)
    hard_threshold: 115000,  // 90% of 128k (blocking compaction)
    compaction_block_size: 10,
    summary_target_tokens: 500,
    episodes: {
      max_episode_tokens: 2000,
      max_episode_messages: 20,
      auto_compact_after_close: true,
    },
    store_backend: {
      type: 'sqlite',
      path: './data/session.db',
    },
  },
});

The context control loop has three zones:

ZoneConditionBehavior
Greentokens < soft_thresholdZero-cost continuity — no overhead
Yellowsoft ≤ tokens < hardAsync compaction between turns
Redtokens ≥ hard_thresholdBlocking compaction before LLM call

Episodic Memory

Episodes group related messages into coherent interaction units for compression and retrieval.

TypeScript
// Episodes are configured via the lcm.episodes block
const rlm = new RLM('gpt-4o', {
  lcm: {
    enabled: true,
    episodes: {
      max_episode_tokens: 2000,    // Auto-rotate when exceeded
      max_episode_messages: 20,    // Auto-rotate when exceeded
      auto_compact_after_close: true, // Generate summary on close
    },
  },
});

Episode lifecycle: active → compacted (has summary) → archived. Budget-based retrieval selects episodes that fit within the token budget, always including the active episode.

BPE Tokenizer

RLM uses model-specific BPE tokenization via tiktoken-go, automatically selected during engine creation:

Model FamilyEncodingExamples
o200k_baseGPT-4o, O1, O3gpt-4o, gpt-4o-mini, o1, o3-mini
cl100k_baseGPT-4, GPT-3.5, Claudegpt-4, gpt-3.5-turbo, claude-3-opus

Token counting is cached with xxhash-keyed sync.Map (10K entries). Falls back to a ~3.5 chars/token heuristic when BPE encoding is unavailable.

Five-Level Summarization

When context exceeds thresholds, LCM escalates through five compression levels. Level 5 is deterministic — guaranteed convergence with no LLM calls:

LevelStrategyLLM?Description
1NormalYesLLM summarize with detail preservation
2AggressiveYesLLM summarize as bullet points, target T/2
3TF-IDFNoExtractive compression via sentence scoring
4TextRankNoGraph-based PageRank sentence ranking
5TruncateNoKeep 2/3 start + 1/3 end, deterministic

LLM-Map & Agentic-Map

LLM-Map processes items in parallel with schema validation per item:

Go
result, err := engine.LLMMap(rlm.LLMMapConfig{
  InputPath:  "data/items.jsonl",
  OutputPath: "data/results.jsonl",
  Prompt:     "Classify this item: {{item}}",
  OutputSchema: &rlm.JSONSchema{Type: "object", Properties: map[string]*rlm.JSONSchema{
    "category": {Type: "string"},
  }},
  Concurrency: 16,
})

Agentic-Map spawns full sub-agent RLM sessions per item with tool access:

Go
result, err := engine.AgenticMap(rlm.AgenticMapConfig{
  InputPath:  "data/repos.jsonl",
  OutputPath: "data/analyses.jsonl",
  Prompt:     "Analyze this repository: {{item}}",
  Concurrency: 4,
  ReadOnly:    true,
})

Task Delegation

The infinite delegation guard prevents unbounded recursion by requiring sub-agents to declare scope reduction:

Go
result, stats, err := engine.DelegateTask(rlm.DelegationRequest{
  Prompt:         "Parse the config files",
  DelegatedScope: "Parse config/ directory files",
  KeptWork:       "Validate and apply extracted settings",
})

If KeptWork is trivial (e.g., "none", "waiting"), the delegation is rejected. Root agents (depth 0), read-only agents, and parallel decomposition are exempt.

SQLite Persistence

LCM supports two storage backends:

BackendConfigUse Case
Memorytype: 'memory'Default, zero dependencies, ephemeral
SQLitetype: 'sqlite'Persistent, FTS5 search, WAL mode, crash recovery
TypeScript
const rlm = new RLM('gpt-4o', {
  lcm: {
    enabled: true,
    store_backend: {
      type: 'sqlite',
      path: './data/session.db',  // or ':memory:' for in-memory SQLite
    },
  },
});

SQLite features: WAL mode for concurrent reads, FTS5 virtual tables for full-text message search, indexed lookups by ID/role/timestamp, transactional writes for crash recovery.

LLM Providers

The Go binary uses an OpenAI-compatible chat completion API. Any provider that supports the /chat/completions schema works:

ProviderConfiguration
OpenAI Default. Just set api_key.
Azure OpenAI api_base + api_key + api_version
Bedrock Via LiteLLM proxy: api_base pointing to proxy
Anthropic Via LiteLLM proxy
Ollama api_base: 'http://localhost:11434/v1'
vLLM api_base pointing to vLLM server
Any OpenAI-compatible api_base + api_key

Docker

For Linux containers, you have three supported paths: use the published platform package, point to a custom binary, or build from source in a multi-stage image.

Option 1: Use the published Linux binary package

On linux-x64 and linux-arm64, npm ci --omit=dev installs the matching @recursive-llm/linux-* binary automatically. No Go toolchain or RLM_GO_BINARY override is required.

Dockerfile
FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
ENV NODE_ENV=production
CMD ["node", "your-app.js"]

Option 2: Copy or mount a custom binary

Use this when you build the Go binary elsewhere and want to pin a specific binary path inside the container.

Dockerfile
FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev --ignore-scripts
COPY . .
COPY ./bin/rlm-go /app/bin/rlm-go
RUN chmod +x /app/bin/rlm-go
ENV NODE_ENV=production
ENV RLM_GO_BINARY=/app/bin/rlm-go
CMD ["node", "your-app.js"]

Option 3: Build from source in a multi-stage image

Use this for unsupported targets or when you want a custom-compiled binary.

Dockerfile
# Build Go binary
FROM golang:1.25-alpine AS go-builder
WORKDIR /build
COPY go/go.mod go/go.sum ./
RUN go mod download
COPY go/ ./
RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o rlm-go ./cmd/rlm

# Build Node.js
FROM node:22-alpine AS node-builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev --ignore-scripts

# Runtime
FROM node:22-alpine
WORKDIR /app
COPY --from=node-builder /app/node_modules ./node_modules
COPY --from=go-builder /build/rlm-go ./bin/rlm-go
RUN chmod +x ./bin/rlm-go
COPY . .
ENV RLM_GO_BINARY=/app/bin/rlm-go
ENV NODE_ENV=production
CMD ["node", "your-app.js"]

Go Module

Import the Go implementation directly in Go projects:

Bash
go get github.com/howlerops/recursive-llm-ts/go

See the Go examples for usage.

Environment Variables

Required for operation

OPENAI_API_KEY must be set (or passed via config.api_key) for the LLM to work. All other variables are optional.

VariableRequiredDescription
OPENAI_API_KEY Required API key for the LLM provider
AZURE_API_KEY Optional Azure OpenAI API key
RLM_GO_BINARY Optional Custom path to Go binary
RLM_DEBUG Optional Enable debug mode (1)
OTEL_EXPORTER_OTLP_ENDPOINT Optional OTLP endpoint (auto-enables OTEL)
LANGFUSE_PUBLIC_KEY Optional Langfuse public key
LANGFUSE_SECRET_KEY Optional Langfuse secret key
LANGFUSE_HOST Optional Langfuse API host
AWS_ACCESS_KEY_ID Optional AWS access key for S3
AWS_SECRET_ACCESS_KEY Optional AWS secret key for S3
AWS_SESSION_TOKEN Optional AWS session token
AWS_REGION Optional AWS region for S3
AWS_DEFAULT_REGION Optional Fallback AWS region

Binary Resolution

The Go bridge looks for the binary in this order:

  1. RLMConfig.go_binary_path parameter
  2. RLM_GO_BINARY environment variable
  3. Matching @recursive-llm/<platform> package
  4. ./bin/rlm-go (npm package location)
  5. ./go/rlm-go (development location)

Troubleshooting

Go binary not found

If you see "Go binary not found" errors:

  • On supported targets, confirm the matching @recursive-llm/<platform> package installed successfully
  • Ensure Go 1.25+ is installed: go version
  • Manually build: cd go && go build -o ../bin/rlm-go ./cmd/rlm
  • Or set RLM_GO_BINARY to a custom or downloaded binary path

S3 authentication errors

The S3StorageError class provides actionable remediation messages:

  • AUTH_FAILED: Check credentials config or AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY
  • ACCESS_DENIED: Verify IAM permissions for the bucket
  • BUCKET_NOT_FOUND: Verify the bucket name and region
  • REGION_MISMATCH: The bucket is in a different region

Timeout errors

For very large documents, increase the timeout:

TypeScript
const rlm = new RLM('gpt-4o-mini', {
  max_iterations: 50,
  timeout: 300,           // 5 min for LLM calls
  pythonia_timeout: 600000, // 10 min for bridge
});