Interactive Demo

Explore different use cases with simulated output. Select an example and click Run to see how RLM processes each scenario.

rlm-playground.ts
TypeScript

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.

TypeScript
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.

TypeScript
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.

TypeScript
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).

TypeScript
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.

TypeScript
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.

TypeScript
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.

Go
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.

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 your own binary and point RLM_GO_BINARY at it.

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 the binary from source in a multi-stage image.

Dockerfile
# 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.

TypeScript
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.

TypeScript
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.

TypeScript
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.

TypeScript
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.

TypeScript
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...