Demo Setup

Run the interactive demos locally with LocalStack for S3 and bundled synthetic data. No AWS account required.

What you'll need

Docker (for LocalStack S3), Node.js 16+, Go 1.25+, and an OPENAI_API_KEY. That's it.

Prerequisites

DependencyRequiredNotes
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

Bash
# 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-latest image
  • 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

Bash
# 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

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

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

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

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

Bash
npx ts-node demo/run-demo.ts structured

This extracts a structured review analysis from the JSON files in the S3 bucket:

TypeScript
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":

FileFormatSizeDescription
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:

Bash
# 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

VariableRequiredDefaultDescription
OPENAI_API_KEY Required — API key for LLM provider. This is the only variable you must set.
No AWS credentials needed

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:

Bash
# 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 up for 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

Bash
# Stop and remove LocalStack container
docker compose -f demo/docker-compose.yml down