recursive-llm-ts 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 recursive-llm-ts contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+# recursive-llm-ts
+
+TypeScript bridge for [recursive-llm](https://github.com/grigori-gvadzabia/recursive-llm): Recursive Language Models for unbounded context processing.
+
+## Installation
+
+```bash
+npm install recursive-llm-ts
+```
+
+**That's it!** Python is bundled via [JSPyBridge](https://github.com/extremeheat/JSPyBridge) - no additional setup required.
+
+## Usage
+
+```typescript
+import { RLM } from 'recursive-llm-ts';
+
+// Initialize RLM with a model
+const rlm = new RLM('gpt-4o-mini', {
+  max_iterations: 15,
+  api_key: process.env.OPENAI_API_KEY
+});
+
+// Process a query with unbounded context
+const result = await rlm.completion(
+  'What are the key points in this document?',
+  longDocument
+);
+
+console.log(result.result);
+console.log('Stats:', result.stats);
+```
+
+
+## API
+
+### `RLM`
+
+Main class for recursive language model completions.
+
+**Constructor:**
+```typescript
+constructor(model: string, rlmConfig?: RLMConfig)
+```
+
+- `model`: The LLM model to use (e.g., 'gpt-4o-mini', 'claude-3-sonnet')
+- `rlmConfig`: Optional configuration object
+
+**Methods:**
+
+#### `completion(query: string, context: string): Promise<RLMResult>`
+
+Process a query with the given context using recursive language models.
+
+**Parameters:**
+- `query`: The question or task to perform
+- `context`: The context/document to process (can be arbitrarily large)
+
+**Returns:**
+- `Promise<RLMResult>`: Result containing the answer and statistics
+
+#### `cleanup(): Promise<void>`
+
+Clean up the Python bridge and free resources.
+
+```typescript
+await rlm.cleanup();
+```
+
+### Types
+
+```typescript
+interface RLMConfig {
+  // Model configuration
+  recursive_model?: string;      // Model to use for recursive calls (defaults to main model)
+  
+  // API configuration
+  api_base?: string;             // Custom API base URL (for Azure, Bedrock, etc.)
+  api_key?: string;              // API key for authentication
+  
+  // Execution limits
+  max_depth?: number;            // Maximum recursion depth (default: 5)
+  max_iterations?: number;       // Maximum REPL iterations per call (default: 30)
+  
+  // LiteLLM parameters - pass any additional parameters supported by LiteLLM
+  api_version?: string;          // API version (e.g., for Azure)
+  timeout?: number;              // Request timeout in seconds
+  temperature?: number;          // Sampling temperature
+  max_tokens?: number;           // Maximum tokens in response
+  [key: string]: any;            // Any other LiteLLM parameters
+}
+
+interface RLMResult {
+  result: string;
+  stats: RLMStats;
+}
+
+interface RLMStats {
+  llm_calls: number;
+  iterations: number;
+  depth: number;
+}
+```
+
+## Environment Variables
+
+Set your API key as an environment variable:
+
+```bash
+export OPENAI_API_KEY='your-api-key-here'
+```
+
+Or pass it in the configuration:
+
+```typescript
+const rlm = new RLM('gpt-4o-mini', {
+  api_key: 'your-api-key-here'
+});
+```
+
+## Custom Providers
+
+This package uses [LiteLLM](https://github.com/BerriAI/litellm) under the hood, which supports **100+ LLM providers** including OpenAI, Anthropic, AWS Bedrock, Azure, Cohere, and more.
+
+### Quick Reference
+
+| Provider | Model Format | Required Config |
+|----------|-------------|----------------|
+| OpenAI | `gpt-4o`, `gpt-4o-mini` | `api_key` |
+| Anthropic | `claude-3-5-sonnet-20241022` | `api_key` |
+| AWS Bedrock | `bedrock/anthropic.claude-3-sonnet...` | AWS env vars |
+| Azure OpenAI | `azure/gpt-4o` | `api_base`, `api_key`, `api_version` |
+| Ollama | `ollama/llama3.2` | `api_base` (optional) |
+| Custom | `openai/your-model` | `api_base`, `api_key` |
+
+### Amazon Bedrock
+
+```typescript
+import { RLM } from 'recursive-llm-ts';
+
+const rlm = new RLM('bedrock/anthropic.claude-3-sonnet-20240229-v1:0', {
+  api_key: process.env.AWS_ACCESS_KEY_ID,
+  max_iterations: 15
+});
+
+// Set AWS credentials via environment variables:
+// AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION_NAME
+```
+
+### Azure OpenAI
+
+```typescript
+const rlm = new RLM('azure/gpt-4o', {
+  api_base: 'https://your-resource.openai.azure.com',
+  api_key: process.env.AZURE_API_KEY,
+  api_version: '2024-02-15-preview' // Pass any LiteLLM params
+});
+```
+
+### Custom OpenAI-Compatible APIs
+
+For providers with OpenAI-compatible APIs (e.g., local models, vLLM, Ollama):
+
+```typescript
+const rlm = new RLM('openai/your-model', {
+  api_base: 'https://your-custom-endpoint.com/v1',
+  api_key: 'your-key-here'
+});
+```
+
+### Other Providers
+
+See the [LiteLLM documentation](https://docs.litellm.ai/docs/providers) for the complete list of supported providers and their configuration.
+
+## How It Works
+
+This package provides a TypeScript wrapper around the Python `recursive-llm` package, enabling seamless integration into Node.js/TypeScript applications. It uses [JSPyBridge (pythonia)](https://github.com/extremeheat/JSPyBridge) to provide direct Python interop - Python is bundled and runs in-process, so no external Python installation is needed.
+
+The recursive-llm approach breaks down large contexts into manageable chunks and processes them recursively, allowing you to work with documents of any size without hitting token limits.
+
+### Key Features
+
+- ✅ **Zero Python setup** - Python runtime bundled via JSPyBridge
+- ✅ **Direct interop** - Native Python-JavaScript bridge (no JSON serialization)
+- ✅ **Type-safe** - Full TypeScript type definitions
+- ✅ **Simple API** - Just `npm install` and start using
+
+## Publishing
+
+This package uses automated GitHub Actions workflows to publish to npm. See [RELEASE.md](RELEASE.md) for detailed instructions on publishing new versions.
+
+**Quick start:**
+```bash
+npm version patch  # Bump version
+git push origin main --tags  # Push tag
+# Then create a GitHub release to trigger automatic npm publish
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { RLM } from './rlm';
+export { RLMBridge, RLMConfig, RLMResult, RLMStats, RLMError } from './rlm-bridge';

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RLMBridge = exports.RLM = void 0;
+var rlm_1 = require("./rlm");
+Object.defineProperty(exports, "RLM", { enumerable: true, get: function () { return rlm_1.RLM; } });
+var rlm_bridge_1 = require("./rlm-bridge");
+Object.defineProperty(exports, "RLMBridge", { enumerable: true, get: function () { return rlm_bridge_1.RLMBridge; } });

package/dist/rlm-bridge.d.ts

@@ -0,0 +1,26 @@
+export interface RLMStats {
+    llm_calls: number;
+    iterations: number;
+    depth: number;
+}
+export interface RLMResult {
+    result: string;
+    stats: RLMStats;
+}
+export interface RLMError {
+    error: string;
+}
+export interface RLMConfig {
+    recursive_model?: string;
+    api_base?: string;
+    api_key?: string;
+    max_depth?: number;
+    max_iterations?: number;
+    [key: string]: any;
+}
+export declare class RLMBridge {
+    private rlmModule;
+    private ensureRLMModule;
+    completion(model: string, query: string, context: string, rlmConfig?: RLMConfig): Promise<RLMResult>;
+    cleanup(): Promise<void>;
+}

package/dist/rlm-bridge.js

@@ -0,0 +1,101 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RLMBridge = void 0;
+const pythonia_1 = require("pythonia");
+const path = __importStar(require("path"));
+class RLMBridge {
+    constructor() {
+        this.rlmModule = null;
+    }
+    ensureRLMModule() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.rlmModule)
+                return;
+            // Get path to recursive-llm Python module
+            const rlmPath = path.join(__dirname, '..', 'recursive-llm', 'src', 'rlm');
+            // Import sys module to add path
+            const sys = yield (0, pythonia_1.python)('sys');
+            const pathList = yield sys.path;
+            yield pathList.insert(0, path.join(__dirname, '..', 'recursive-llm', 'src'));
+            // Import the rlm module
+            this.rlmModule = yield (0, pythonia_1.python)('rlm');
+        });
+    }
+    completion(model_1, query_1, context_1) {
+        return __awaiter(this, arguments, void 0, function* (model, query, context, rlmConfig = {}) {
+            yield this.ensureRLMModule();
+            try {
+                // Create RLM instance with config
+                const RLMClass = yield this.rlmModule.RLM;
+                const rlmInstance = yield RLMClass(model, rlmConfig);
+                // Call completion method
+                const result = yield rlmInstance.completion(query, context);
+                const stats = yield rlmInstance.stats;
+                // Convert Python stats dict to JS object
+                const statsObj = {
+                    llm_calls: yield stats.llm_calls,
+                    iterations: yield stats.iterations,
+                    depth: yield stats.depth
+                };
+                return {
+                    result: String(result),
+                    stats: statsObj
+                };
+            }
+            catch (error) {
+                throw new Error(`RLM completion failed: ${error.message || error}`);
+            }
+        });
+    }
+    cleanup() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.rlmModule) {
+                pythonia_1.python.exit();
+                this.rlmModule = null;
+            }
+        });
+    }
+}
+exports.RLMBridge = RLMBridge;

package/dist/rlm.d.ts

@@ -0,0 +1,9 @@
+import { RLMConfig, RLMResult } from './rlm-bridge';
+export declare class RLM {
+    private bridge;
+    private model;
+    private rlmConfig;
+    constructor(model: string, rlmConfig?: RLMConfig);
+    completion(query: string, context: string): Promise<RLMResult>;
+    cleanup(): Promise<void>;
+}

package/dist/rlm.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RLM = void 0;
+const rlm_bridge_1 = require("./rlm-bridge");
+class RLM {
+    constructor(model, rlmConfig = {}) {
+        this.bridge = new rlm_bridge_1.RLMBridge();
+        this.model = model;
+        this.rlmConfig = rlmConfig;
+    }
+    completion(query, context) {
+        return this.bridge.completion(this.model, query, context, this.rlmConfig);
+    }
+    cleanup() {
+        return this.bridge.cleanup();
+    }
+}
+exports.RLM = RLM;

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "recursive-llm-ts",
+  "version": "1.0.1",
+  "description": "TypeScript bridge for recursive-llm: Recursive Language Models for unbounded context processing",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "recursive-llm/src",
+    "recursive-llm/pyproject.toml"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "release": "./scripts/release.sh",
+    "start": "ts-node test/test.ts",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "llm",
+    "ai",
+    "recursive",
+    "context",
+    "nlp",
+    "language-model"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourusername/recursive-llm-ts.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yourusername/recursive-llm-ts/issues"
+  },
+  "homepage": "https://github.com/yourusername/recursive-llm-ts#readme",
+  "dependencies": {
+    "pythonia": "^1.2.6"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.19",
+    "dotenv": "^16.4.5",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3"
+  }
+}

package/recursive-llm/pyproject.toml

@@ -0,0 +1,70 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "recursive-llm"
+version = "0.1.0"
+description = "Recursive Language Models for unbounded context processing"
+authors = [{name = "Grigori Gvadzabia"}]
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+keywords = ["llm", "ai", "nlp", "recursive", "language-models"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+dependencies = [
+    "litellm>=1.0.0",
+    "RestrictedPython>=6.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-cov>=4.0.0",
+    "black>=24.0.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/yourusername/recursive-llm"
+Documentation = "https://github.com/yourusername/recursive-llm"
+Repository = "https://github.com/yourusername/recursive-llm"
+Issues = "https://github.com/yourusername/recursive-llm/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "-v"
+
+[tool.black]
+line-length = 100
+target-version = ['py39']
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.mypy]
+python_version = "3.9"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true

package/recursive-llm/src/rlm/__init__.py

@@ -0,0 +1,14 @@
+"""Recursive Language Models for unbounded context processing."""
+
+from .core import RLM, RLMError, MaxIterationsError, MaxDepthError
+from .repl import REPLError
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "RLM",
+    "RLMError",
+    "MaxIterationsError",
+    "MaxDepthError",
+    "REPLError",
+]

package/recursive-llm/src/rlm/core.py

@@ -0,0 +1,305 @@
+"""Core RLM implementation."""
+
+import asyncio
+import re
+from typing import Optional, Dict, Any, List
+
+import litellm
+
+from .types import Message
+from .repl import REPLExecutor, REPLError
+from .prompts import build_system_prompt
+from .parser import parse_response, is_final
+
+
+class RLMError(Exception):
+    """Base error for RLM."""
+    pass
+
+
+class MaxIterationsError(RLMError):
+    """Max iterations exceeded."""
+    pass
+
+
+class MaxDepthError(RLMError):
+    """Max recursion depth exceeded."""
+    pass
+
+
+class RLM:
+    """Recursive Language Model."""
+
+    def __init__(
+        self,
+        model: str,
+        recursive_model: Optional[str] = None,
+        api_base: Optional[str] = None,
+        api_key: Optional[str] = None,
+        max_depth: int = 5,
+        max_iterations: int = 30,
+        _current_depth: int = 0,
+        **llm_kwargs: Any
+    ):
+        """
+        Initialize RLM.
+
+        Args:
+            model: Model name (e.g., "gpt-4o", "claude-sonnet-4", "ollama/llama3.2")
+            recursive_model: Optional cheaper model for recursive calls
+            api_base: Optional API base URL
+            api_key: Optional API key
+            max_depth: Maximum recursion depth
+            max_iterations: Maximum REPL iterations per call
+            _current_depth: Internal current depth tracker
+            **llm_kwargs: Additional LiteLLM parameters
+        """
+        self.model = model
+        self.recursive_model = recursive_model or model
+        self.api_base = api_base
+        self.api_key = api_key
+        self.max_depth = max_depth
+        self.max_iterations = max_iterations
+        self._current_depth = _current_depth
+        self.llm_kwargs = llm_kwargs
+
+        self.repl = REPLExecutor()
+
+        # Stats
+        self._llm_calls = 0
+        self._iterations = 0
+
+    def completion(
+        self,
+        query: str = "",
+        context: str = "",
+        **kwargs: Any
+    ) -> str:
+        """
+        Sync wrapper for acompletion.
+
+        Args:
+            query: User query (optional if query is in context)
+            context: Context to process (optional, can pass query here)
+            **kwargs: Additional LiteLLM parameters
+
+        Returns:
+            Final answer string
+
+        Examples:
+            # Standard usage
+            rlm.completion(query="Summarize this", context=document)
+
+            # Query in context (RLM will extract task)
+            rlm.completion(context="Summarize this document: ...")
+
+            # Single string (treat as context)
+            rlm.completion("Process this text and extract dates")
+        """
+        # If only one argument provided, treat it as context
+        if query and not context:
+            context = query
+            query = ""
+
+        return asyncio.run(self.acompletion(query, context, **kwargs))
+
+    async def acompletion(
+        self,
+        query: str = "",
+        context: str = "",
+        **kwargs: Any
+    ) -> str:
+        """
+        Main async completion method.
+
+        Args:
+            query: User query (optional if query is in context)
+            context: Context to process (optional, can pass query here)
+            **kwargs: Additional LiteLLM parameters
+
+        Returns:
+            Final answer string
+
+        Raises:
+            MaxIterationsError: If max iterations exceeded
+            MaxDepthError: If max recursion depth exceeded
+
+        Examples:
+            # Explicit query and context
+            await rlm.acompletion(query="What is this?", context=doc)
+
+            # Query embedded in context
+            await rlm.acompletion(context="Extract all dates from: ...")
+
+            # LLM will figure out the task
+            await rlm.acompletion(context=document_with_instructions)
+        """
+        # If only query provided, treat it as context
+        if query and not context:
+            context = query
+            query = ""
+        if self._current_depth >= self.max_depth:
+            raise MaxDepthError(f"Max recursion depth ({self.max_depth}) exceeded")
+
+        # Initialize REPL environment
+        repl_env = self._build_repl_env(query, context)
+
+        # Build initial messages
+        system_prompt = build_system_prompt(len(context), self._current_depth)
+        messages: List[Message] = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": query}
+        ]
+
+        # Main loop
+        for iteration in range(self.max_iterations):
+            self._iterations = iteration + 1
+
+            # Call LLM
+            response = await self._call_llm(messages, **kwargs)
+
+            # Check for FINAL
+            if is_final(response):
+                answer = parse_response(response, repl_env)
+                if answer is not None:
+                    return answer
+
+            # Execute code in REPL
+            try:
+                exec_result = self.repl.execute(response, repl_env)
+            except REPLError as e:
+                exec_result = f"Error: {str(e)}"
+            except Exception as e:
+                exec_result = f"Unexpected error: {str(e)}"
+
+            # Add to conversation
+            messages.append({"role": "assistant", "content": response})
+            messages.append({"role": "user", "content": exec_result})
+
+        raise MaxIterationsError(
+            f"Max iterations ({self.max_iterations}) exceeded without FINAL()"
+        )
+
+    async def _call_llm(
+        self,
+        messages: List[Message],
+        **kwargs: Any
+    ) -> str:
+        """
+        Call LLM API.
+
+        Args:
+            messages: Conversation messages
+            **kwargs: Additional parameters (can override model here)
+
+        Returns:
+            LLM response text
+        """
+        self._llm_calls += 1
+
+        # Choose model based on depth
+        default_model = self.model if self._current_depth == 0 else self.recursive_model
+
+        # Allow override via kwargs
+        model = kwargs.pop('model', default_model)
+
+        # Merge kwargs
+        call_kwargs = {**self.llm_kwargs, **kwargs}
+        if self.api_base:
+            call_kwargs['api_base'] = self.api_base
+        if self.api_key:
+            call_kwargs['api_key'] = self.api_key
+
+        # Call LiteLLM
+        response = await litellm.acompletion(
+            model=model,
+            messages=messages,
+            **call_kwargs
+        )
+
+        # Extract text
+        return response.choices[0].message.content
+
+    def _build_repl_env(self, query: str, context: str) -> Dict[str, Any]:
+        """
+        Build REPL environment.
+
+        Args:
+            query: User query
+            context: Context string
+
+        Returns:
+            Environment dict
+        """
+        env: Dict[str, Any] = {
+            'context': context,
+            'query': query,
+            'recursive_llm': self._make_recursive_fn(),
+            're': re,  # Whitelist re module
+        }
+        return env
+
+    def _make_recursive_fn(self) -> Any:
+        """
+        Create recursive LLM function for REPL.
+
+        Returns:
+            Async function that can be called from REPL
+        """
+        async def recursive_llm(sub_query: str, sub_context: str) -> str:
+            """
+            Recursively process sub-context.
+
+            Args:
+                sub_query: Query for sub-context
+                sub_context: Sub-context to process
+
+            Returns:
+                Answer from recursive call
+            """
+            if self._current_depth + 1 >= self.max_depth:
+                return f"Max recursion depth ({self.max_depth}) reached"
+
+            # Create sub-RLM with increased depth
+            sub_rlm = RLM(
+                model=self.recursive_model,
+                recursive_model=self.recursive_model,
+                api_base=self.api_base,
+                api_key=self.api_key,
+                max_depth=self.max_depth,
+                max_iterations=self.max_iterations,
+                _current_depth=self._current_depth + 1,
+                **self.llm_kwargs
+            )
+
+            return await sub_rlm.acompletion(sub_query, sub_context)
+
+        # Wrap in sync function for REPL compatibility
+        def sync_recursive_llm(sub_query: str, sub_context: str) -> str:
+            """Sync wrapper for recursive_llm."""
+            # Check if we're in an async context
+            try:
+                loop = asyncio.get_running_loop()
+                # We're in async context, but REPL is sync
+                # Create a new thread to run async code
+                import concurrent.futures
+                with concurrent.futures.ThreadPoolExecutor() as executor:
+                    future = executor.submit(
+                        asyncio.run,
+                        recursive_llm(sub_query, sub_context)
+                    )
+                    return future.result()
+            except RuntimeError:
+                # No running loop, safe to use asyncio.run
+                return asyncio.run(recursive_llm(sub_query, sub_context))
+
+        return sync_recursive_llm
+
+    @property
+    def stats(self) -> Dict[str, int]:
+        """Get execution statistics."""
+        return {
+            'llm_calls': self._llm_calls,
+            'iterations': self._iterations,
+            'depth': self._current_depth,
+        }

package/recursive-llm/src/rlm/parser.py

@@ -0,0 +1,93 @@
+"""Parse FINAL() and FINAL_VAR() statements from LLM responses."""
+
+import re
+from typing import Optional, Dict, Any
+
+
+def extract_final(response: str) -> Optional[str]:
+    """
+    Extract answer from FINAL() statement.
+
+    Args:
+        response: LLM response text
+
+    Returns:
+        Extracted answer or None if not found
+    """
+    # Look for FINAL("answer") or FINAL('answer')
+    patterns = [
+        r'FINAL\s*\(\s*"""(.*)"""',  # FINAL("""answer""") - triple double quotes
+        r"FINAL\s*\(\s*'''(.*)'''",  # FINAL('''answer''') - triple single quotes
+        r'FINAL\s*\(\s*"([^"]*)"',  # FINAL("answer") - double quotes
+        r"FINAL\s*\(\s*'([^']*)'",  # FINAL('answer') - single quotes
+    ]
+
+    for pattern in patterns:
+        match = re.search(pattern, response, re.DOTALL)
+        if match:
+            return match.group(1).strip()
+
+    return None
+
+
+def extract_final_var(response: str, env: Dict[str, Any]) -> Optional[str]:
+    """
+    Extract answer from FINAL_VAR() statement.
+
+    Args:
+        response: LLM response text
+        env: REPL environment with variables
+
+    Returns:
+        Variable value as string or None if not found
+    """
+    # Look for FINAL_VAR(var_name)
+    match = re.search(r'FINAL_VAR\s*\(\s*(\w+)\s*\)', response)
+    if not match:
+        return None
+
+    var_name = match.group(1)
+
+    # Get variable from environment
+    if var_name in env:
+        value = env[var_name]
+        return str(value)
+
+    return None
+
+
+def is_final(response: str) -> bool:
+    """
+    Check if response contains FINAL() or FINAL_VAR().
+
+    Args:
+        response: LLM response text
+
+    Returns:
+        True if response contains final statement
+    """
+    return 'FINAL(' in response or 'FINAL_VAR(' in response
+
+
+def parse_response(response: str, env: Dict[str, Any]) -> Optional[str]:
+    """
+    Parse response for any final statement.
+
+    Args:
+        response: LLM response text
+        env: REPL environment
+
+    Returns:
+        Final answer or None
+    """
+    # Try FINAL() first
+    answer = extract_final(response)
+    if answer is not None:
+        return answer
+
+    # Try FINAL_VAR()
+    answer = extract_final_var(response, env)
+    if answer is not None:
+        return answer
+
+    return None

package/recursive-llm/src/rlm/prompts.py

@@ -0,0 +1,50 @@
+"""System prompt templates for RLM."""
+
+
+def build_system_prompt(context_size: int, depth: int = 0) -> str:
+    """
+    Build system prompt for RLM.
+
+    Args:
+        context_size: Size of context in characters
+        depth: Current recursion depth
+
+    Returns:
+        System prompt string
+    """
+    # Minimal prompt (paper-style)
+    prompt = f"""You are a Recursive Language Model. You interact with context through a Python REPL environment.
+
+The context is stored in variable `context` (not in this prompt). Size: {context_size:,} characters.
+
+Available in environment:
+- context: str (the document to analyze)
+- query: str (the question: "{"{"}query{"}"}")
+- recursive_llm(sub_query, sub_context) -> str (recursively process sub-context)
+- re: already imported regex module (use re.findall, re.search, etc.)
+
+Write Python code to answer the query. The last expression or print() output will be shown to you.
+
+Examples:
+- print(context[:100])  # See first 100 chars
+- errors = re.findall(r'ERROR', context)  # Find all ERROR
+- count = len(errors); print(count)  # Count and show
+
+When you have the answer, use FINAL("answer") - this is NOT a function, just write it as text.
+
+Depth: {depth}"""
+
+    return prompt
+
+
+def build_user_prompt(query: str) -> str:
+    """
+    Build user prompt.
+
+    Args:
+        query: User's question
+
+    Returns:
+        User prompt string
+    """
+    return query

package/recursive-llm/src/rlm/repl.py

@@ -0,0 +1,235 @@
+"""Safe REPL executor using RestrictedPython."""
+
+import io
+import sys
+from typing import Dict, Any, Optional
+from RestrictedPython import compile_restricted_exec, safe_globals, limited_builtins, utility_builtins
+from RestrictedPython.Guards import guarded_iter_unpack_sequence, safer_getattr
+from RestrictedPython.PrintCollector import PrintCollector
+
+
+class REPLError(Exception):
+    """Error during REPL execution."""
+    pass
+
+
+class REPLExecutor:
+    """Safe Python code executor."""
+
+    def __init__(self, timeout: int = 5, max_output_chars: int = 2000):
+        """
+        Initialize REPL executor.
+
+        Args:
+            timeout: Execution timeout in seconds (not currently enforced)
+            max_output_chars: Maximum characters to return (truncate if longer)
+        """
+        self.timeout = timeout
+        self.max_output_chars = max_output_chars
+
+    def execute(self, code: str, env: Dict[str, Any]) -> str:
+        """
+        Execute Python code in restricted environment.
+
+        Args:
+            code: Python code to execute
+            env: Environment with context, query, recursive_llm, etc.
+
+        Returns:
+            String result of execution (stdout or last expression)
+
+        Raises:
+            REPLError: If code execution fails
+        """
+        # Filter out code blocks if present (LLM might wrap code)
+        code = self._extract_code(code)
+
+        if not code.strip():
+            return "No code to execute"
+
+        # Build restricted globals
+        restricted_globals = self._build_globals(env)
+
+        # Capture stdout
+        old_stdout = sys.stdout
+        sys.stdout = captured_output = io.StringIO()
+
+        try:
+            # Compile with RestrictedPython
+            byte_code = compile_restricted_exec(code)
+
+            if byte_code.errors:
+                raise REPLError(f"Compilation error: {', '.join(byte_code.errors)}")
+
+            # Execute
+            exec(byte_code.code, restricted_globals, env)
+
+            # Get output from stdout
+            output = captured_output.getvalue()
+
+            # Get output from PrintCollector if available
+            if '_print' in env and hasattr(env['_print'], '__call__'):
+                # PrintCollector stores prints in its txt attribute
+                print_collector = env['_print']
+                if hasattr(print_collector, 'txt'):
+                    output += ''.join(print_collector.txt)
+
+            # Check if last line was an expression (try to get its value)
+            # This handles cases like: error_count (should return its value)
+            lines = code.strip().split('\n')
+            if lines:
+                last_line = lines[-1].strip()
+                # If last line is a simple expression (no assignment, no keyword)
+                if last_line and not any(kw in last_line for kw in ['=', 'import', 'def', 'class', 'if', 'for', 'while', 'with']):
+                    try:
+                        # Try to evaluate the last line as expression
+                        result = eval(last_line, restricted_globals, env)
+                        if result is not None:
+                            output += str(result) + '\n'
+                    except:
+                        pass  # Not an expression, ignore
+
+            if not output:
+                return "Code executed successfully (no output)"
+
+            # Truncate output if too long (as per paper: "truncated version of output")
+            if len(output) > self.max_output_chars:
+                truncated = output[:self.max_output_chars]
+                return f"{truncated}\n\n[Output truncated: {len(output)} chars total, showing first {self.max_output_chars}]"
+
+            return output.strip()
+
+        except Exception as e:
+            raise REPLError(f"Execution error: {str(e)}")
+
+        finally:
+            sys.stdout = old_stdout
+
+    def _extract_code(self, text: str) -> str:
+        """
+        Extract code from markdown code blocks if present.
+
+        Args:
+            text: Raw text that might contain code
+
+        Returns:
+            Extracted code
+        """
+        # Check for markdown code blocks
+        if '```python' in text:
+            start = text.find('```python') + len('```python')
+            end = text.find('```', start)
+            if end != -1:
+                return text[start:end].strip()
+
+        if '```' in text:
+            start = text.find('```') + 3
+            end = text.find('```', start)
+            if end != -1:
+                return text[start:end].strip()
+
+        return text
+
+    def _build_globals(self, env: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Build restricted globals for safe execution.
+
+        Args:
+            env: User environment
+
+        Returns:
+            Safe globals dict
+        """
+        restricted_globals = safe_globals.copy()
+        restricted_globals.update(limited_builtins)
+        restricted_globals.update(utility_builtins)
+
+        # Add guards
+        restricted_globals['_iter_unpack_sequence_'] = guarded_iter_unpack_sequence
+        restricted_globals['_getattr_'] = safer_getattr
+        restricted_globals['_getitem_'] = lambda obj, index: obj[index]
+        restricted_globals['_getiter_'] = iter
+        restricted_globals['_print_'] = PrintCollector
+
+        # Add additional safe builtins
+        restricted_globals.update({
+            # Types
+            'len': len,
+            'str': str,
+            'int': int,
+            'float': float,
+            'bool': bool,
+            'list': list,
+            'dict': dict,
+            'tuple': tuple,
+            'set': set,
+            'frozenset': frozenset,
+            'bytes': bytes,
+            'bytearray': bytearray,
+
+            # Iteration
+            'range': range,
+            'enumerate': enumerate,
+            'zip': zip,
+            'map': map,
+            'filter': filter,
+            'reversed': reversed,
+            'iter': iter,
+            'next': next,
+
+            # Aggregation
+            'sorted': sorted,
+            'sum': sum,
+            'min': min,
+            'max': max,
+            'any': any,
+            'all': all,
+
+            # Math
+            'abs': abs,
+            'round': round,
+            'pow': pow,
+            'divmod': divmod,
+
+            # String/repr
+            'chr': chr,
+            'ord': ord,
+            'hex': hex,
+            'oct': oct,
+            'bin': bin,
+            'repr': repr,
+            'ascii': ascii,
+            'format': format,
+
+            # Type checking
+            'isinstance': isinstance,
+            'issubclass': issubclass,
+            'callable': callable,
+            'type': type,
+            'hasattr': hasattr,
+
+            # Constants
+            'True': True,
+            'False': False,
+            'None': None,
+        })
+
+        # Add safe standard library modules
+        # These are read-only and don't allow file/network access
+        import re
+        import json
+        import math
+        from datetime import datetime, timedelta
+        from collections import Counter, defaultdict
+
+        restricted_globals.update({
+            're': re,               # Regex (read-only)
+            'json': json,           # JSON parsing (read-only)
+            'math': math,           # Math functions
+            'datetime': datetime,   # Date parsing
+            'timedelta': timedelta, # Time deltas
+            'Counter': Counter,     # Counting helper
+            'defaultdict': defaultdict,  # Dict with defaults
+        })
+
+        return restricted_globals

package/recursive-llm/src/rlm/types.py

@@ -0,0 +1,37 @@
+"""Type definitions for RLM."""
+
+from typing import TypedDict, Optional, Any, Callable, Awaitable
+
+
+class Message(TypedDict):
+    """LLM message format."""
+    role: str
+    content: str
+
+
+class RLMConfig(TypedDict, total=False):
+    """Configuration for RLM instance."""
+    model: str
+    recursive_model: Optional[str]
+    api_base: Optional[str]
+    api_key: Optional[str]
+    max_depth: int
+    max_iterations: int
+    temperature: float
+    timeout: int
+
+
+class REPLEnvironment(TypedDict, total=False):
+    """REPL execution environment."""
+    context: str
+    query: str
+    recursive_llm: Callable[[str, str], Awaitable[str]]
+    re: Any  # re module
+
+
+class CompletionResult(TypedDict):
+    """Result from RLM completion."""
+    answer: str
+    iterations: int
+    depth: int
+    llm_calls: int