recursive-llm-ts 4.3.2 → 4.3.5

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/go/{internal/rlm → rlm}/openai.go

@@ -87,7 +87,9 @@ func CallChatCompletion(request ChatRequest) (string, error) {
 	if err != nil {
 		return "", err
 	}
-	defer resp.Body.Close()
+	defer func() {
+		_ = resp.Body.Close()
+	}()
 
 	responseBody, err := io.ReadAll(resp.Body)
 	if err != nil {

package/go/{internal/rlm → rlm}/repl.go

@@ -29,7 +29,9 @@ func (r *REPLExecutor) Execute(code string, env map[string]interface{}) (string,
 	var output strings.Builder
 
 	for key, value := range env {
-		vm.Set(key, value)
+		if err := vm.Set(key, value); err != nil {
+			return "", fmt.Errorf("failed to set environment variable %s: %w", key, err)
+		}
 	}
 
 	writeOutput := func(call goja.FunctionCall) goja.Value {
@@ -46,9 +48,13 @@ func (r *REPLExecutor) Execute(code string, env map[string]interface{}) (string,
 		"log": writeOutput,
 	}
 
-	vm.Set("console", console)
-	vm.Set("print", writeOutput)
-	vm.Set("len", func(value goja.Value) int {
+	if err := vm.Set("console", console); err != nil {
+		return "", fmt.Errorf("failed to set console: %w", err)
+	}
+	if err := vm.Set("print", writeOutput); err != nil {
+		return "", fmt.Errorf("failed to set print: %w", err)
+	}
+	if err := vm.Set("len", func(value goja.Value) int {
 		if value == nil || value == goja.Undefined() || value == goja.Null() {
 			return 0
 		}
@@ -63,7 +69,9 @@ func (r *REPLExecutor) Execute(code string, env map[string]interface{}) (string,
 			}
 		}
 		return len(value.String())
-	})
+	}); err != nil {
+		return "", fmt.Errorf("failed to set len: %w", err)
+	}
 
 	if _, err := vm.RunString(jsBootstrap); err != nil {
 		return "", NewREPLError("Bootstrap execution error", jsBootstrap, err)

package/go/{internal/rlm → rlm}/structured.go

@@ -230,7 +230,7 @@ func generateSchemaConstraints(schema *JSONSchema) string {
 				}
 			}
 			
-			if fieldSchema.Enum != nil && len(fieldSchema.Enum) > 0 {
+			if len(fieldSchema.Enum) > 0 {
 				constraints = append(constraints, fmt.Sprintf("- %s must be EXACTLY one of these values: %s (use these exact strings, do not modify)", fieldName, strings.Join(fieldSchema.Enum, ", ")))
 			}
 			
@@ -274,7 +274,7 @@ func generateSchemaConstraints(schema *JSONSchema) string {
 					}
 				}
 				
-				if fieldSchema.Enum != nil && len(fieldSchema.Enum) > 0 {
+				if len(fieldSchema.Enum) > 0 {
 					constraints = append(constraints, fmt.Sprintf("- Each item's %s must be EXACTLY one of these values: %s (copy exactly, do not modify these strings)", fieldName, strings.Join(fieldSchema.Enum, ", ")))
 				}
 			}
@@ -348,7 +348,7 @@ func generateFieldQuery(fieldName string, schema *JSONSchema) string {
 		}
 		
 	case "string":
-		if schema.Enum != nil && len(schema.Enum) > 0 {
+		if len(schema.Enum) > 0 {
 			queryParts = append(queryParts, fmt.Sprintf("Return EXACTLY one of these values: %s (use exact strings).", strings.Join(schema.Enum, ", ")))
 		} else {
 			queryParts = append(queryParts, "Return a string value.")
@@ -393,7 +393,6 @@ func parseAndValidateJSON(result string, schema *JSONSchema) (map[string]interfa
 					for _, v := range valueMap {
 						if arr, ok := v.([]interface{}); ok {
 							value = arr
-							break
 						}
 					}
 				case "string":
@@ -401,7 +400,6 @@ func parseAndValidateJSON(result string, schema *JSONSchema) (map[string]interfa
 					for _, v := range valueMap {
 						if str, ok := v.(string); ok {
 							value = str
-							break
 						}
 					}
 				case "number":
@@ -410,7 +408,6 @@ func parseAndValidateJSON(result string, schema *JSONSchema) (map[string]interfa
 						switch v.(type) {
 						case float64, float32, int, int32, int64:
 							value = v
-							break
 						}
 					}
 				case "boolean":
@@ -418,7 +415,6 @@ func parseAndValidateJSON(result string, schema *JSONSchema) (map[string]interfa
 					for _, v := range valueMap {
 						if b, ok := v.(bool); ok {
 							value = b
-							break
 						}
 					}
 				default:
@@ -426,7 +422,6 @@ func parseAndValidateJSON(result string, schema *JSONSchema) (map[string]interfa
 					if len(valueMap) == 1 {
 						for _, v := range valueMap {
 							value = v
-							break
 						}
 					}
 				}
@@ -584,7 +579,7 @@ func buildExampleJSON(schema *JSONSchema) string {
 		
 		switch fieldSchema.Type {
 		case "string":
-			if fieldSchema.Enum != nil && len(fieldSchema.Enum) > 0 {
+			if len(fieldSchema.Enum) > 0 {
 				example[fieldName] = fieldSchema.Enum[0]
 			} else {
 				example[fieldName] = "example value"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "recursive-llm-ts",
-  "version": "4.3.2",
+  "version": "4.3.5",
   "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",