recursive-llm-ts 5.0.1 → 5.0.2

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "recursive-llm-ts",
-  "version": "5.0.1",
+  "version": "5.0.2",
   "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",
   "files": [
     "dist",
-    "bin",
-    "go",
+    "go/cmd",
+    "go/go.mod",
+    "go/go.sum",
+    "go/rlm/*.go",
+    "!go/rlm/*_test.go",
     "scripts/build-go-binary.js"
   ],
   "scripts": {

package/go/README.md

@@ -1,426 +0,0 @@
-# RLM Go Module
-
-Go implementation of Recursive Language Models (RLM) based on the [original Python implementation](https://github.com/alexzhang13/rlm).
-
-## Overview
-
-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.
-
-## Installation
-
-### As a Go Library
-
-```bash
-go get github.com/howlerops/recursive-llm-ts/go
-```
-
-### Usage as Library
-
-```go
-package main
-
-import (
-    "fmt"
-    "os"
-
-    "github.com/howlerops/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-go ./cmd/rlm
-
-# Run tests
-go test ./rlm/... -v
-
-# Build with optimization
-go build -ldflags="-s -w" -o rlm-go ./cmd/rlm
-```
-
-## Usage
-
-The binary accepts JSON input on stdin and returns JSON output on stdout.
-
-### Input Format
-
-```json
-{
-  "model": "gpt-4o-mini",
-  "query": "What are the main themes?",
-  "context": "Your long document here...",
-  "config": {
-    "recursive_model": "gpt-4o-mini",
-    "api_base": "https://api.openai.com/v1",
-    "api_key": "sk-...",
-    "max_depth": 5,
-    "max_iterations": 30,
-    "temperature": 0.7
-  }
-}
-```
-
-### Output Format
-
-```json
-{
-  "result": "The main themes are...",
-  "stats": {
-    "llm_calls": 3,
-    "iterations": 2,
-    "depth": 0
-  }
-}
-```
-
-### Example
-
-```bash
-# Basic usage
-echo '{
-  "model": "gpt-4o-mini",
-  "query": "Summarize this",
-  "context": "Long document...",
-  "config": {
-    "api_key": "sk-..."
-  }
-}' | ./rlm
-
-# With environment variable for API key
-export OPENAI_API_KEY="sk-..."
-echo '{
-  "model": "gpt-4o-mini",
-  "query": "What is this about?",
-  "context": "Document text..."
-}' | ./rlm
-```
-
-## Configuration Options
-
-All fields in `config` are optional and have defaults:
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `recursive_model` | string | Same as `model` | Cheaper model for recursive calls |
-| `api_base` | string | `https://api.openai.com/v1` | API endpoint URL |
-| `api_key` | string | From `OPENAI_API_KEY` env | API key for authentication |
-| `max_depth` | int | 5 | Maximum recursion depth |
-| `max_iterations` | int | 30 | Maximum REPL iterations per call |
-| `temperature` | float | 0.7 | LLM temperature (0-2) |
-| `timeout` | int | 60 | HTTP timeout in seconds |
-| `context_overflow.enabled` | bool | true | Enable context overflow recovery |
-| `context_overflow.strategy` | string | `mapreduce` | Reduction strategy: mapreduce, truncate, chunked, tfidf, textrank, refine |
-| `context_overflow.max_model_tokens` | int | 0 (auto) | Override detected model token limit |
-| `context_overflow.safety_margin` | float | 0.15 | Fraction reserved for prompt overhead |
-| `context_overflow.max_reduction_attempts` | int | 3 | Max retry attempts |
-
-Any other fields in `config` are passed as extra parameters to the LLM API.
-
-## JavaScript REPL Environment
-
-The LLM can write JavaScript code to explore the context. Available globals:
-
-### Core Variables
-- `context` - The document to analyze (string)
-- `query` - The user's question (string)
-- `recursive_llm(sub_query, sub_context)` - Recursively process sub-context
-
-### String Operations
-```javascript
-context.slice(0, 100)           // First 100 chars
-context.split('\n')             // Split by newline
-context.length                  // String length
-```
-
-### Regex (Python-style API)
-```javascript
-re.findall("ERROR", context)    // Find all matches
-re.search("ERROR", context)     // Find first match
-```
-
-### Built-in Functions
-```javascript
-len(context)                    // Length of string/array
-print("hello")                  // Print output
-console.log("hello")            // Same as print
-```
-
-### JSON
-```javascript
-json.loads('{"key":"value"}')   // Parse JSON
-json.dumps({key: "value"})      // Stringify JSON
-```
-
-### Array Operations
-```javascript
-range(5)                        // [0, 1, 2, 3, 4]
-range(2, 5)                     // [2, 3, 4]
-sorted([3, 1, 2])               // [1, 2, 3]
-sum([1, 2, 3])                  // 6
-min([1, 2, 3])                  // 1
-max([1, 2, 3])                  // 3
-enumerate(['a', 'b'])           // [[0,'a'], [1,'b']]
-zip([1, 2], ['a', 'b'])         // [[1,'a'], [2,'b']]
-any([false, true])              // true
-all([true, true])               // true
-```
-
-### Counting & Grouping
-```javascript
-Counter("hello")                // {h:1, e:1, l:2, o:1}
-defaultdict(() => 0)            // Dict with default values
-```
-
-### Math
-```javascript
-Math.floor(3.7)                 // 3
-Math.ceil(3.2)                  // 4
-Math.max(1, 2, 3)               // 3
-```
-
-### Returning Results
-```javascript
-// Option 1: Direct answer (write as text, not code)
-FINAL("The answer is 42")
-
-// Option 2: Return a variable
-const answer = "The answer is 42"
-FINAL_VAR(answer)
-```
-
-## Supported LLM Providers
-
-Works with any OpenAI-compatible API:
-
-- **OpenAI**: `model: "gpt-4o"`, `model: "gpt-4o-mini"`
-- **Azure OpenAI**: Set custom `api_base`
-- **Ollama**: `api_base: "http://localhost:11434/v1"`, `model: "llama3.2"`
-- **llama.cpp**: `api_base: "http://localhost:8000/v1"`
-- **vLLM**: `api_base: "http://localhost:8000/v1"`
-- Any other OpenAI-compatible endpoint
-
-## Architecture
-
-```
-cmd/rlm/main.go              # CLI entry point (JSON I/O)
-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
-├── errors.go                # Error types
-├── context_overflow.go      # Context overflow detection + 6 reduction strategies
-├── tfidf.go                 # TF-IDF extractive compression (pure Go)
-└── textrank.go              # TextRank graph-based ranking with PageRank
-```
-
-## Error Handling
-
-Errors are written to stderr with exit code 1:
-
-```bash
-# Missing model
-echo '{"query":"test"}' | ./rlm
-# stderr: Missing model in request payload
-
-# API error
-echo '{
-  "model": "invalid",
-  "query": "test",
-  "context": "test"
-}' | ./rlm 2>&1
-# stderr: LLM request failed (401): ...
-```
-
-## Testing
-
-```bash
-# Run all tests
-go test ./rlm/... -v
-
-# Run specific test
-go test ./rlm -run TestParser -v
-
-# With coverage
-go test ./rlm/... -cover
-
-# Benchmark
-go test ./rlm/... -bench=. -benchmem
-```
-
-## Performance
-
-- **Binary size**: ~15MB (uncompressed), ~5MB (compressed with UPX)
-- **Memory**: ~50MB baseline + context size
-- **Startup**: <10ms
-- **REPL overhead**: ~1-2ms per iteration
-
-## Comparison with Python Implementation
-
-| Feature | Python | Go |
-|---------|--------|-----|
-| **REPL Language** | Python (RestrictedPython) | JavaScript (goja) |
-| **LLM Providers** | 100+ via LiteLLM | OpenAI-compatible only |
-| **Async Support** | ✅ Full async/await | ❌ Synchronous only |
-| **Distribution** | Requires Python runtime | ✅ Single binary |
-| **Startup Time** | ~500ms | ~10ms |
-| **Memory Usage** | ~150MB | ~50MB |
-
-## Known Limitations
-
-1. **JavaScript vs Python**: LLMs are more familiar with Python, may need more iterations
-2. **No async**: Recursive calls are sequential, not parallel
-3. **OpenAI API only**: Doesn't support all LiteLLM providers
-4. **No streaming**: Full response only
-
-## Integration with TypeScript
-
-From Node.js/TypeScript:
-
-```typescript
-import { spawn } from 'child_process';
-
-interface RLMRequest {
-  model: string;
-  query: string;
-  context: string;
-  config?: {
-    api_key?: string;
-    max_depth?: number;
-    max_iterations?: number;
-  };
-}
-
-interface RLMResponse {
-  result: string;
-  stats: {
-    llm_calls: number;
-    iterations: number;
-    depth: number;
-  };
-}
-
-async function callRLM(request: RLMRequest): Promise<RLMResponse> {
-  return new Promise((resolve, reject) => {
-    const proc = spawn('./rlm');
-    let stdout = '';
-    let stderr = '';
-
-    proc.stdout.on('data', (data) => { stdout += data; });
-    proc.stderr.on('data', (data) => { stderr += data; });
-
-    proc.on('close', (code) => {
-      if (code !== 0) {
-        reject(new Error(stderr || `Exit code ${code}`));
-      } else {
-        resolve(JSON.parse(stdout));
-      }
-    });
-
-    proc.stdin.write(JSON.stringify(request));
-    proc.stdin.end();
-  });
-}
-
-// Usage
-const result = await callRLM({
-  model: 'gpt-4o-mini',
-  query: 'What is this about?',
-  context: longDocument,
-  config: {
-    api_key: process.env.OPENAI_API_KEY,
-  },
-});
-
-console.log(result.result);
-console.log(`Stats: ${result.stats.llm_calls} LLM calls`);
-```
-
-## Troubleshooting
-
-### "Missing model in request payload"
-Include the `model` field in your JSON input.
-
-### "LLM request failed (401)"
-Check your API key is correct and has sufficient credits.
-
-### "max iterations exceeded"
-Increase `max_iterations` in config, or simplify your query.
-
-### "max recursion depth exceeded"
-Increase `max_depth` in config.
-
-### "Execution error: ReferenceError: xyz is not defined"
-Check the JavaScript syntax. Use `console.log()` not `print()`, or ensure `print()` is available.
-
-## Contributing
-
-1. Write tests for new features
-2. Ensure all tests pass: `go test ./rlm/... -v`
-3. Format code: `go fmt ./...`
-4. Update documentation
-
-## License
-
-MIT License - Same as the original Python implementation
-
-## Acknowledgments
-
-- Based on [Recursive Language Models paper](https://alexzhang13.github.io/blog/2025/rlm/) by Alex Zhang and Omar Khattab (MIT)
-- Original Python implementation: https://github.com/alexzhang13/rlm
-- JavaScript engine: [goja](https://github.com/dop251/goja)

package/go/integration_test.sh

@@ -1,169 +0,0 @@
-#!/bin/bash
-# Integration test with real LLM API
-# Set OPENAI_API_KEY environment variable before running
-
-set -e
-
-echo "🧪 RLM Go Integration Tests"
-echo "================================"
-echo ""
-
-# Check if binary exists
-if [ ! -f "./rlm" ]; then
-    echo "❌ Binary not found. Building..."
-    go build -o rlm ./cmd/rlm
-    echo "✅ Built binary"
-fi
-
-# Check for API key
-if [ -z "$OPENAI_API_KEY" ]; then
-    echo "❌ OPENAI_API_KEY environment variable not set"
-    echo ""
-    echo "Usage:"
-    echo "  export OPENAI_API_KEY='sk-...'"
-    echo "  ./integration_test.sh"
-    exit 1
-fi
-
-echo "✅ API key found"
-echo ""
-
-# Test 1: Simple query
-echo "📝 Test 1: Simple context analysis"
-echo "-----------------------------------"
-RESULT=$(cat <<EOF | ./rlm
-{
-  "model": "gpt-4o-mini",
-  "query": "How many times does the word 'test' appear?",
-  "context": "This is a test. Another test here. Final test.",
-  "config": {
-    "api_key": "$OPENAI_API_KEY",
-    "max_iterations": 10
-  }
-}
-EOF
-)
-
-if [ $? -eq 0 ]; then
-    echo "✅ Test 1 passed"
-    echo "Result: $(echo $RESULT | jq -r '.result')"
-    echo "Stats: $(echo $RESULT | jq '.stats')"
-else
-    echo "❌ Test 1 failed"
-    exit 1
-fi
-echo ""
-
-# Test 2: Count/aggregation
-echo "📝 Test 2: Counting errors in logs"
-echo "-----------------------------------"
-LOG_CONTEXT='2024-01-01 INFO: System started
-2024-01-01 ERROR: Connection failed
-2024-01-01 INFO: Retrying
-2024-01-01 ERROR: Timeout
-2024-01-01 ERROR: Failed again
-2024-01-01 INFO: Success'
-
-RESULT=$(./rlm <<EOF
-{
-  "model": "gpt-4o-mini",
-  "query": "Count how many ERROR entries are in the logs",
-  "context": "$LOG_CONTEXT",
-  "config": {
-    "api_key": "$OPENAI_API_KEY",
-    "max_iterations": 10
-  }
-}
-EOF
-)
-
-if [ $? -eq 0 ]; then
-    echo "✅ Test 2 passed"
-    echo "Result: $(echo $RESULT | jq -r '.result')"
-    ITERATIONS=$(echo $RESULT | jq '.stats.iterations')
-    echo "Iterations: $ITERATIONS"
-else
-    echo "❌ Test 2 failed"
-    exit 1
-fi
-echo ""
-
-# Test 3: Long context
-echo "📝 Test 3: Long context processing"
-echo "-----------------------------------"
-LONG_CONTEXT=$(cat <<EOF
-Chapter 1: The Beginning
-
-It was a dark and stormy night. The hero embarked on a journey.
-$(for i in {1..100}; do echo "Line $i of the story continues here with more content."; done)
-
-Chapter 2: The Middle
-
-The hero faced many challenges.
-$(for i in {1..100}; do echo "Line $i describes the adventure."; done)
-
-Chapter 3: The End
-
-Finally, the hero succeeded and returned home triumphant.
-EOF
-)
-
-RESULT=$(cat <<EOF | ./rlm
-{
-  "model": "gpt-4o-mini",
-  "query": "How many chapters are in this document?",
-  "context": "$LONG_CONTEXT",
-  "config": {
-    "api_key": "$OPENAI_API_KEY",
-    "max_iterations": 15
-  }
-}
-EOF
-)
-
-if [ $? -eq 0 ]; then
-    echo "✅ Test 3 passed"
-    echo "Result: $(echo $RESULT | jq -r '.result')"
-    LLM_CALLS=$(echo $RESULT | jq '.stats.llm_calls')
-    echo "LLM calls: $LLM_CALLS"
-else
-    echo "❌ Test 3 failed"
-    exit 1
-fi
-echo ""
-
-# Test 4: Different model configurations
-echo "📝 Test 4: Two-model configuration"
-echo "-----------------------------------"
-RESULT=$(cat <<EOF | ./rlm
-{
-  "model": "gpt-4o",
-  "query": "What is this text about?",
-  "context": "Artificial intelligence and machine learning are transforming technology.",
-  "config": {
-    "recursive_model": "gpt-4o-mini",
-    "api_key": "$OPENAI_API_KEY",
-    "max_iterations": 10,
-    "temperature": 0.3
-  }
-}
-EOF
-)
-
-if [ $? -eq 0 ]; then
-    echo "✅ Test 4 passed"
-    echo "Result: $(echo $RESULT | jq -r '.result')"
-else
-    echo "❌ Test 4 failed"
-    exit 1
-fi
-echo ""
-
-echo "================================"
-echo "✅ All integration tests passed!"
-echo ""
-echo "Summary:"
-echo "  - Simple queries work"
-echo "  - Counting/aggregation works"
-echo "  - Long context works"
-echo "  - Model configuration works"