Demo Setup
Run the interactive demos locally with LocalStack for S3 and bundled synthetic data. No AWS account required.
Docker (for LocalStack S3), Node.js 16+, Go 1.25+, and an OPENAI_API_KEY. That's it.
Prerequisites
| Dependency | Required | Notes |
|---|---|---|
OPENAI_API_KEY |
Required | API key for OpenAI or any compatible provider |
| Docker | Required | For LocalStack S3 (only needed for S3 demos) |
| Node.js 16+ | Required | Runtime for TypeScript demos |
| Go 1.25+ | Required | For building the Go binary (or use pre-built) |
Quick Start
# 1. Clone and install
git clone https://github.com/howlerops/recursive-llm-ts.git
cd recursive-llm-ts
npm install
# 2. Set your API key
export OPENAI_API_KEY="sk-..."
# 3. Start LocalStack (S3 with auto-seeded demo data)
docker compose -f demo/docker-compose.yml up -d
# 4. Wait for seed data (~5 seconds)
docker logs rlm-demo-localstack 2>&1 | tail -20
# 5. Run all demos
npx ts-node demo/run-demo.ts all
The demo runner will execute three scenarios in sequence: local file context, S3 file context, and structured extraction from S3.
LocalStack S3 Setup
The demo uses LocalStack to provide a local S3-compatible API. No AWS account or credentials needed.
How it works
- Docker Compose starts LocalStack with
s3-latestimage - An init script (
init-localstack.sh) auto-creates a bucket and uploads seed data - S3 API is available at
http://localhost:4566 - Demo credentials:
accessKeyId: 'test',secretAccessKey: 'test'
Verify the bucket
# List all files in the demo bucket
aws --endpoint-url=http://localhost:4566 s3 ls s3://rlm-demo-docs/ --recursive
# Read a specific file
aws --endpoint-url=http://localhost:4566 s3 cp s3://rlm-demo-docs/docs/architecture.md -
LocalStack connection details
// Use this config to connect to the demo bucket
const fileConfig = {
type: 's3' as const,
path: 'rlm-demo-docs',
endpoint: 'http://localhost:4566',
region: 'us-east-1',
credentials: {
accessKeyId: 'test',
secretAccessKey: 'test',
},
};
Demo: Local File Context
Process the seed data directly from the local filesystem. No Docker required for this demo.
npx ts-node demo/run-demo.ts local
This reads all files from demo/seed-data/ and asks the LLM to analyze the company's architecture, products, and incidents.
const result = await rlm.completionFromFiles(
'Analyze these documents and provide: (1) a summary of what this ' +
'company does, (2) their key technical architecture decisions, ' +
'and (3) any notable incidents or challenges.',
{
type: 'local',
path: './demo/seed-data',
extensions: ['.md', '.json', '.ts', '.csv'],
excludePatterns: ['*.test.*'],
maxFileSize: 200_000,
}
);
Demo: S3 File Context (LocalStack)
Same data, but accessed through the S3 API via LocalStack. Demonstrates that S3FileStorage works identically to local files.
# Make sure LocalStack is running first
docker compose -f demo/docker-compose.yml up -d
npx ts-node demo/run-demo.ts s3
Demo: Structured Extraction from S3
Extract typed data from S3 files using a Zod schema. Demonstrates parallel structured extraction.
npx ts-node demo/run-demo.ts structured
This extracts a structured review analysis from the JSON files in the S3 bucket:
const schema = z.object({
overallSentiment: z.number().min(1).max(5),
totalReviews: z.number(),
topStrengths: z.array(z.string()),
topWeaknesses: z.array(z.string()),
productBreakdown: z.array(z.object({
product: z.string(),
avgRating: z.number(),
reviewCount: z.number(),
summary: z.string(),
})),
recommendations: z.array(z.string()),
});
const result = await rlm.structuredCompletionFromFiles(
'Analyze all product reviews and extract structured insights',
{ type: 's3', path: 'rlm-demo-docs', prefix: 'data/', ... },
schema,
{ parallelExecution: true }
);
Included Seed Data
The demo/seed-data/ directory contains synthetic data for a fictional "Acme Analytics Platform":
| File | Format | Size | Description |
|---|---|---|---|
docs/architecture.md |
Markdown | ~4KB | Full system architecture: ingestion, streaming, storage tiers, query engine |
docs/api-reference.md |
Markdown | ~4KB | REST API documentation with endpoints, parameters, and examples |
docs/getting-started.md |
Markdown | ~3KB | Onboarding guide with SDK setup and first event |
data/product-reviews.json |
JSON | ~6KB | 10 detailed product reviews with ratings, tags, and analysis |
data/quarterly-metrics.csv |
CSV | ~4KB | 6 months of revenue, customers, churn by region and product |
data/incident-reports.json |
JSON | ~5KB | 3 production incident post-mortems with timelines and action items |
reports/q2-2024-report.md |
Markdown | ~3KB | Quarterly business report with financials, product updates, and risks |
code/analytics-service.ts |
TypeScript | ~5KB | Event processing service with validation, rate limiting, and Kafka publishing |
Total seed data: ~34KB across 8 files. All data is synthetic — no licensing concerns.
Using Custom Data
Replace or add files in demo/seed-data/ and restart LocalStack:
# Add your own files
cp ~/my-project/docs/*.md demo/seed-data/docs/
# Restart LocalStack to re-seed
docker compose -f demo/docker-compose.yml down
docker compose -f demo/docker-compose.yml up -d
# Verify your files are in S3
aws --endpoint-url=http://localhost:4566 s3 ls s3://rlm-demo-docs/ --recursive
Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
OPENAI_API_KEY |
Required | — | API key for LLM provider. This is the only variable you must set. |
LocalStack uses dummy credentials (test/test) hardcoded in the demo scripts. You do not need AWS_ACCESS_KEY_ID or AWS_SECRET_ACCESS_KEY for the demos.
Optional: Full .env for all features
If you want to test all features beyond the demo (real S3, observability, etc.), here's the complete set:
# Required
OPENAI_API_KEY=sk-...
# Optional: Real S3 (instead of LocalStack)
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
AWS_SESSION_TOKEN=... # Only for temporary credentials
AWS_REGION=us-east-1
# Optional: Azure OpenAI
AZURE_API_KEY=...
# Optional: Observability
RLM_DEBUG=1 # Debug logging
OTEL_EXPORTER_OTLP_ENDPOINT=... # OpenTelemetry endpoint
LANGFUSE_PUBLIC_KEY=pk-... # Langfuse public key
LANGFUSE_SECRET_KEY=sk-... # Langfuse secret key
LANGFUSE_HOST=https://cloud.langfuse.com
# Optional: Binary override
RLM_GO_BINARY=/path/to/rlm-go
Troubleshooting
LocalStack won't start
- Ensure Docker is running:
docker ps - Check port 4566 isn't in use:
lsof -i :4566 - View logs:
docker logs rlm-demo-localstack
S3 demo returns "bucket not found"
- Wait a few seconds after
docker compose upfor the init script to complete - Check the init script ran:
docker logs rlm-demo-localstack 2>&1 | grep "Demo bucket ready"
Go binary not found
- Run
npm install(the postinstall script builds the binary) - Or build manually:
cd go && go build -o ../bin/rlm-go ./cmd/rlm
Cleanup
# Stop and remove LocalStack container
docker compose -f demo/docker-compose.yml down