recursive-llm-ts 4.3.2 → 4.3.3

package/README.md

@@ -353,6 +353,194 @@ const result = await rlm.completion(
 
 See the [LiteLLM documentation](https://docs.litellm.ai/docs/providers) for the complete list of supported providers and their configuration.
 
+## Docker Deployment
+
+### Basic Dockerfile with Go Build
+
+To containerize your application that uses `recursive-llm-ts`, install Go 1.21+ in your Docker image to build the binary during `npm install`:
+
+```dockerfile
+FROM node:20-alpine
+
+# Install Go 1.21+ for building the RLM binary
+RUN apk add --no-cache go
+
+# Set Go environment
+ENV GOPATH=/go
+ENV PATH=$PATH:$GOPATH/bin
+
+WORKDIR /app
+
+COPY package*.json ./
+RUN npm install
+
+COPY . .
+
+ENV OPENAI_API_KEY=""
+ENV NODE_ENV=production
+
+CMD ["node", "your-app.js"]
+```
+
+### Multi-Stage Build (Recommended for Production)
+
+For optimal image size and security, use a multi-stage build:
+
+```dockerfile
+# Stage 1: Build the Go binary
+FROM golang:1.21-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 dependencies
+FROM node:20-alpine AS node-builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --omit=dev
+
+# Stage 3: Final runtime image
+FROM node:20-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 package*.json ./
+COPY dist/ ./dist/
+
+ENV NODE_ENV=production
+ENV RLM_GO_BINARY=/app/bin/rlm-go
+ENV OPENAI_API_KEY=""
+
+CMD ["node", "dist/index.js"]
+```
+
+**Benefits:** Smaller image (~150MB vs ~500MB), faster builds with caching, more secure.
+
+### Docker Compose
+
+```yaml
+version: '3.8'
+services:
+  app:
+    build: .
+    environment:
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+      - NODE_ENV=production
+    ports:
+      - "3000:3000"
+```
+
+### Installing Go in Different Base Images
+
+```dockerfile
+# Alpine
+RUN apk add --no-cache go
+
+# Debian/Ubuntu
+RUN apt-get update && apt-get install -y golang-1.21
+
+# Or use pre-built binary (no Go required)
+# Download from GitHub releases and copy to /app/bin/rlm-go
+```
+
+## Using the Go Module Directly
+
+The Go implementation can be used as a standalone library in Go projects.
+
+### Installation
+
+```bash
+go get github.com/jbeck018/recursive-llm-ts/go
+```
+
+### Usage
+
+```go
+package main
+
+import (
+    "fmt"
+    "os"
+
+    "github.com/jbeck018/recursive-llm-ts/go/rlm"
+)
+
+func main() {
+    config := rlm.Config{
+        MaxDepth:      5,
+        MaxIterations: 30,
+        APIKey:        os.Getenv("OPENAI_API_KEY"),
+    }
+
+    engine := rlm.New("gpt-4o-mini", config)
+
+    answer, stats, err := engine.Completion(
+        "What are the key points?",
+        "Your long document here...",
+    )
+    if err != nil {
+        fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+        os.Exit(1)
+    }
+
+    fmt.Printf("Answer: %s\n", answer)
+    fmt.Printf("Stats: %d LLM calls, %d iterations\n",
+        stats.LlmCalls, stats.Iterations)
+}
+```
+
+### Structured Output
+
+```go
+schema := &rlm.JSONSchema{
+    Type: "object",
+    Properties: map[string]*rlm.JSONSchema{
+        "summary": {Type: "string"},
+        "score":   {Type: "number"},
+    },
+    Required: []string{"summary", "score"},
+}
+
+config := &rlm.StructuredConfig{
+    Schema:     schema,
+    MaxRetries: 3,
+}
+
+result, stats, err := engine.StructuredCompletion(
+    "Summarize and score",
+    document,
+    config,
+)
+```
+
+### Building from Source
+
+```bash
+cd go
+
+# Standard build
+go build -o rlm-go ./cmd/rlm
+
+# Optimized (smaller binary)
+go build -ldflags="-s -w" -o rlm-go ./cmd/rlm
+
+# Cross-compile
+GOOS=linux GOARCH=amd64 go build -o rlm-linux-amd64 ./cmd/rlm
+GOOS=darwin GOARCH=arm64 go build -o rlm-darwin-arm64 ./cmd/rlm
+```
+
+### Running Tests
+
+```bash
+cd go
+go test -v ./rlm/...
+```
+
 ## How It Works
 
 This package provides a TypeScript wrapper around a Go implementation of Recursive-LLM, enabling seamless integration into Node.js/TypeScript applications without Python dependencies. The Go binary is built locally (or supplied via `RLM_GO_BINARY`) and invoked for completions.

package/go/README.md

@@ -1,24 +1,92 @@
-# RLM Go Binary
+# RLM Go Module
 
 Go implementation of Recursive Language Models (RLM) based on the [original Python implementation](https://github.com/alexzhang13/rlm).
 
 ## Overview
 
-This is a self-contained Go binary that implements the RLM algorithm, allowing language models to process extremely long contexts (100k+ tokens) by storing context as a variable and allowing recursive exploration.
+This is both a standalone Go library and CLI binary that implements the RLM algorithm, allowing language models to process extremely long contexts (100k+ tokens) by storing context as a variable and allowing recursive exploration.
 
 **Key Difference from Python**: Uses JavaScript REPL instead of Python REPL for code execution.
 
-## Building
+## Installation
+
+### As a Go Library
+
+```bash
+go get github.com/jbeck018/recursive-llm-ts/go
+```
+
+### Usage as Library
+
+```go
+package main
+
+import (
+    "fmt"
+    "os"
+
+    "github.com/jbeck018/recursive-llm-ts/go/rlm"
+)
+
+func main() {
+    config := rlm.Config{
+        MaxDepth:      5,
+        MaxIterations: 30,
+        APIKey:        os.Getenv("OPENAI_API_KEY"),
+    }
+
+    engine := rlm.New("gpt-4o-mini", config)
+
+    answer, stats, err := engine.Completion(
+        "What are the key themes?",
+        "Your long document here...",
+    )
+    if err != nil {
+        fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+        os.Exit(1)
+    }
+
+    fmt.Printf("Answer: %s\n", answer)
+    fmt.Printf("Stats: %d LLM calls, %d iterations\n",
+        stats.LlmCalls, stats.Iterations)
+}
+```
+
+### Structured Output
+
+```go
+schema := &rlm.JSONSchema{
+    Type: "object",
+    Properties: map[string]*rlm.JSONSchema{
+        "summary": {Type: "string"},
+        "score":   {Type: "number"},
+    },
+    Required: []string{"summary", "score"},
+}
+
+config := &rlm.StructuredConfig{
+    Schema:     schema,
+    MaxRetries: 3,
+}
+
+result, stats, err := engine.StructuredCompletion(
+    "Summarize and score",
+    document,
+    config,
+)
+```
+
+## Building the CLI Binary
 
 ```bash
 # Build the binary
-go build -o rlm ./cmd/rlm
+go build -o rlm-go ./cmd/rlm
 
 # Run tests
-go test ./internal/rlm/... -v
+go test ./rlm/... -v
 
 # Build with optimization
-go build -ldflags="-s -w" -o rlm ./cmd/rlm
+go build -ldflags="-s -w" -o rlm-go ./cmd/rlm
 ```
 
 ## Usage
@@ -181,13 +249,16 @@ Works with any OpenAI-compatible API:
 
 ```
 cmd/rlm/main.go              # CLI entry point (JSON I/O)
-internal/rlm/
+rlm/                         # Public package (importable)
+├── doc.go                   # Package documentation
 ├── rlm.go                   # Core RLM logic
 ├── types.go                 # Config and stats types
+├── structured.go            # Structured completion with schema validation
 ├── parser.go                # FINAL() extraction
 ├── prompt.go                # System prompt builder
 ├── repl.go                  # JavaScript REPL (goja)
-└── openai.go                # OpenAI API client
+├── openai.go                # OpenAI API client
+└── errors.go                # Error types
 ```
 
 ## Error Handling
@@ -212,16 +283,16 @@ echo '{
 
 ```bash
 # Run all tests
-go test ./internal/rlm/... -v
+go test ./rlm/... -v
 
 # Run specific test
-go test ./internal/rlm -run TestParser -v
+go test ./rlm -run TestParser -v
 
 # With coverage
-go test ./internal/rlm/... -cover
+go test ./rlm/... -cover
 
 # Benchmark
-go test ./internal/rlm/... -bench=. -benchmem
+go test ./rlm/... -bench=. -benchmem
 ```
 
 ## Performance
@@ -332,7 +403,7 @@ Check the JavaScript syntax. Use `console.log()` not `print()`, or ensure `print
 ## Contributing
 
 1. Write tests for new features
-2. Ensure all tests pass: `go test ./internal/rlm/... -v`
+2. Ensure all tests pass: `go test ./rlm/... -v`
 3. Format code: `go fmt ./...`
 4. Update documentation
 

package/go/cmd/rlm/main.go

@@ -6,7 +6,7 @@ import (
 	"io"
 	"os"
 
-	"recursive-llm-go/internal/rlm"
+	"github.com/jbeck018/recursive-llm-ts/go/rlm"
 )
 
 type requestPayload struct {

package/go/go.mod

@@ -1,4 +1,4 @@
-module recursive-llm-go
+module github.com/jbeck018/recursive-llm-ts/go
 
 go 1.21
 

package/go/rlm/doc.go

@@ -0,0 +1,82 @@
+// Package rlm provides a Recursive Language Model (RLM) engine for Go.
+//
+// RLM enables language models to use tools and make recursive calls to themselves,
+// allowing for complex multi-step reasoning and task decomposition. This implements
+// the technique from the paper "Recursive Language Models" by Alex Zhang and Omar Khattab (MIT, 2025).
+//
+// # Installation
+//
+// To use this package in your Go project:
+//
+//	go get github.com/jbeck018/recursive-llm-ts/go
+//
+// # Basic Usage
+//
+// Create an RLM engine and execute a completion:
+//
+//	import "github.com/jbeck018/recursive-llm-ts/go/rlm"
+//
+//	config := rlm.Config{
+//	    MaxDepth:      5,
+//	    MaxIterations: 30,
+//	    APIKey:        os.Getenv("OPENAI_API_KEY"),
+//	}
+//
+//	engine := rlm.New("gpt-4", config)
+//	answer, stats, err := engine.Completion("What is 2+2?", "")
+//
+// # Structured Output
+//
+// For structured JSON output with validation:
+//
+//	schema := &rlm.JSONSchema{
+//	    Type: "object",
+//	    Properties: map[string]*rlm.JSONSchema{
+//	        "name": {Type: "string"},
+//	        "age":  {Type: "number"},
+//	    },
+//	    Required: []string{"name", "age"},
+//	}
+//
+//	config := &rlm.StructuredConfig{
+//	    Schema:     schema,
+//	    MaxRetries: 3,
+//	}
+//
+//	result, stats, err := engine.StructuredCompletion(
+//	    "Extract person info",
+//	    "John is 30 years old",
+//	    config,
+//	)
+//
+// # Recursive Calls
+//
+// The LLM can make recursive calls to itself using the recursive_llm() function
+// available in the JavaScript REPL environment during execution. This enables
+// complex multi-step reasoning and task decomposition.
+//
+// # Supported Providers
+//
+// RLM works with any OpenAI-compatible API:
+//   - OpenAI (default)
+//   - Azure OpenAI
+//   - Ollama
+//   - LiteLLM
+//   - Any OpenAI-compatible endpoint
+//
+// Configure the provider using Config.APIBase:
+//
+//	config := rlm.Config{
+//	    APIBase: "https://your-azure-endpoint.openai.azure.com/v1",
+//	    APIKey:  os.Getenv("AZURE_API_KEY"),
+//	}
+//
+// # Error Handling
+//
+// All methods return typed errors that can be checked with errors.As():
+//
+//	var maxDepthErr *rlm.MaxDepthError
+//	if errors.As(err, &maxDepthErr) {
+//	    fmt.Printf("Hit max depth: %d\n", maxDepthErr.MaxDepth)
+//	}
+package rlm

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "recursive-llm-ts",
-  "version": "4.3.2",
+  "version": "4.3.3",
   "description": "TypeScript bridge for recursive-llm: Recursive Language Models for unbounded context processing with structured outputs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",