Interactive Demo
Explore different use cases with simulated output. Select an example and click Run to see how RLM processes each scenario.
Complete Examples
Copy-paste ready examples for common use cases.
Document Summarization
Process arbitrarily large documents and generate summaries. The recursive engine handles context splitting automatically.
import { RLM } from 'recursive-llm-ts';
import * as fs from 'fs';
const rlm = new RLM('gpt-4o-mini', {
api_key: process.env.OPENAI_API_KEY,
max_iterations: 20,
});
// Read a very large document
const document = fs.readFileSync('research-paper.txt', 'utf-8');
console.log(`Document size: ${document.length} characters`);
const result = await rlm.completion(
'Provide a comprehensive summary of this research paper, including: ' +
'the main hypothesis, methodology, key findings, and conclusions.',
document
);
console.log('Summary:', result.result);
console.log('LLM calls:', result.stats.llm_calls);
console.log('Recursion depth:', result.stats.depth);
await rlm.cleanup();
Call Transcript Analysis
Extract structured data from sales call transcripts using Zod schemas with parallel execution.
import { RLM } from 'recursive-llm-ts';
import { z } from 'zod';
const rlm = new RLM('gpt-4o-mini', {
api_key: process.env.OPENAI_API_KEY,
});
const callAnalysisSchema = z.object({
overallSentiment: z.number().min(1).max(5)
.describe('1=very negative, 5=very positive'),
sentimentExplanation: z.string(),
customerIntent: z.enum([
'purchase', 'support', 'complaint', 'inquiry', 'cancellation'
]),
keyTopics: z.array(z.object({
topic: z.string(),
sentiment: z.enum(['positive', 'negative', 'neutral']),
quotes: z.array(z.string()),
})),
actionItems: z.array(z.object({
description: z.string(),
assignee: z.string(),
priority: z.enum(['high', 'medium', 'low']),
})),
summary: z.string(),
});
const result = await rlm.structuredCompletion(
'Analyze this sales call transcript comprehensively',
callTranscript,
callAnalysisSchema,
{ parallelExecution: true, maxRetries: 3 }
);
// Fully typed result
console.log('Sentiment:', result.result.overallSentiment);
console.log('Intent:', result.result.customerIntent);
console.log('Topics:', result.result.keyTopics.length);
console.log('Action Items:', result.result.actionItems);
await rlm.cleanup();
Codebase Analysis from Files
Process an entire codebase directory and extract architectural insights.
import { RLM, FileContextBuilder } from 'recursive-llm-ts';
import { z } from 'zod';
const rlm = new RLM('gpt-4o-mini', {
api_key: process.env.OPENAI_API_KEY,
});
const fileConfig = {
type: 'local' as const,
path: '/path/to/project/src',
extensions: ['.ts', '.tsx', '.js'],
excludePatterns: [
'*.test.ts',
'*.spec.ts',
'node_modules/**',
'__tests__/**',
],
maxFileSize: 200_000, // Skip files over 200KB
maxTotalSize: 5_000_000, // 5MB total limit
};
// Preview what files will be included
const builder = new FileContextBuilder(fileConfig);
const files = await builder.listMatchingFiles();
console.log(`Will process ${files.length} files`);
// Extract architecture info
const archSchema = z.object({
layers: z.array(z.object({
name: z.string(),
description: z.string(),
files: z.array(z.string()),
})),
patterns: z.array(z.string()),
dependencies: z.array(z.object({
from: z.string(),
to: z.string(),
type: z.enum(['import', 'api-call', 'event']),
})),
recommendations: z.array(z.string()),
});
const result = await rlm.structuredCompletionFromFiles(
'Analyze the architecture: identify layers, patterns, ' +
'key dependencies, and areas for improvement',
fileConfig,
archSchema
);
console.log('Architecture Layers:');
for (const layer of result.result.layers) {
console.log(` ${layer.name}: ${layer.description}`);
}
console.log('\nPatterns:', result.result.patterns);
console.log('Files processed:', result.fileStorage?.files.length);
await rlm.cleanup();
S3 Report Processing
Process documents from S3 or S3-compatible storage (MinIO, LocalStack, DigitalOcean Spaces).
import { RLM } from 'recursive-llm-ts';
import { z } from 'zod';
const rlm = new RLM('gpt-4o-mini', {
api_key: process.env.OPENAI_API_KEY,
});
// AWS S3 with explicit credentials
const awsResult = await rlm.completionFromFiles(
'Summarize the quarterly reports and identify trends',
{
type: 's3',
path: 'company-reports',
prefix: 'quarterly/2024/',
extensions: ['.md', '.txt', '.csv'],
credentials: {
accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
},
region: 'us-west-2',
}
);
// MinIO (local S3-compatible)
const minioResult = await rlm.completionFromFiles(
'Analyze the test results',
{
type: 's3',
path: 'test-data',
endpoint: 'http://localhost:9000',
credentials: {
accessKeyId: 'minioadmin',
secretAccessKey: 'minioadmin',
},
}
);
// Using env vars (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
const envResult = await rlm.completionFromFiles(
'What are the key metrics?',
{
type: 's3',
path: 'metrics-bucket',
prefix: 'daily/',
extensions: ['.json'],
}
);
console.log('S3 result:', awsResult.result);
console.log('Files:', awsResult.fileStorage?.files.length);
await rlm.cleanup();
Full Observability Setup
Enable debug logging, OpenTelemetry tracing, and Langfuse integration simultaneously.
import { RLM } from 'recursive-llm-ts';
const rlm = new RLM('gpt-4o-mini', {
api_key: process.env.OPENAI_API_KEY,
// Meta-agent for query optimization
meta_agent: {
enabled: true,
model: 'gpt-4o', // Use a stronger model for optimization
},
// Full observability stack
observability: {
// Debug logging
debug: true,
log_output: 'stderr', // or 'stdout', or '/var/log/rlm.log'
// OpenTelemetry
trace_enabled: true,
trace_endpoint: 'http://localhost:4318',
service_name: 'my-rlm-app',
// Langfuse
langfuse_enabled: true,
langfuse_public_key: process.env.LANGFUSE_PUBLIC_KEY,
langfuse_secret_key: process.env.LANGFUSE_SECRET_KEY,
langfuse_host: 'https://cloud.langfuse.com',
},
});
const result = await rlm.completion(
'what happened in the meeting?', // Vague query - meta-agent will optimize
longMeetingTranscript
);
// Access trace events programmatically
const events = rlm.getTraceEvents();
console.log(`\nTrace Events (${events.length}):`);
for (const event of events) {
const attrs = Object.entries(event.attributes)
.map(([k, v]) => `${k}=${v}`)
.join(', ');
console.log(` [${event.type}] ${event.name} {${attrs}}`);
if (event.duration) {
console.log(` Duration: ${event.duration}ms`);
}
}
await rlm.cleanup();
Custom LLM Providers
Use Azure OpenAI, Amazon Bedrock, Ollama, or any OpenAI-compatible API.
import { RLM } from 'recursive-llm-ts';
// Azure OpenAI
const azureRlm = new RLM('gpt-4o', {
api_base: 'https://my-resource.openai.azure.com/openai/deployments/gpt-4o',
api_key: process.env.AZURE_API_KEY,
api_version: '2024-02-15-preview',
});
// Amazon Bedrock (via LiteLLM proxy)
const bedrockRlm = new RLM('bedrock/anthropic.claude-3-sonnet-20240229-v1:0', {
api_base: 'http://localhost:4000', // LiteLLM proxy
api_key: process.env.LITELLM_API_KEY,
});
// Ollama (local models)
const ollamaRlm = new RLM('openai/llama3.1', {
api_base: 'http://localhost:11434/v1',
api_key: 'ollama', // Ollama doesn't need a real key
});
// Any OpenAI-compatible API
const customRlm = new RLM('openai/my-model', {
api_base: 'https://my-api.example.com/v1',
api_key: process.env.CUSTOM_API_KEY,
});
// All instances work the same way
const result = await azureRlm.completion('Summarize', document);
console.log(result.result);
Go Module Usage
Use the RLM engine directly in Go projects for maximum performance.
package main
import (
"encoding/json"
"fmt"
"os"
"github.com/howlerops/recursive-llm-ts/go/rlm"
)
func main() {
engine := rlm.New("gpt-4o-mini", rlm.Config{
MaxDepth: 5,
MaxIterations: 30,
APIKey: os.Getenv("OPENAI_API_KEY"),
MetaAgent: &rlm.MetaAgentConfig{
Enabled: true,
},
Observability: &rlm.ObservabilityConfig{
Debug: true,
TraceEnabled: true,
},
})
// Basic completion
answer, stats, err := engine.Completion(
"Summarize the key points",
largeDocument,
)
if err != nil {
fmt.Fprintf(os.Stderr, "Error: %v\n", err)
os.Exit(1)
}
fmt.Printf("Answer: %s\nLLM calls: %d\n", answer, stats.LlmCalls)
// Structured extraction
schema := &rlm.JSONSchema{
Type: "object",
Properties: map[string]*rlm.JSONSchema{
"summary": {Type: "string"},
"score": {Type: "number"},
"topics": {Type: "array", Items: &rlm.JSONSchema{Type: "string"}},
},
Required: []string{"summary", "score", "topics"},
}
result, stats, err := engine.StructuredCompletion(
"Extract summary, score, and topics",
document,
&rlm.StructuredConfig{Schema: schema, MaxRetries: 3},
)
if err != nil {
fmt.Fprintf(os.Stderr, "Error: %v\n", err)
os.Exit(1)
}
out, _ := json.MarshalIndent(result, "", " ")
fmt.Println(string(out))
}
Docker Deployment
Three supported container options: auto-installed Linux platform package, explicit binary path, or source-build fallback.
Option 1: Use the published Linux binary package. This is the simplest path for linux-x64 and linux-arm64 containers.
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 your own binary and point RLM_GO_BINARY at it.
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 the binary from source in a multi-stage image.
# Stage 1: 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 GOOS=linux go build -ldflags="-s -w" -o rlm-go ./cmd/rlm
# Stage 2: Build Node.js
FROM node:22-alpine AS node-builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev --ignore-scripts
# Stage 3: 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 NODE_ENV=production
ENV RLM_GO_BINARY=/app/bin/rlm-go
CMD ["node", "your-app.js"]
Real-Time Streaming
Stream completions token-by-token for real-time UI updates. Supports both text and structured object streaming with cancellation.
import { RLM } from 'recursive-llm-ts';
const rlm = new RLM('gpt-4o-mini', {
api_key: process.env.OPENAI_API_KEY,
});
// Stream text tokens in real-time
const stream = await rlm.streamCompletion(
'Provide a detailed analysis of this report',
quarterlyReport
);
// Iterate over chunks as they arrive
for await (const chunk of stream) {
switch (chunk.type) {
case 'text':
process.stdout.write(chunk.text);
break;
case 'metadata':
console.log('\nStats:', chunk.stats);
break;
case 'done':
console.log('\nComplete!', chunk.stats);
break;
}
}
// Or collect everything at once
const stream2 = await rlm.streamCompletion('Summarize', doc);
const fullText = await stream2.toText();
console.log(fullText);
// Stream with cancellation (30s timeout)
const controller = new AbortController();
setTimeout(() => controller.abort(), 30000);
const stream3 = await rlm.streamCompletion(
'Summarize', longDoc, controller.signal
);
const text = await stream3.toText();
// Stream structured objects
import { z } from 'zod';
const schema = z.object({
summary: z.string(),
score: z.number(),
tags: z.array(z.string()),
});
const objStream = await rlm.streamStructuredCompletion(
'Extract data', context, schema
);
for await (const chunk of objStream) {
if (chunk.type === 'partial_object') {
console.log('Partial:', chunk.object);
}
}
const finalObj = await objStream.toObject();
console.log('Final:', finalObj);
await rlm.cleanup();
Retry & Multi-Provider Fallback
Configure automatic retries with backoff strategies and multi-provider fallback chains for production resilience.
import { RLM, withRetry, withFallback } from 'recursive-llm-ts';
// RLM with built-in retry and fallback
const rlm = new RLM('gpt-4o-mini', {
api_key: process.env.OPENAI_API_KEY,
// Retry config
retry: {
maxRetries: 3,
baseDelay: 1000,
backoff: 'exponential',
jitter: true,
onRetry: (attempt, error, delay) => {
console.log(`Retry ${attempt} in ${delay}ms: ${error.message}`);
},
},
// Multi-provider fallback
fallback: {
models: ['gpt-4o-mini', 'gpt-4o', 'claude-sonnet-4-20250514'],
},
});
const result = await rlm.completion('Summarize', doc);
console.log('Used model:', result.model);
// Standalone retry utility
const data = await withRetry(
async () => {
const res = await fetch('https://api.example.com/data');
if (!res.ok) throw new Error(`HTTP ${res.status}`);
return res.json();
},
{ maxRetries: 3, backoff: 'exponential', baseDelay: 500 }
);
// Standalone fallback utility
const result2 = await withFallback(
async (model) => {
const rlm = new RLM(model, { api_key: process.env.OPENAI_API_KEY });
return rlm.completion('Summarize', doc);
},
{ models: ['gpt-4o-mini', 'gpt-4o'] },
{ maxRetries: 2, baseDelay: 100 }
);
console.log('Fallback used:', result2._usedModel);
Structured Error Handling
Use typed error classes for precise error handling with actionable suggestions.
import {
RLM,
RLMError,
RLMRateLimitError,
RLMTimeoutError,
RLMValidationError,
RLMProviderError,
RLMBinaryError,
RLMAbortError,
classifyError,
} from 'recursive-llm-ts';
const rlm = new RLM('gpt-4o-mini', {
api_key: process.env.OPENAI_API_KEY,
});
try {
const result = await rlm.completion('Summarize', doc);
console.log(result.result);
} catch (err) {
if (err instanceof RLMRateLimitError) {
// Rate limited - wait and retry
console.log(`Rate limited. Retry after: ${err.retryAfter}s`);
console.log(`Suggestion: ${err.suggestion}`);
} else if (err instanceof RLMTimeoutError) {
// Request timed out
console.log(`Timed out after ${err.timeout}ms`);
console.log(`Retryable: ${err.retryable}`); // true
} else if (err instanceof RLMValidationError) {
// Schema validation failed
console.log(`Field: ${err.field}`);
console.log(`Suggestion: ${err.suggestion}`);
} else if (err instanceof RLMProviderError) {
// LLM provider error
console.log(`Provider: ${err.provider}, Status: ${err.statusCode}`);
} else if (err instanceof RLMBinaryError) {
// Go binary not found or crashed
console.log(`Binary path: ${err.binaryPath}`);
} else if (err instanceof RLMAbortError) {
// User cancelled
console.log('Operation was cancelled');
} else if (err instanceof RLMError) {
// Generic RLM error
console.log(`[${err.code}] ${err.message}`);
console.log(`Retryable: ${err.retryable}`);
}
}
// Auto-classify unknown errors
try {
await fetch('https://api.openai.com/...');
} catch (rawError) {
const classified = classifyError(rawError);
console.log(classified.constructor.name); // e.g., RLMTimeoutError
console.log(classified.suggestion);
}
Events & Monitoring
Subscribe to lifecycle events for real-time monitoring, logging, and custom integrations.
import { RLM } from 'recursive-llm-ts';
const rlm = new RLM('gpt-4o-mini', {
api_key: process.env.OPENAI_API_KEY,
cache: { enabled: true },
retry: { maxRetries: 3 },
});
// Monitor all LLM calls
rlm.on('llm_call', (event) => {
console.log(`[LLM] Calling ${event.model}`);
console.log(` Query length: ${event.queryLength}`);
console.log(` Context length: ${event.contextLength}`);
});
// Track cache performance
rlm.on('cache', (event) => {
console.log(`[Cache] ${event.action}`);
});
// Monitor retries
rlm.on('retry', (event) => {
console.log(`[Retry] Attempt ${event.attempt} after ${event.delay}ms`);
console.log(` Error: ${event.error.message}`);
});
// Track errors
rlm.on('error', (event) => {
console.error(`[Error] in ${event.operation}:`, event.error.message);
});
// Completion lifecycle
rlm.on('completion_start', (event) => {
console.log(`[Start] ${event.model} - "${event.query.slice(0, 50)}..."`);
});
rlm.on('completion_end', (event) => {
console.log(`[Done] ${event.model} in ${event.duration}ms`);
console.log(` LLM calls: ${event.stats.llm_calls}`);
});
// Run a completion - events fire automatically
const result = await rlm.completion('Summarize', doc);
console.log(result.result);
// Check cache stats after multiple calls
const stats = rlm.getCacheStats();
if (stats) {
console.log(`\nCache: ${stats.hits} hits, ${stats.misses} misses`);
console.log(`Hit rate: ${(stats.hitRate * 100).toFixed(1)}%`);
}
await rlm.cleanup();
Builder Pattern & Config Validation
Use the fluent builder API and factory methods for clean configuration. Validate configs to catch errors early.
import { RLM, validateConfig, assertValidConfig } from 'recursive-llm-ts';
// Fluent builder for complex configs
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, ttl: 3600000 })
.enableRetry({ maxRetries: 3, backoff: 'exponential' })
.build();
// Factory methods for common setups
const devRlm = RLM.withDebug('gpt-4o-mini');
const envRlm = RLM.fromEnv();
const azureRlm = RLM.forAzure(
'gpt-4o',
'https://my-resource.openai.azure.com',
process.env.AZURE_API_KEY!
);
// Validate configuration before use
const result = validateConfig({
api_key: 'sk-...',
max_detph: 5, // Catches typo!
max_iterations: -1, // Catches invalid value!
cache: { enabled: true, maxEntries: -5 },
});
console.log('Valid:', result.valid);
for (const issue of result.issues) {
console.log(`[${issue.level}] ${issue.field}: ${issue.message}`);
}
// [warning] max_detph: Unknown key (possible typo for "max_depth")
// [error] max_iterations: must be positive
// [error] cache.maxEntries: must be positive
// Or throw on any errors
try {
assertValidConfig({ max_depth: -1 });
} catch (e) {
console.log(e.message); // "Invalid configuration: ..."
}
// Format results for display
const completion = await rlm.completion('Summarize', doc);
const formatter = rlm.formatResult(completion);
console.log(formatter.prettyStats());
// LLM Calls: 8 | Iterations: 12 | Depth: 2
console.log(formatter.toMarkdown());
// ## Result\n...\n## Stats\n...