### Install uv and Setup Project

Source: https://github.com/alexzhang13/rlm/blob/main/AGENTS.md

Installs uv, initializes a new project, sets up a virtual environment with Python 3.12, and installs the rlm package in editable mode. Includes optional installations for Modal and Prime sandbox support.

```bash
# Install uv (first time)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Setup blank project if needed
uv init && uv venv --python 3.12
source .venv/bin/activate

# Install in editable mode
uv pip install -e .

# For Modal sandbox support
uv pip install -e ".[modal]"

# For Prime sandbox support
uv pip install -e ".[prime]"
```

--------------------------------

### Example - vLLM Local Server Setup

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/6-clients.md

Illustrates how to configure the RLM client to connect to a locally running vLLM server compatible with the OpenAI API. Requires vLLM to be installed and the server started.

```python
# Requires: pip install vllm
# Start server: python -m vllm.entrypoints.openai.api_server --model mistralai/Mistral-7B-Instruct-v0.1

rlm = RLM(
    backend="vllm",  # or "openai" with base_url
    backend_kwargs={
        "model_name": "mistralai/Mistral-7B-Instruct-v0.1",
        "base_url": "http://localhost:8000/v1",
        "api_key": "not-needed",
    }
)
```

--------------------------------

### Example Usage of OpenAI Client for Completion

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/6-clients.md

Demonstrates how to use the initialized OpenAI client to get a text completion and access usage summary, including total cost.

```python
rlm = RLM(
    backend="openai",
    backend_kwargs={"model_name": "gpt-4", "api_key": "sk-…"},
)
result = rlm.completion("Solve this problem...")
print(f"Cost: ${result.usage_summary.total_cost}")
```

--------------------------------

### Install RLM with uv

Source: https://github.com/alexzhang13/rlm/blob/main/docs/getting-started.md

Installs uv, creates and activates a virtual environment, and installs RLM in editable mode. Ensure Python 3.11 or higher is installed.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh

uv init && uv venv --python 3.12
source .venv/bin/activate

uv pip install -e .
```

--------------------------------

### Install Prime Intellect SDK and Set API Key

Source: https://github.com/alexzhang13/rlm/blob/main/README.md

Install the Prime Intellect SDK using uv pip and set the PRIME_API_KEY environment variable to use Prime Sandboxes.

```bash
uv pip install -e ".[prime]"
export PRIME_API_KEY=...
```

--------------------------------

### Google Gemini Client Initialization Example

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/6-clients.md

A basic example of initializing the RLM client for Google Gemini models, specifying the model and API key.

```python
rlm = RLM(
    backend="gemini",
    backend_kwargs={
        "model_name": "gemini-2.0-flash",
        "api_key": "AIzaSy...",
    }
)
```

--------------------------------

### Azure OpenAI Client Initialization Example

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/6-clients.md

Example of initializing the RLM client for Azure OpenAI, specifying deployment name, API key, base URL, and API version.

```python
rlm = RLM(
    backend="azure_openai",
    backend_kwargs={
        "model_name": "my-gpt4-deployment",
        "api_key": "abc123...",
        "base_url": "https://myorg.openai.azure.com/",
        "api_version": "2024-08-01-preview",
    }
)
```

--------------------------------

### Run Development Server

Source: https://github.com/alexzhang13/rlm/blob/main/visualizer/README.md

Commands to start the Next.js development server using different package managers.

```bash
npm run dev
```

```bash
yarn dev
```

```bash
pnpm dev
```

```bash
bun dev
```

--------------------------------

### Configure Local Environment Setup Code

Source: https://github.com/alexzhang13/rlm/blob/main/docs/api/rlm.md

For the 'local' execution environment, you can specify setup code to be run before each completion. This is useful for importing necessary libraries.

```python
environment_kwargs = {
    "setup_code": "import numpy as np",  # Run before each completion
}
```

--------------------------------

### Install RLM Library

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/README.md

Install the RLM library using pip. This is the first step to using the library.

```bash
pip install rlms
```

--------------------------------

### Full RLM Configuration Example

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/7-configuration.md

A comprehensive example demonstrating the integration of various RLM configuration options, including model and backend settings, environment, recursion limits, custom tools, sampling, logging, persistence, and callbacks.

```python
from rlm import RLM
from rlm.logger import RLMLogger

logger = RLMLogger(log_dir="./logs", file_name="my_task")

rlm = RLM(
    # Primary model
    backend="openai",
    backend_kwargs={
        "model_name": "gpt-4",
        "api_key": "sk-...",  # or from OPENAI_API_KEY
    },
    
    # Alternative backend for sub-calls
    other_backends=["anthropic"],
    other_backend_kwargs=[{
        "model_name": "claude-3-opus",
        "api_key": "sk-ant-...",  # or from ANTHROPIC_API_KEY
    }],
    
    # Environment
    environment="local",
    environment_kwargs={
        "setup_code": "import json\nimport requests",
    },
    
    # Recursion and limits
    max_depth=2,
    max_iterations=50,
    max_budget=20.0,                      # $20 limit
    max_timeout=300.0,                    # 5 minutes
    max_tokens=100000,                    # Tokens limit
    max_errors=3,                         # Consecutive errors
    
    # Custom tools
    custom_tools={
        "fetch_json": lambda url: __import__("requests").get(url).json(),
        "CONFIG": {"retries": 3, "timeout": 10},
    },
    
    # Sampling
    sampling_args={"temperature": 0.5},
    sub_sampling_args={"temperature": 0.9},
    
    # Logging and UI
    logger=logger,
    verbose=True,
    
    # Persistence (multi-turn)
    persistent=False,
    
    # Compaction
    compaction=False,
    compaction_threshold_pct=0.85,
    
    # Callbacks
    on_iteration_complete=lambda d, i, t: print(f"Iter {i}: {t:.1f}s"),
)

```

--------------------------------

### Run the RLM Visualizer

Source: https://github.com/alexzhang13/rlm/blob/main/docs/getting-started.md

Navigate to the visualizer directory, install dependencies, and run the development server to explore RLM log files.

```bash
cd visualizer/
npm install
npm run dev  # Opens at localhost:3001
```

--------------------------------

### Launch Training Run

Source: https://github.com/alexzhang13/rlm/blob/main/training/README.md

Use this command to launch a training run with a specified configuration file. Ensure prime-rl is installed and the environment is set up.

```bash
uv run rl @ training/configs/rlm-qwen3-30b-example.toml
```

--------------------------------

### Add Modal Library and Authenticate

Source: https://github.com/alexzhang13/rlm/blob/main/README.md

Install the Modal library using uv and authenticate your Modal account to use Modal Sandboxes as a REPL environment.

```bash
uv add modal  # add modal library
modal setup   # authenticate account
```

--------------------------------

### Quickstart RLM Completion with OpenAI

Source: https://github.com/alexzhang13/rlm/blob/main/README.md

Demonstrates how to perform an RLM completion using the OpenAI backend with GPT-5-nano. Ensure your OPENAI_API_KEY environment variable is set.

```python
from rlm import RLM

rlm = RLM(
    backend="openai",
    backend_kwargs={"model_name": "gpt-5-nano"},
    verbose=True,  # For printing to console with rich, disabled by default.
)

print(rlm.completion("Print me the first 100 powers of two, each on a newline.").response)
```

--------------------------------

### Portkey Client Cost Tracking Example

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/6-clients.md

Initialize the Portkey client and set a 'max_budget' for cost tracking. Portkey handles multi-model routing and failover.

```python
rlm = RLM(
    backend="portkey",
    backend_kwargs={
        "model_name": "gpt-4",
        "api_key": "portkey_...",
    },
    max_budget=10.0,  # Portkey tracks cost
)
```

--------------------------------

### Running the RLM Log Visualizer

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/4-logger-api.md

Instructions to start the RLM log visualizer. Navigate to the visualizer directory and run the development server.

```bash
cd visualizer/
npm run dev  # Starts on localhost:3001
# Load the JSONL file in the UI
```

--------------------------------

### Install and Set Up Prime Intellect Sandboxes

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/5-environments.md

Install the RLM package for Prime Intellect integration and set your API key as an environment variable. This is required to use Prime Intellect's beta cloud sandbox platform.

```bash
# Install and set up
pip install 'rlms[prime]'
export PRIME_API_KEY=your_api_key
```

--------------------------------

### Install RLM with Modal Support

Source: https://github.com/alexzhang13/rlm/blob/main/docs/getting-started.md

Installs the Modal extra for RLM, enabling cloud-based sandboxed execution. Requires RLM to be installed first.

```bash
uv pip install -e ".[modal]"

modal setup
```

--------------------------------

### Minimal RLM Example

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/README.md

A basic example demonstrating how to initialize the RLM class with an OpenAI backend and perform a completion. This snippet shows the fundamental usage pattern.

```python
from rlm import RLM
rlm = RLM(backend="openai", backend_kwargs={"model_name": "gpt-4"})
result = rlm.completion("Your prompt here")
print(result.response)
```

--------------------------------

### Install and Authenticate for Modal Sandboxes

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/5-environments.md

Install the necessary RLM package for Modal integration and authenticate your account. This is a prerequisite for using Modal sandboxes.

```bash
# Install and authenticate
pip install 'rlms[modal]'
modal setup  # Authenticate with Modal account
```

--------------------------------

### Run Quickstart Test with Makefile

Source: https://github.com/alexzhang13/rlm/blob/main/README.md

Executes a quick RLM query using the OpenAI client via the Makefile. This command also generates console output and a log file for visualization.

```bash
make quickstart
```

--------------------------------

### Example: Modal Sandbox for Cloud Execution

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/5-environments.md

Example of initializing RLM for Modal execution, specifying a backend model and max depth. The completion prompt explicitly notes that the code runs in a cloud sandbox.

```python
rlm = RLM(
    backend="openai",
    backend_kwargs={"model_name": "gpt-4"},
    environment="modal",
    max_depth=2,
)

result = rlm.completion("""
Download a dataset, process it, and return summary statistics.
This code runs in a Modal sandbox, not on your machine.
""")
```

--------------------------------

### Minimal RLM Code Example

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/0-index.md

A basic example demonstrating how to initialize the RLM class and generate a completion. Ensure you have the necessary backend configured (e.g., OpenAI API key set as an environment variable).

```python
from rlm import RLM

rlm = RLM(
    backend="openai",
    backend_kwargs={"model_name": "gpt-4"},
)
result = rlm.completion("Your prompt")
print(result.response)
```

--------------------------------

### Usage Summary Example

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/2-types.md

Demonstrates how to access and display aggregated usage statistics, including total tokens, cost, and per-model call counts.

```python
usage = result.usage_summary
print(f"Total tokens: {usage.total_input_tokens + usage.total_output_tokens}")
print(f"Total cost: ${usage.total_cost}")
for model_name, model_usage in usage.model_usage_summaries.items():
    print(f"{model_name}: {model_usage.total_calls} calls, {model_usage.total_input_tokens} input tokens")
```

--------------------------------

### Clone rlm and Install Dependencies

Source: https://github.com/alexzhang13/rlm/blob/main/AGENTS.md

Clones the rlm repository and installs development and testing dependencies using uv. Also includes instructions for installing pre-commit hooks.

```bash
git clone https://github.com/alexzhang13/rlm.git
cd rlm

# Standard development:
uv sync

# Install dev + test dependencies:
uv sync --group dev --group test

# Install pre-commit hooks:
uv run pre-commit install
```

--------------------------------

### RLM Completion Example

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/1-rlm-core-api.md

Demonstrates how to initialize an RLM instance and perform a completion query. Shows how to access the response, execution time, and token usage from the result.

```python
from rlm import RLM

rlm = RLM(
    backend="openai",
    backend_kwargs={"model_name": "gpt-4"},
    environment="local",
    max_iterations=20,
    verbose=True,
)

result = rlm.completion(
    prompt="Find the sum of all prime numbers under 1000.",
    root_prompt="What is the sum of all primes < 1000?"
)

print(f"Answer: {result.response}")
print(f"Time: {result.execution_time:.2f}s")
print(f"Tokens: {result.usage_summary.total_input_tokens} input, {result.usage_summary.total_output_tokens} output")
```

--------------------------------

### Verify Docker Installation

Source: https://github.com/alexzhang13/rlm/blob/main/docs/getting-started.md

Checks if Docker is installed and available on your system. This is a prerequisite for using Docker support with RLM.

```bash
docker --version
```

--------------------------------

### Basic RLM Completion

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/9-quickstart-examples.md

Demonstrates the simplest way to initialize RLM and get a completion. Ensure your OPENAI_API_KEY environment variable is set.

```python
from rlm import RLM
import os

rlm = RLM(
    backend="openai",
    backend_kwargs={"model_name": "gpt-4", "api_key": os.getenv("OPENAI_API_KEY")},
    verbose=True,
)

result = rlm.completion("Print the first 100 prime numbers, each on a new line.")
print(result.response)
```

--------------------------------

### Initialize RLM with Local Environment

Source: https://github.com/alexzhang13/rlm/blob/main/docs/getting-started.md

Configure RLM to run locally within the same Python process. This is the default and requires no additional setup.

```python
rlm = RLM(
    backend="openai",
    backend_kwargs={"model_name": "gpt-4o"},
    environment="local",
)
```

--------------------------------

### RLM Completion Example

Source: https://github.com/alexzhang13/rlm/blob/main/docs/api/rlm.md

Demonstrates a typical RLM completion call and accessing its response, execution time, metadata, and usage summary.

```python
result = rlm.completion(
    "Calculate the factorial of 100 and return the number of digits."
)

print(result.response)          # "158"
print(result.execution_time)    # 12.34
print(result.metadata)          # Trajectory dict (if logger provided), else None
print(result.usage_summary.to_dict())
# {'model_usage_summaries': {'gpt-4o': {'total_calls': 5, ...}}}
```

--------------------------------

### Install and Set Up E2B Code Interpreter

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/5-environments.md

Install the RLM package for E2B integration and set your API key as an environment variable. This enables the use of E2B's cloud code sandbox with a built-in Python interpreter.

```bash
pip install 'rlms[e2b]'
export E2B_API_KEY=your_api_key
```

--------------------------------

### Example: Docker Environment with Volume Mount

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/5-environments.md

Demonstrates mounting a host directory into the Docker container for data persistence. The RLM can then process files within the mounted volume.

```python
rlm = RLM(
    environment="docker",
    environment_kwargs={
        "image": "python:3.11-slim",
        "volumes": {"/data": "/data"},  # Mount /data from host
    }
)

result = rlm.completion("Process files in /data and save results")
```

--------------------------------

### Specify RLM Backend

Source: https://github.com/alexzhang13/rlm/blob/main/docs/api/rlm.md

Configure the LM provider backend for the root model. Examples show how to select OpenAI, Anthropic, or a local vLLM server.

```python
# OpenAI
rlm = RLM(backend="openai", ...)

# Anthropic
rlm = RLM(backend="anthropic", ...)

# Local vLLM server
rlm = RLM(backend="vllm", ...)
```

--------------------------------

### Get Environment Instance

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/5-environments.md

Instantiate a specific RLM environment by its type string and associated keyword arguments.

```python
from rlm.environments import get_environment

env = get_environment("local", {
    "setup_code": "import pandas as pd"
})
# Returns LocalREPL instance
```

--------------------------------

### RLM Persistence Example

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/5-environments.md

Demonstrates using RLM in a persistent mode within a context manager to maintain state across multiple completion calls.

```python
with RLM(persistent=True) as rlm:
    # Context 0
    result1 = rlm.completion("What is 2+2?")
    
    # Context 1 - history from first call available as history_0
    result2 = rlm.completion("What about 3+3?")
    # Code can access: context_0, context_1, history_0, etc.
```

--------------------------------

### RLM Context Manager Example

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/1-rlm-core-api.md

Shows how to use the RLM as a context manager. The environment is automatically cleaned up when the `with` block is exited, ensuring proper resource management.

```python
with RLM(backend="openai", backend_kwargs={"model_name": "gpt-4"}) as rlm:
    result = rlm.completion("Your question here")
    print(result.response)
# Environment automatically cleaned up
```

--------------------------------

### API Key Setup for Backends

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/README.md

Set environment variables for API keys required by different language model backends. Ensure these are set before initializing RLM with the corresponding backend.

```bash
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
```

--------------------------------

### Budget-Constrained RLM Configuration

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/7-configuration.md

Configure RLM with a maximum budget to control costs. This example sets a $5 limit using the OpenRouter backend.

```python
rlm = RLM(
    backend="openrouter",
    backend_kwargs={
        "model_name": "openai/gpt-4",
        "api_key": "sk-or-...",
    },
    max_budget=5.0,  # $5 limit
)
```

--------------------------------

### Basic RLM Completion Usage

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/7-configuration.md

Demonstrates how to use the RLM library to get a completion and access its response, usage summary, and execution time.

```python
result = rlm.completion(
    prompt="Process this data...",
    root_prompt="What insights can you find?"
)

print(f"Answer: {result.response}")
print(f"Cost: ${result.usage_summary.total_cost}")
print(f"Time: {result.execution_time:.2f}s")
```

--------------------------------

### RLM Logging with Disk Persistence

Source: https://github.com/alexzhang13/rlm/blob/main/README.md

Example showing how to initialize RLMLogger to save trajectories to disk in JSONL format for visualization. This also captures the in-memory metadata.

```python
from rlm.logger import RLMLogger
from rlm import RLM

logger = RLMLogger(log_dir="./logs")
rlm = RLM(..., logger=logger)
```

--------------------------------

### Logging and Verbosity Setup

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/7-configuration.md

Configure RLM's logging by providing a custom logger instance for trajectory logging and enable verbose console output.

```python
from rlm.logger import RLMLogger

rlm = RLM(
    logger=RLMLogger(log_dir="./logs"),  # Trajectory logging
    verbose=True,                        # Console output with rich
)
```

--------------------------------

### Initialize RLM with OpenAI Backend

Source: https://github.com/alexzhang13/rlm/blob/main/docs/api/rlm.md

Instantiate the RLM class using the OpenAI backend with a specified model. This is the primary way to start using RLM for completions.

```python
from rlm import RLM

rlm = RLM(
    backend="openai",
    backend_kwargs={"model_name": "gpt-5-nano"},
)
```

--------------------------------

### Sampling Control with RLM

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/9-quickstart-examples.md

Demonstrates how to control sampling parameters like temperature and top_p for RLM. Examples include deterministic, creative, and mixed sampling strategies for root and sub-calls.

```python
from rlm import RLM

# Deterministic
rlm_deterministic = RLM(
    backend="openai",
    backend_kwargs={"model_name": "gpt-4"},
    sampling_args={"temperature": 0.0, "seed": 42},
)

# Creative
rlm_creative = RLM(
    backend="openai",
    backend_kwargs={"model_name": "gpt-4"},
    sampling_args={"temperature": 1.5, "top_p": 0.95},
)

# Different for sub-calls
rlm_mixed = RLM(
    backend="openai",
    backend_kwargs={"model_name": "gpt-4"},
    sampling_args={"temperature": 0.3},           # Root: conservative
    sub_sampling_args={"temperature": 0.9},       # Sub-calls: exploratory
    max_depth=2,
)
```

--------------------------------

### Configure Local REPL Environment

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/5-environments.md

Initializes the RLM with the 'local' environment, suitable for non-isolated execution. It allows specifying setup code and configuration for persistence, compaction, and concurrency.

```python
from rlm import RLM

rlm = RLM(
    environment="local",
    environment_kwargs={
        "setup_code": "import numpy as np\nimport pandas as pd",
        # Optional kwargs below
        "persistent": False,
        "compaction": False,
        "max_concurrent_subcalls": 4,
    }
)
```

--------------------------------

### Use Local REPL for Prime Number Calculation

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/5-environments.md

Demonstrates using the 'local' RLM environment to find prime numbers and store the result. It shows how to configure setup code and then use the completion API to solve a problem.

```python
from rlm import RLM

rlm = RLM(
    environment="local",
    environment_kwargs={"setup_code": "import numpy as np"},
)

result = rlm.completion("""
Find all prime numbers less than 100.
Store the result in answer["content"] and set answer["ready"] = True.
""")

print(result.response)
```

--------------------------------

### Install Daytona Sandboxes for RLM

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/5-environments.md

Install the RLM package required for integrating with Daytona cloud-based sandboxes. No further setup or API key is mentioned in this section.

```bash
pip install 'rlms[daytona]'
```

--------------------------------

### Basic RLM Environment Structure

Source: https://github.com/alexzhang13/rlm/blob/main/AGENTS.md

Example of a custom environment inheriting from NonIsolatedEnv. Ensure all abstract methods are implemented and necessary setup is performed.

```python
from rlm.environments.base_env import NonIsolatedEnv
from rlm.core.types import REPLResult

class MyEnvironment(NonIsolatedEnv):
    def __init__(self, lm_handler_address: tuple[str, int] | None = None, 
                 context_payload: dict | list | str | None = None, **kwargs):
        super().__init__(**kwargs)
        self.lm_handler_address = lm_handler_address
        self.setup()
        if context_payload:
            self.load_context(context_payload)
            
    def setup(self):
        # Initialize execution namespace
        
    def load_context(self, context_payload: dict | list | str):
        # Make context available to executed code
        
    def execute_code(self, code: str) -> REPLResult:
        # Execute code and return REPLResult
        
    def cleanup(self):
        # Clean up resources

```

--------------------------------

### Stream-Based Monitoring with LiveMonitor

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/8-advanced-topics.md

Implement real-time monitoring of RLM iterations by providing a callback function to the RLM constructor. This example shows how to track the number of iterations completed.

```python
import sys

class LiveMonitor:
    def __init__(self):
        self.iterations = 0
        self.total_tokens = 0
    
    def on_iteration_complete(self, depth, iteration_num, duration):
        self.iterations += 1
        sys.stderr.write(f"\rIterations: {self.iterations}")
        sys.stderr.flush()

monitor = LiveMonitor()
rlm = RLM(on_iteration_complete=monitor.on_iteration_complete)
result = rlm.completion(prompt)
print(f"\nCompleted in {result.execution_time:.1f}s")
```

--------------------------------

### LLM Query Function Call Example

Source: https://github.com/alexzhang13/rlm/blob/main/docs/architecture.md

Illustrates how model code uses the `llm_query` function to get a direct LM completion. This function is fast and lightweight, making a single prompt-to-text call.

```python
Model code: answer = llm_query("Summarize this text: ...")
    │
    ▼
LocalREPL._llm_query()
    │  Creates LMRequest(prompt=..., depth=self.depth)
    │  Opens TCP socket to handler
    ▼
LMHandler (TCP server)
    │  get_client(model, depth) → selects backend
    │  client.completion(prompt) → calls LM API
    ▼
Response flows back over socket
    │
    ▼
Returns response string to model code
```

--------------------------------

### Initialize Virtual Environment with uv

Source: https://github.com/alexzhang13/rlm/blob/main/README.md

Sets up a Python virtual environment using uv, a fast package and virtual environment manager. Change the Python version as needed.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
uv init && uv venv --python 3.12  # change version as needed
uv pip install -e .
```

--------------------------------

### RLM Initialization and Completion

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/0-index.md

Demonstrates how to initialize an RLM instance with essential parameters and call the main completion method. It also shows how to access the results.

```APIDOC
## RLM Initialization and Completion

### Description
Initializes an RLM instance with a specified backend and configuration, then uses it to generate a completion for a given prompt. The structure of the result, including the final response, usage summary, and execution time, is also shown.

### Method
```python
RLM(backend: str, backend_kwargs: dict, max_depth: int = 1, depth: int = 0, max_iterations: int = 30, max_timeout: float, max_budget: float, max_tokens: int, max_errors: int, environment: str = "local", environment_kwargs: dict, logger: RLMLogger | None, verbose: bool, persistent: bool, compaction: bool, custom_tools: list | None, custom_sub_tools: list | None, other_backends: list | None, sampling_args: dict | None, custom_system_prompt: str | None, **kwargs)
```

### Endpoint
N/A (Python Library)

### Parameters
#### Constructor Parameters (Essential):
- `backend` (str): LM provider (e.g., "openai", "anthropic", "gemini").
- `backend_kwargs` (dict): Provider configuration (e.g., model_name, api_key).

#### Constructor Parameters (Control Recursion):
- `max_depth` (int): How deep RLM can recurse (default 1 = no sub-RLMs).
- `depth` (int): Current depth (0 for root, set by parent).

#### Constructor Parameters (Iteration Limits):
- `max_iterations` (int): Max steps per completion (default 30).
- `max_timeout` (float): Seconds limit.
- `max_budget` (float): USD cost limit.
- `max_tokens` (int): Token count limit.
- `max_errors` (int): Consecutive error limit.

#### Constructor Parameters (Environment):
- `environment` (str): REPL type (default "local").
- `environment_kwargs` (dict): Environment config.

#### Constructor Parameters (Features):
- `logger` (RLMLogger | None): RLMLogger for trajectory capture.
- `verbose` (bool): Console output with rich.
- `persistent` (bool): Reuse environment across calls.
- `compaction` (bool): Summarize context when it grows.
- `custom_tools` (list | None): Functions/data in REPL.
- `custom_sub_tools` (list | None): Tools for sub-calls.

#### Constructor Parameters (Advanced):
- `other_backends` (list | None): Alternative backends for sub-calls.
- `sampling_args` (dict | None): Model parameters (temperature, top_p, etc.).
- `custom_system_prompt` (str | None): Override system prompt.
- Callbacks: `on_iteration_complete`, `on_subcall_start`, etc.

#### Method Parameters:
- `prompt` (str | dict): The input prompt for the language model.
- `root_prompt` (str | None): Optional root prompt for context.

### Request Example
```python
from rlm import RLM

rlm = RLM(backend="openai", backend_kwargs={"model_name": "gpt-3.5-turbo"})
result = rlm.completion(prompt="What is the capital of France?")
```

### Response
#### Success Response
- `result.response` (str): The final answer.
- `result.usage_summary` (UsageSummary): Tokens and cost summary.
- `result.execution_time` (float): Seconds taken for completion.
- `result.metadata` (dict | None): Full trajectory if logger was used.
- `result.root_model` (str): The name of the root model used.

#### Response Example
```json
{
  "response": "The capital of France is Paris.",
  "usage_summary": {
    "tokens_prompt": 10,
    "tokens_completion": 8,
    "tokens_total": 18,
    "cost_prompt": 0.00001,
    "cost_completion": 0.000008,
    "cost_total": 0.000018
  },
  "execution_time": 1.5,
  "metadata": { ... },
  "root_model": "gpt-3.5-turbo"
}
```
```

--------------------------------

### Configure Prime, Daytona, E2B Environments

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/7-configuration.md

Initialize an empty dictionary for environment_kwargs for Prime, Daytona, or E2B environments, as no custom configuration is currently available.

```python
environment_kwargs = {}  # No custom config currently
```

--------------------------------

### Catch ErrorThresholdExceededError

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/3-errors.md

Example of catching and handling ErrorThresholdExceededError to report error counts and details.

```python
from rlm import ErrorThresholdExceededError

try:
    result = rlm.completion(prompt, max_errors=3)
except ErrorThresholdExceededError as e:
    print(f"Too many errors: {e.error_count} consecutive (limit: {e.threshold})")
    print(f"Last error: {e.last_error}")
    if e.partial_answer:
        print(f"Partial result: {e.partial_answer}")
    else:
        print("No result computed before errors")
```

--------------------------------

### Initialize RLM with Modal Environment

Source: https://github.com/alexzhang13/rlm/blob/main/docs/getting-started.md

Configure RLM to use Modal's cloud sandboxes for fully isolated execution. Requires a Modal account.

```python
rlm = RLM(
    backend="openai",
    backend_kwargs={"model_name": "gpt-4o"},
    environment="modal",
    environment_kwargs={
        "app_name": "my-rlm-app",
        "timeout": 600,
    },
)
```

--------------------------------

### Exception Handling

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/0-index.md

Details the custom exceptions raised by the RLM library and provides examples of how to catch and handle them.

```APIDOC
## Exception Handling

### Description
The RLM library defines several custom exceptions to handle specific error conditions such as timeouts, budget exceeded, token limits, and error thresholds. This section provides examples of how to catch these exceptions and access relevant information.

### Exceptions
- `BudgetExceededError`: Raised when the maximum budget is exceeded.
- `TimeoutExceededError`: Raised when the maximum timeout is exceeded.
- `TokenLimitExceededError`: Raised when the maximum token limit is exceeded.
- `ErrorThresholdExceededError`: Raised when the maximum number of consecutive errors is exceeded.
- `CancellationError`: Raised when the operation is cancelled by the user.

### Request Example
```python
from rlm import RLM
from rlm.exceptions import TimeoutExceededError, BudgetExceededError, TokenLimitExceededError, ErrorThresholdExceededError, CancellationError

try:
    rlm = RLM(max_timeout=10, max_budget=5.0, max_tokens=1000)
    result = rlm.completion(prompt="Solve a complex problem.")
except TimeoutExceededError as e:
    print(f"Operation timed out. Partial answer: {e.partial_answer}")
except BudgetExceededError as e:
    print(f"Budget exceeded. Spent ${e.spent:.2f} of ${e.budget:.2f}")
except TokenLimitExceededError as e:
    print(f"Token limit exceeded. Used {e.tokens_used:,} of {e.token_limit:,} tokens")
except ErrorThresholdExceededError as e:
    print(f"Error threshold exceeded. Errors: {e.error_count}, Last error: {e.last_error}")
except CancellationError:
    print("Operation was cancelled by the user.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")
```

### Response
- When an exception is caught, the corresponding `except` block is executed, allowing for specific error handling. For example, `TimeoutExceededError` provides access to `partial_answer`, `BudgetExceededError` provides `spent` and `budget`, and `TokenLimitExceededError` provides `tokens_used` and `token_limit`.
```

--------------------------------

### Initialize RLM with Portkey Backend

Source: https://github.com/alexzhang13/rlm/blob/main/docs/getting-started.md

Integrate RLM with Portkey as a router. Use Portkey's API key and specify models using their format.

```python
rlm = RLM(
    backend="portkey",
    backend_kwargs={
        "api_key": os.getenv("PORTKEY_API_KEY"),
        "model_name": "@openai/gpt-5-nano",  # Portkey model format
    },
)
```

--------------------------------

### Initialize Google Gemini Client

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/6-clients.md

Set up the RLM client for Google's Generative AI models. Key parameters include 'model_name', 'api_key', and 'sampling_args'.

```python
from rlm import RLM

rlm = RLM(
    backend="gemini",
    backend_kwargs={
        "model_name": "gemini-2.0-flash",
        "api_key": "AIzaSy...",
        "timeout": 300.0,
        "sampling_args": {
            "temperature": 0.7,
            "top_p": 0.9,
        },
    }
)
```

--------------------------------

### Catch CancellationError

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/3-errors.md

Example of catching CancellationError to inform the user about execution cancellation and display partial results if available.

```python
from rlm import CancellationError

try:
    result = rlm.completion(prompt)
except CancellationError as e:
    print("Execution cancelled by user")
    if e.partial_answer:
        print(f"Partial answer: {e.partial_answer}")
```

--------------------------------

### Time-Constrained RLM Configuration

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/7-configuration.md

Configure RLM with a maximum timeout to limit execution time. This example sets a 30-second limit.

```python
rlm = RLM(
    max_timeout=30.0,  # 30 seconds
)
```

--------------------------------

### RLM Close Example

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/1-rlm-core-api.md

Illustrates the manual cleanup of an RLM environment after completing multi-turn conversations. This ensures resources are released.

```python
rlm = RLM(persistent=True, ...)

# Multi-turn conversation
result1 = rlm.completion("First question")
result2 = rlm.completion("Follow-up question")

# Clean up
rlm.close()
```

--------------------------------

### Set API Keys as Environment Variables

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/6-clients.md

Demonstrates how to set API keys for various services as environment variables. This is a common and recommended practice for managing credentials.

```bash
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export GOOGLE_API_KEY=AIzaSy...
```

--------------------------------

### RLM Initialization with Unknown Backend

Source: https://github.com/alexzhang13/rlm/blob/main/docs/api/rlm.md

Demonstrates an error scenario where RLM initialization fails due to specifying an unknown backend.

```python
# Unknown backend
rlm = RLM(backend="unknown")
```

--------------------------------

### Handle Child RLM BudgetExceededError

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/3-errors.md

Example of a parent RLM catching BudgetExceededError from a child RLM, including cumulative spending.

```python
# Parent RLM with budget tracking
parent_rlm = RLM(
    backend="openai",
    backend_kwargs={\"model_name\": \"gpt-4\"},
    max_depth=2,
    max_budget=10.0,  # $10 total
)

try:
    result = parent_rlm.completion("Complex task requiring sub-calls")
except BudgetExceededError as e:
    # Includes spending from child RLM calls
    print(f"Total spent (parent + children): ${e.spent:.2f}")
```

--------------------------------

### Import BaseLM and get_client

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/6-clients.md

Import the necessary components for language model client interactions.

```python
from rlm.clients import BaseLM, get_client
from rlm.core.types import ClientBackend
```

--------------------------------

### Development/Debugging RLM Configuration

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/7-configuration.md

Configure RLM for development with a specific model, local environment setup including pdb, and verbose logging.

```python
rlm = RLM(
    backend="openai",
    backend_kwargs={"model_name": "gpt-4o-mini", "api_key": "sk-..."},
    environment="local",
    environment_kwargs={"setup_code": "import pdb"},
    logger=RLMLogger(log_dir="./logs"),
    verbose=True,
)
```

--------------------------------

### Core RLM Initialization

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/7-configuration.md

Configure the primary backend, environment, recursion depth, and various iteration and execution limits for the RLM.

```python
rlm = RLM(
    # Model selection
    backend="openai",
    backend_kwargs={"model_name": "gpt-4", "api_key": "sk-..."},
    
    # Environment selection
    environment="local",
    environment_kwargs={},
    
    # Recursion depth
    depth=0,                          # Root RLM has depth=0
    max_depth=1,                      # Allow 1 level of recursion
    
    # Iteration limits
    max_iterations=30,                # Max iterations per completion
    
    # Execution limits
    max_budget=None,                  # USD limit
    max_timeout=None,                 # Seconds limit
    max_tokens=None,                  # Token limit
    max_errors=None,                  # Consecutive error limit
)
```

--------------------------------

### Search in Long Document with RLM

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/0-index.md

Example of using RLM for efficient searching within a large document by setting a maximum number of iterations.

```python
rlm = RLM(max_iterations=20)
result = rlm.completion("""
Find the answer to "What is X?" in this long document.
Use binary search or similar efficient strategies.

[Long document]
""")
```

--------------------------------

### Initialize Portkey Client

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/6-clients.md

Set up the RLM client to use Portkey for multi-model routing and failover. Requires 'model_name' and 'api_key'.

```python
from rlm import RLM

rlm = RLM(
    backend="portkey",
    backend_kwargs={
        "model_name": "gpt-4",
        "api_key": "portkey_...",
        "timeout": 300.0,
        "sampling_args": {
            "temperature": 0.7,
        },
    }
)
```

--------------------------------

### Anthropic Client Completion Example

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/6-clients.md

Perform a completion task using the configured Anthropic client. The 'max_depth' parameter can be set for recursive calls.

```python
rlm = RLM(
    backend="anthropic",
    backend_kwargs={
        "model_name": "claude-3-5-sonnet-20241022",
        "api_key": "sk-ant-...",
    },
    max_depth=2,
)
result = rlm.completion("Complex reasoning task...")
```

--------------------------------

### OpenRouter Client with Budget

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/6-clients.md

Initialize the OpenRouter client with a maximum budget. The client will track spending and raise a BudgetExceededError if the limit is reached.

```python
rlm = RLM(
    backend="openrouter",
    backend_kwargs={
        "model_name": "openai/gpt-4",
        "api_key": "sk-or-...",
    },
    max_budget=5.0,  # $5 limit - OpenRouter accurately tracks
)

try:
    result = rlm.completion(prompt)
except BudgetExceededError as e:
    print(f"Spent: ${e.spent:.2f}, Limit: ${e.budget:.2f}")
```

--------------------------------

### Initialize RLM with Docker Environment

Source: https://github.com/alexzhang13/rlm/blob/main/docs/getting-started.md

Set up RLM to execute code within a Docker container for enhanced isolation. Ensure Docker is installed and running.

```python
rlm = RLM(
    backend="openai",
    backend_kwargs={"model_name": "gpt-4o"},
    environment="docker",
    environment_kwargs={
        "image": "python:3.11-slim",  # Custom image
    },
)
```

--------------------------------

### Initialize RLM with vLLM Backend

Source: https://github.com/alexzhang13/rlm/blob/main/docs/getting-started.md

Configure RLM to connect to a local vLLM inference server. Ensure the server is running and accessible at the specified base URL.

```python
rlm = RLM(
    backend="vllm",
    backend_kwargs={
        "base_url": "http://localhost:8000/v1",  # Required
        "model_name": "meta-llama/Llama-3-70b",
    },
)
```

--------------------------------

### Configure Daytona Environment for RLM

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/5-environments.md

Initialize RLM to utilize Daytona's cloud sandbox environment. Similar to Prime Intellect, no custom configuration options are detailed for environment_kwargs.

```python
from rlm import RLM

rlm = RLM(
    environment="daytona",
    environment_kwargs={},
)
```

--------------------------------

### Configure Local REPL Environment

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/7-configuration.md

Define environment_kwargs for a local REPL, including optional setup code, persistence, compaction, and max concurrent subcalls.

```python
environment_kwargs = {
    "setup_code": "import numpy as np\nimport pandas as pd",  # Optional
    "persistent": False,                        # Multi-turn persistence
    "compaction": False,                        # History compaction
    "max_concurrent_subcalls": 4,               # For batched calls
}
```

--------------------------------

### Integrating RLM with FastAPI

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/8-advanced-topics.md

Example of integrating RLM into a FastAPI web application. The RLM instance is initialized with `persistent=True` to be shared across multiple requests.

```python
# FastAPI
from fastapi import FastAPI
from rlm import RLM

app = FastAPI()
rlm = RLM(persistent=True)  # Share across requests

@app.post("/solve")
async def solve(question: str):
    result = rlm.completion(question)
    return {"answer": result.response}
```

--------------------------------

### Initialize RLM with OpenAI Backend

Source: https://github.com/alexzhang13/rlm/blob/main/docs/getting-started.md

Connect RLM to the OpenAI API. Ensure your OPENAI_API_KEY is set in your environment variables.

```python
rlm = RLM(
    backend="openai",
    backend_kwargs={
        "api_key": os.getenv("OPENAI_API_KEY"),
        "model_name": "gpt-4o",
        # Optional: custom base URL
        # "base_url": "https://api.openai.com/v1",
    },
)
```

--------------------------------

### Initialize RLM with Environment

Source: https://github.com/alexzhang13/rlm/blob/main/README.md

Initialize the RLM with a specified REPL environment and its associated keyword arguments. The environment can be one of the supported types like 'local', 'ipython', 'docker', 'modal', 'prime', 'daytona', or 'e2b'.

```python
rlm = RLM(
    environment="...", # "local", "ipython", "docker", "modal", "prime", "daytona", "e2b"
    environment_kwargs={...},
)
```

--------------------------------

### Set Up API Keys for RLM

Source: https://github.com/alexzhang13/rlm/blob/main/docs/getting-started.md

Creates a .env file in your project root to store API keys for LLM providers like OpenAI and Anthropic. These keys are loaded using dotenv.

```bash
# .env
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
PORTKEY_API_KEY=...
```

--------------------------------

### Configure Backend Keyword Arguments

Source: https://github.com/alexzhang13/rlm/blob/main/docs/api/rlm.md

Provide specific configuration details to the LM client, such as API keys, model names, and base URLs. Required fields depend on the chosen backend.

```python
backend_kwargs = {
    "api_key": "sk-...",
    "model_name": "gpt-4o",
    "base_url": "https://api.openai.com/v1",  # Optional
}
```

--------------------------------

### Get the full trajectory data

Source: https://github.com/alexzhang13/rlm/blob/main/_autodocs/4-logger-api.md

The get_trajectory method retrieves the complete run metadata and all logged iterations for the current completion. Returns None if no metadata has been logged.

```python
logger = RLMLogger()
rlm = RLM(logger=logger, verbose=True)
result = rlm.completion(prompt)

# Access full trajectory
trajectory = logger.get_trajectory()
print(f"Iterations: {len(trajectory['iterations'])}")
for i, iteration in enumerate(trajectory['iterations']):
    print(f"Iteration {i+1}: {iteration['iteration_time']:.2f}s")

# Also attached to result
print(f"Same trajectory in result.metadata: {result.metadata == trajectory}")
```

--------------------------------

### Basic RLM Completion Call

Source: https://github.com/alexzhang13/rlm/blob/main/docs/getting-started.md

Demonstrates how to initialize the RLM with an OpenAI backend and make a completion call. Ensure your API key is set in the .env file.

```python
import os
from dotenv import load_dotenv
from rlm import RLM

load_dotenv()

# Create RLM instance
rlm = RLM(
    backend="openai",
    backend_kwargs={
        "api_key": os.getenv("OPENAI_API_KEY"),
        "model_name": "gpt-4o",
    },
)

# Make a completion call
result = rlm.completion("Calculate the 50th Fibonacci number using Python.")
print(result.response)
```