Metadata-Version: 2.4
Name: recursive-llm
Version: 0.5.0
Summary: Recursive Language Models for efficient long-context processing
Author: Grigori Gvadzabia
License-Expression: MIT
Project-URL: Homepage, https://github.com/grishahq/recursive-llm
Project-URL: Documentation, https://github.com/grishahq/recursive-llm
Project-URL: Repository, https://github.com/grishahq/recursive-llm
Project-URL: Issues, https://github.com/grishahq/recursive-llm/issues
Project-URL: Changelog, https://github.com/grishahq/recursive-llm/blob/main/CHANGELOG.md
Keywords: llm,ai,nlp,recursive,language-models
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: litellm<1.98.0,>=1.0.0
Requires-Dist: RestrictedPython>=6.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: visualizer
Requires-Dist: pypdf<7,>=6.18.0; extra == "visualizer"
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
Requires-Dist: coverage[toml]>=7.10.0; extra == "dev"
Requires-Dist: black==25.11.0; extra == "dev"
Requires-Dist: ruff==0.16.0; extra == "dev"
Requires-Dist: mypy<2.0.0,>=1.0.0; extra == "dev"
Dynamic: license-file

# Recursive Language Models (RLM)

![Recursive Language Models — large-context analysis through recursive selection](https://github.com/user-attachments/assets/c1c629fc-90ce-4c95-907e-0fd161628920)

[![CI](https://github.com/grishahq/recursive-llm/actions/workflows/ci.yml/badge.svg)](https://github.com/grishahq/recursive-llm/actions/workflows/ci.yml)
[![Python 3.9-3.12](https://img.shields.io/badge/python-3.9--3.12-3776AB.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/grishahq/recursive-llm/blob/main/LICENSE)
[![Latest release](https://img.shields.io/github/v/release/grishahq/recursive-llm)](https://github.com/grishahq/recursive-llm/releases/latest)

Analyze large contexts with bounded cost and inspectable execution. Instead of placing the full
source in model prompts, RLM keeps it in a restricted Python REPL, where the model can search,
compute, partition, and send only selected sections to language-model calls.

This is an independent Python implementation of the
[Recursive Language Models paper](https://arxiv.org/abs/2512.24601), focused on practical library
use: provider portability, tree-wide budgets, structured failures, reproducible benchmarks, and
complete run trajectories.

[Quick start](#quick-start) | [Visual comparison](#visual-comparison) | [Measured results](#measured-results) |
[Document-format evaluation](https://github.com/grishahq/recursive-llm/blob/main/DOCUMENT_EVALUATION.md) | [Configuration](#configuration) |
[Security](https://github.com/grishahq/recursive-llm/blob/main/SECURITY.md) |
[Original implementation](https://github.com/alexzhang13/rlm)

## Why use this implementation?

| Capability | What it provides |
| --- | --- |
| Externalized context | Large source text stays in the REPL instead of being repeated in model prompts |
| Bounded execution | Tree-wide limits for calls, tokens, estimated cost, elapsed time, and local execution |
| Observable runs | Per-run statistics, typed failures, versioned JSONL records, and complete trajectories |
| Provider portability | OpenAI, Anthropic, DeepSeek, local models, and other LiteLLM providers |
| Reproducible evaluation | Exact graders, generated corpora, pinned public documents, and repeated live runs |
| Restricted execution | Spawned RestrictedPython worker with hard timeouts and optional POSIX resource limits |

## Visual comparison

To celebrate 600 stars, the project includes a [side-by-side visualizer](https://github.com/grishahq/recursive-llm/blob/main/visualizer/README.md) of
real RLM and direct-model runs: synchronized replay, Python steps, call trees, exact grading, and
exportable recordings. Both sides use GPT-5.6 Luna through a ChatGPT-authenticated Codex CLI.

[![RLM and direct LLM comparison](https://raw.githubusercontent.com/grishahq/recursive-llm/main/.github/assets/rlm-comparison.gif)](https://github.com/grishahq/recursive-llm/blob/main/visualizer/public/rlm-comparison.mp4)

On one 100k-character paired experiment, both answers were exact. RLM used 11,656 total CLI model
tokens versus 37,521 directly, with elapsed times of 30.7 and 29.0 seconds respectively. The 10k
experiment favored direct completion. See [CODEX_COMPARISON.md](https://github.com/grishahq/recursive-llm/blob/main/CODEX_COMPARISON.md) for both
outcomes, raw recordings, methodology, and reproduction commands. These are individual experiments,
not a general performance claim or a measurement of subscription credits saved.

```bash
# Uses the existing ChatGPT login and consumes Codex subscription allowance
python examples/capture_codex_comparison.py --chars 100000 --output comparison.json
```

To test another model through the same transport, pass its settings explicitly:

```bash
python examples/capture_codex_comparison.py --model gpt-6.1-sol \
    --reasoning-effort low --max-depth 1 --chars 100000 --output comparison-sol.json
```

The web companion keeps the historical Luna/medium/depth-1 defaults. Imported captures record
their own model, reasoning effort, and depth; changing depth enables subcalls but does not force
the model to use them.

## Measured results

The exact 100k-character aggregation benchmark used one generated corpus seed and three live runs
per configuration. On this task, RLM improved exact correctness while reducing model-token usage.

![Direct and RLM results on the generated 100k-character benchmark](https://raw.githubusercontent.com/grishahq/recursive-llm/main/.github/assets/benchmark-100k.svg)

| Model and mode | Exact passes | Mean model tokens | Mean estimated cost |
| --- | ---: | ---: | ---: |
| GPT-5 mini, direct | 0/3 | 37,928 | $0.0088788 |
| GPT-5 mini, RLM | 3/3 | 8,224 | $0.0048132 |
| DeepSeek V4 Flash, direct | 0/3 | 39,364 | $0.0012240 |
| DeepSeek V4 Flash, RLM | 2/3 | 15,209 | $0.0010156 |

These measurements are an engineering check, not a paper reproduction or a universal quality
claim. Direct completion was faster and cheaper on short tasks. A separate 1M-character RLM scale
check passed 6/6 exact-graded runs, but those runs used local REPL computation without child RLMs.
See [BENCHMARK_RESULTS.md](https://github.com/grishahq/recursive-llm/blob/main/BENCHMARK_RESULTS.md) for methodology, raw summaries, public-document
experiments, limitations, and reproduction commands.
The separate [document-format evaluation](https://github.com/grishahq/recursive-llm/blob/main/DOCUMENT_EVALUATION.md) compares RLM with direct
completion on a SHA-pinned TXT book, PDF, CSV, and HTML documentation page and records two
reliability/performance changes evaluated one at a time.

Historical transaction and literary scores used legacy graders. Current graders reject ambiguous
or contradictory fields and record their version; see the grading-version note in
[BENCHMARK_RESULTS.md](https://github.com/grishahq/recursive-llm/blob/main/BENCHMARK_RESULTS.md) before comparing old and new runs.

## When to use RLM

RLM is a good fit when:

- the source is too large or too expensive to place in a normal model prompt;
- the task benefits from search, filtering, exact counting, or local Python computation;
- selected sections can be delegated to model calls instead of repeatedly sending the full source;
- call, token, cost, and time limits must apply to the whole recursive run.

Prefer direct completion when the context fits comfortably in the model window and the task is
small. Semantic synthesis across long narrative text remains difficult and should be evaluated on
your own data before production use.

## Execution at a glance

```text
query -> root model -> Python REPL over full context -> selected chunks or child calls -> answer
                       |                           |
                       +-- local search/compute   +-- shared budgets and trajectory
```

The root model receives the query and instructions, while the source is exposed as the `context`
variable. REPL state persists across iterations. The model can inspect small regions, perform local
computation, call a plain LM, or create a child RLM when the configured depth permits it.

## Installation

Use a fresh virtual environment (recommended), then install the latest release from PyPI:

```bash
pip install recursive-llm
```

`recursive-llm` and `rlms` both provide the `rlm` import namespace. Install only one of them in a
given environment.

For development, install from source:

```bash
git clone https://github.com/grishahq/recursive-llm.git
cd recursive-llm
pip install -e .
```

Or install the current GitHub version directly:

```bash
pip install "recursive-llm @ git+https://github.com/grishahq/recursive-llm.git"
```

## Requirements

- Python 3.9 or higher
- An API key for your chosen LLM provider (OpenAI, Anthropic, etc.)
- Or a local model setup (Ollama, llama.cpp, etc.)

## Quick Start

Set the provider key, create `quickstart.py`, and point it at a UTF-8 text file:

```bash
export OPENAI_API_KEY="sk-..."
```

```python
from pathlib import Path

from rlm import RLM


def main():
    rlm = RLM(model="gpt-5-mini")

    result = rlm.complete_result(
        query="What are the main themes in this document?",
        context=Path("document.txt").read_text(encoding="utf-8"),
    )
    print(result.answer)
    print(result.stats)


if __name__ == "__main__":
    main()
```

```bash
python quickstart.py
```

RLM uses a spawned worker process for isolated REPL execution. Executable Python scripts must use
the standard `if __name__ == "__main__":` entry-point guard, as shown above. This is required by
Python multiprocessing on spawn-based platforms; all repository examples follow this pattern.

### Usage and Cost Statistics

`RLM.stats` aggregates model calls across the complete recursion tree. Token usage comes from
provider responses, while cost is calculated on a best-effort basis using LiteLLM's model pricing
metadata.

```python
rlm = RLM(
    model="gpt-5-mini",
    recursive_model="deepseek/deepseek-v4-flash",
)
result = rlm.complete(query="Summarize this", context=document)

print(rlm.stats)
# {
#     "llm_calls": 11,
#     "root_calls": 3,
#     "recursive_calls": 8,
#     "leaf_calls": 4,
#     "prompt_tokens": 12500,
#     "completion_tokens": 3200,
#     "cached_tokens": 6000,
#     "estimated_cost_usd": 0.0047,
#     "by_model": {
#         "gpt-5-mini": {"calls": 3, ...},
#         "deepseek/deepseek-v4-flash": {"calls": 8, ...},
#     },
# }
```

Each root completion receives fresh statistics, so they describe one recursion tree rather than
lifetime usage.
`estimated_cost_usd` is `None` when LiteLLM has no pricing metadata for any completed call. Compare
`priced_calls` with `llm_calls` before treating the estimate as the full run cost.

When the same `RLM` instance runs concurrent completions, `RLM.stats` describes whichever root run
completed most recently. Use the structured result API for exact per-run statistics and trajectory:

```python
result = rlm.complete_result(query="Summarize this", context=document)
print(result.answer)
print(result.stats)
for event in result.trajectory:
    print(event.kind, event.depth, event.node_id, event.parent_id)

# Append one complete, versioned run record for later comparison
result.write_jsonl("runs.jsonl")
```

`acomplete_result` is the asynchronous equivalent. Trajectories include the complete root, child
RLM, and leaf-call tree. Query, context, model response, code, and output content are represented by
character counts by default. Set `capture_trajectory_content=True` only when the resulting logs are
allowed to contain that data. An optional `event_handler` receives events as they occur; handler
failures do not interrupt model completion.

Use the non-raising result API when failed runs must be persisted or compared alongside successful
runs:

```python
run = rlm.try_complete_result(query="Summarize this", context=document)
if run.succeeded:
    print(run.answer)
else:
    print(run.error_type, run.error)

# Success and failure records share the same versioned JSONL schema.
run.write_jsonl("runs.jsonl")
```

`atry_complete_result` is the asynchronous equivalent. Ordinary run failures return a
`FailedCompletionResult` with exact per-run statistics, secret-free configuration, and the complete
partial trajectory, including its terminal `run_error` event. Cancellation and other process-control
exceptions are not converted. The existing `complete`, `acomplete`, `complete_result`, and
`acomplete_result` APIs keep their exception behavior.

Completed JSONL records contain the final answer; failed records contain `answer: null` and a typed
error. Query, context, intermediate model responses, code, and REPL output follow the same redaction
setting as the in-memory trajectory.

### Live Model Comparison

The comparison script uses the same model for both root and recursive calls. It runs one small
recursive smoke test by default and reports latency, calls, tokens, and estimated cost:

```bash
python benchmarks/compare_same_model.py gpt-5-mini
python benchmarks/compare_same_model.py deepseek/deepseek-v4-flash
```

Use repeated runs and save raw records before comparing configurations:

```bash
python benchmarks/compare_same_model.py gpt-5-mini --full --runs 3 --jsonl results.jsonl
python benchmarks/compare_same_model.py gpt-5-mini --full --runs 3 --mode direct
python benchmarks/compare_same_model.py gpt-5-mini --generated-chars 100000 --seed 2026
```

`--max-depth` compares recursion capabilities; `--mode direct` sends task and context in one normal
long-context model request. The script reports pass rate, p50/p95 latency, calls, tokens, and
best-effort cost. Task-specific graders require exact IDs, numeric boundaries, and explicit labeled
counts rather than accepting arbitrary substrings. Live benchmarks make paid API calls and require
the corresponding provider keys. `--trace` includes sensitive content-bearing trajectories in the
JSON output and should be used deliberately.

The repository also includes a SHA-pinned real-document benchmark over the public-domain English
translation of *War and Peace*. The book itself is downloaded separately and is not committed:

```bash
curl -L https://www.gutenberg.org/files/2600/2600-0.txt \
    -o /tmp/war-and-peace-2600-0.txt
python benchmarks/war_and_peace.py gpt-5-mini /tmp/war-and-peace-2600-0.txt
python benchmarks/war_and_peace.py deepseek/deepseek-v4-flash \
    /tmp/war-and-peace-2600-0.txt
```

`benchmarks/multi_document.py` extends this to three independently sourced large corpora: *War and
Peace*, the official 9/11 Commission Report, and the official Python 3.14 text documentation. It
verifies every prepared artifact by SHA-256 and uses exact labeled-field graders. Download and PDF
extraction commands, hashes, task definitions, and measured candidate results are in
[`BENCHMARK_RESULTS.md`](https://github.com/grishahq/recursive-llm/blob/main/BENCHMARK_RESULTS.md).

## API Keys Setup

Copy the example environment file and add keys only for the providers you use:

```bash
cp .env.example .env
```

```dotenv
OPENAI_API_KEY=sk-...
DEEPSEEK_API_KEY=...
MOONSHOT_API_KEY=...
```

Use the LiteLLM provider prefix for non-OpenAI models, for example
`deepseek/deepseek-v4-flash` or `moonshot/kimi-k2.6`. This lets a hybrid RLM select the correct API
key for each model automatically.

Or pass directly in code:
```python
rlm = RLM(model="gpt-5-mini", api_key="sk-...")
```

## Supported Models

Works with 100+ LLM providers via LiteLLM:

```python
# OpenAI
rlm = RLM(model="gpt-5")
rlm = RLM(model="gpt-5-mini")

# Anthropic
rlm = RLM(model="claude-sonnet-4")
rlm = RLM(model="claude-sonnet-4-20250514")

# Ollama (local)
rlm = RLM(model="ollama/llama3.2")
rlm = RLM(model="ollama/mistral")

# llama.cpp (local)
rlm = RLM(
    model="openai/local",
    api_base="http://localhost:8000/v1"
)

# Azure OpenAI
rlm = RLM(model="azure/gpt-4-deployment")

# And many more via LiteLLM...
```

## Advanced Usage

### Two Models (Optimize Cost)

Use a cheaper model for recursive calls:

```python
rlm = RLM(
    model="gpt-5",              # Root LM (main decisions)
    recursive_model="gpt-5-mini"  # Recursive calls (cheaper)
)
```

### Async API

For better performance with parallel recursive calls:

```python
import asyncio

async def main():
    rlm = RLM(model="gpt-5-mini")
    result = await rlm.acomplete(query, context)
    print(result)

if __name__ == "__main__":
    asyncio.run(main())
```

### Configuration

```python
rlm = RLM(
    model="gpt-5-mini",
    max_depth=2,                 # One child RLM level, then a plain-LM fallback
    max_iterations=20,           # Maximum REPL iterations per RLM
    repl_timeout=5,              # Hard timeout for each local Python step
    max_output_chars=2000,       # Observation truncation limit
    repl_max_snapshot_bytes=1_000_000,  # Parent-copy cap; full state stays in the worker
    max_concurrent_subcalls=4,   # Bound batch concurrency
    max_total_calls=24,          # Exact provider-call cap for the full recursion tree
    max_total_tokens=100_000,    # Stop after reported usage crosses this value
    max_total_cost_usd=0.10,     # Stop after reported cost crosses this value
    max_elapsed_seconds=300,     # Deadline shared by root and child calls
    max_retries=2,                # Retry transient provider failures; default is 0
    retry_backoff_seconds=1.0,   # Exponential retry delay; Retry-After is respected
    # Optional LiteLLM params: temperature, timeout, etc.
)
```

Call limits are reserved atomically before provider requests, including batched and recursive
subcalls. Token and cost limits are evaluated after each response because providers only report
those values after generation; the crossing response is included in partial statistics attached to
`BudgetExceededError`. A deadline also bounds in-flight provider requests and REPL exchanges, and
prevents a validator result completed after the deadline from being accepted. A synchronous
validator cannot be forcibly stopped safely, so slow validator code can delay delivery of the
resulting `BudgetExceededError`; validators should remain fast and independently bounded. All
limits are optional and are reset for each root completion.

Retries are opt-in and share the same call and elapsed-time budgets as the rest of the recursion
tree. Every retry is counted as a provider call and recorded in statistics and trajectories.
RLM disables hidden LiteLLM retries to preserve exact accounting; configure `max_retries` on `RLM`
instead of passing `num_retries` or `max_retries` as a LiteLLM option. Null provider content is
normalized to an empty response so the existing repair iteration can recover, while malformed
response structures fail with `ProviderResponseError` or use the bounded retry path when enabled.

### Final Answer Validation

Applications can reject a syntactically valid final answer and give deterministic feedback to the
model without leaving the bounded run:

```python
def validate_answer(answer: str):
    if not answer.startswith("count="):
        return "Answer must start with 'count='."
    return None

rlm = RLM(
    model="gpt-5-mini",
    final_answer_validator=validate_answer,
)
```

The validator returns `None` to accept an answer or a non-empty error string to reject it. Rejected
answers and feedback are represented by lengths in redacted trajectories and by content only when
`capture_trajectory_content=True`. Validator exceptions abort the run as application errors.

`max_depth` is an explicit constructor option so that runs remain reproducible. It is not read from
an environment variable by the library. Applications may map their own configuration or environment
variables to this argument.

| `max_depth` | Behavior |
| ---: | --- |
| `0` | Root RLM and REPL only; no LM subcalls |
| `1` (default) | Root RLM may call a plain LM |
| `2` | Root RLM may create one child RLM; the child falls back to a plain LM |
| `n` | Adds one child RLM level for every increment above `1` |

This follows the paper's capability-based depth convention. The root RLM itself is depth `0` and is
still valid when `max_depth=0`.

### REPL Subcall API

The model can use these functions from its persistent REPL:

```python
# One plain LM call, without another REPL loop
llm_query("Extract the date", context[1000:2000])

# Child RLM when depth permits; otherwise one plain-LM boundary call
rlm_query("Analyze this section", context[2000:8000])

# Ordered parallel calls, limited by max_concurrent_subcalls
results = llm_query_batched(queries, chunks)
```

`recursive_llm` remains as a backward-compatible alias for `rlm_query`. A step can finish directly
through `FINAL(...)`, `FINAL_VAR(...)`, or the mutable `answer` object:

```python
answer["content"] = result
answer["ready"] = True
```

## How It Works

1. **Context is stored as a variable** in a Python REPL environment
2. **Root LM gets only the query** plus instructions
3. **LM can explore context** using Python code:
   ```python
   # Peek at context
   context[:1000]

   # Search with regex
   re.findall(r'pattern', context)

   # Recursive processing with a plain-LM boundary fallback
   rlm_query("extract dates", context[1000:2000])
   ```
4. **Returns the final answer** via a standalone `FINAL("answer")`, `FINAL_VAR(name)`, or `answer`
   publication

REPL variables persist between iterations. Each local step executes in an isolated subprocess, its
final expression is evaluated exactly once, print output is isolated per step, and non-terminating
local code is terminated by `repl_timeout`. Time spent waiting for model subcalls is not charged to
the local Python timeout. Imports are limited to the already exposed `re`, `json`, `math`,
`datetime`, and `collections` helpers; arbitrary modules remain blocked.

Ordinary user variables are copied back to the parent after each step only up to
`repl_max_snapshot_bytes` (1 MB by default), preferring smaller values. Larger values remain intact
in the persistent worker and are still available to later code and `FINAL_VAR`; the cap avoids
repeatedly serializing large intermediate lists or strings. Increase the limit only when an
application directly depends on the parent-side compatibility snapshot.

POSIX deployments may also opt in to worker-process limits:

```python
rlm = RLM(
    model="gpt-5-mini",
    repl_memory_limit_mb=512,
    repl_cpu_time_limit_seconds=10,
    repl_max_open_files=64,
)
```

These values depend on the runtime and workload, so the library does not guess defaults. A
configured limit that the platform cannot enforce fails worker startup explicitly. RestrictedPython
and a subprocess are defense-in-depth controls, not a security boundary for hostile code; read
[SECURITY.md](https://github.com/grishahq/recursive-llm/blob/main/SECURITY.md) before processing untrusted prompts or contexts.

## Examples

See the `examples/` directory for complete working examples:
- `basic_usage.py` - Simple complete with OpenAI
- `ollama_local.py` - Using Ollama locally
- `two_models.py` - Cost optimization with two models
- `long_document.py` - Processing 50k+ token documents
- `data_extraction.py` - Extract structured data from text
- `multi_file.py` - Process multiple documents
- `custom_config.py` - Advanced configuration

Run an example:
```bash
# Set your API key first
export OPENAI_API_KEY="sk-..."

# Run example
python examples/basic_usage.py
```

## Performance

### Paper Results

On OOLONG benchmark (132k tokens):
- GPT-5: baseline
- RLM(GPT-5-Mini): **33% better than GPT-5** at similar cost

### Reproducible Project Benchmark

`benchmarks/compare_same_model.py` contains deterministic structured contexts with exact expected
answers. `benchmarks/generated_long_context.py` creates byte-reproducible transaction corpora with
seed, SHA-256 identity, and a computed answer key. Model outputs remain stochastic, so use `--runs`
and compare pass rate plus p50/p95 latency before drawing quality conclusions. See
[BENCHMARK_RESULTS.md](https://github.com/grishahq/recursive-llm/blob/main/BENCHMARK_RESULTS.md) for the latest checked-in live comparison.

`benchmarks/war_and_peace.py` adds exact chapter counting, distant fact retrieval, and narrative
evidence synthesis over a verified 3.2-million-character real document.

## Development

```bash
# Clone repository
git clone https://github.com/grishahq/recursive-llm.git
cd recursive-llm

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests, branch coverage, and the enforced coverage gate
pytest

# Type checking
mypy src/rlm

# Linting
ruff check src tests benchmarks examples

# Format code
black src tests examples benchmarks

# Build the source distribution and wheel
python -m build
```

GitHub Actions runs these gates across Python 3.9-3.12 on Linux, plus Python 3.12 on macOS and
Windows. It also installs the built wheel and runs the offline demo.

## Architecture

```
RLM
├── Core (async completion logic)
├── Run State (per-invocation budget, usage, and trajectory)
├── REPL Executor (restricted subprocess, persistent state, hard step timeout)
├── Prompt Builder (system prompts)
└── Parser (extract FINAL() answers)
```

Built on top of LiteLLM for universal LLM support.

## Limitations

- Python REPL steps are sequential; explicit batched LM/RLM subcalls can run concurrently
- No prefix caching (future enhancement)
- Recursion depth is limited (configurable via `max_depth`)
- No streaming support yet

## Troubleshooting

### "Max iterations exceeded"
- Increase `max_iterations` parameter
- Simplify your query
- Check if the model is getting stuck in a loop

### "API key not found"
- Copy `.env.example` to `.env` and set the appropriate provider variable:
  - `OPENAI_API_KEY` for OpenAI
  - `DEEPSEEK_API_KEY` for DeepSeek
  - `MOONSHOT_API_KEY` for Kimi
- Or pass `api_key` parameter to RLM constructor

### "Model not found"
- Check model name format for your provider
- See LiteLLM docs: https://docs.litellm.ai/docs/providers

### Using Ollama
- Make sure Ollama is running: `ollama serve`
- Pull a model first: `ollama pull llama3.2`
- Use model format: `ollama/model-name`

## Contributing

Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Ensure all tests pass (`pytest tests/`)
5. Follow code style (use `black` and `ruff`)
6. Submit a pull request

## Citation

This implementation is based on the RLM paper by Alex L. Zhang, Tim Kraska, and Omar Khattab.

**To cite this implementation:**
```bibtex
@software{rlm_python,
  title = {recursive-llm: Python Implementation of Recursive Language Models},
  author = {Gvadzabia, Grisha},
  year = {2025},
  url = {https://github.com/grishahq/recursive-llm}
}
```

**To cite the original paper:**
```bibtex
@misc{zhang2025rlm,
  title = {Recursive Language Models},
  author = {Zhang, Alex L. and Kraska, Tim and Khattab, Omar},
  year = {2025},
  url = {https://arxiv.org/abs/2512.24601},
  eprint = {2512.24601},
  archivePrefix = {arXiv}
}
```

## License

MIT License - see LICENSE file for details

## Acknowledgments

Based on the Recursive Language Models paper by Alex L. Zhang, Tim Kraska, and Omar Khattab.

Built using:
- LiteLLM for universal LLM API support
- RestrictedPython for restricted code execution

## Links

- **Paper**: https://alexzhang13.github.io/blog/2025/rlm/
- **arXiv**: https://arxiv.org/abs/2512.24601
- **Official implementation**: https://github.com/alexzhang13/rlm
- **LiteLLM Docs**: https://docs.litellm.ai/
- **Changelog**: https://github.com/grishahq/recursive-llm/blob/main/CHANGELOG.md
- **Releases**: https://github.com/grishahq/recursive-llm/releases
- **Issues**: https://github.com/grishahq/recursive-llm/issues
