How to Get Started with RLM: Examples, Tutorials, and Quick-Start Guide

Yes, the alexzhang13/rlm repository provides a comprehensive quick-start script, nine standalone example files, and detailed markdown documentation covering everything from basic client initialization to advanced sandboxed execution.

Recursive Language Models (RLM) provide a flexible inference engine that enables language models to interact with REPL environments, make sub-LM calls, and handle arbitrarily long contexts. The repository ships with complete RLM examples and tutorials that demonstrate how to use the RLM client, configure REPL environments, and log execution trajectories for visualization.

Core Architecture Components

Understanding the codebase structure helps navigate the examples effectively. The repository implements four primary components:

1. RLM client – Located in rlm/core/rlm.py, this wraps language-model providers (e.g., OpenAI, Anthropic) and replaces standard completion calls with rlm.completion(prompt). It tracks usage and returns an RLMChatCompletion object containing trajectory metadata.

2. REPL environments – Defined in rlm/environments/base_env.py, these provide either non-isolated execution (LocalREPL) or isolated sandboxes (Docker, Modal, Prime). They inject helper globals including llm_query, rlm_query, context, answer, and SHOW_VARS that generated code can invoke.

3. LM-handler server – Implemented in rlm/core/lm_handler.py, this multi-threaded TCP server receives JSON-encoded requests from REPLs and forwards them to the appropriate client, enabling sub-calls to be routed back to the host.

4. Logging and visualization – The RLMLogger class in rlm/logger/rlm_logger.py records entire call graphs to JSONL files for replay in the visualizer tool.

Quick-Start Example

The fastest way to begin is with examples/quickstart.py, which demonstrates minimal client creation and a single completion call. After installing the package (pip install rlms) and configuring your API key, you can run:

from rlm import RLM

# Initialize the RLM client

rlm = RLM()

# Execute a simple completion

response = rlm.completion("What is the capital of France?")
print(response)

This script showcases basic client instantiation from rlm/core/rlm.py and optional logging configuration.

Complete List of RLM Examples

The repository includes nine standalone scripts in the examples/ directory, each targeting specific use cases:

Basic Usage

• examples/quickstart.py – Minimal end-to-end run showing client creation and completion calls.
• examples/lm_in_repl.py – Demonstrates how the model can call llm_query inside generated Python code using the default LocalREPL.

REPL Environment Variants

• examples/docker_repl_example.py – Launches a sandboxed Docker container using DockerREPL for safe code execution.
• examples/modal_repl_example.py – Runs in a Modal sandbox (requires modal SDK) demonstrating the HTTP-broker pattern.
• examples/prime_repl_example.py – Executes in a Prime sandbox (requires prime extra) using Prime's sandbox API.

Advanced Patterns

• examples/rlm_query_batched_example.py – Shows efficient handling of multiple prompts via rlm_query_batched for parallel sub-calls.
• examples/custom_tools_example.py – Registers user-defined functions that the model can invoke, extending the REPL with domain-specific helpers.
• examples/depth_metadata_example.py – Retrieves full call-graph metadata after execution, useful for debugging recursion depth.
• examples/logger_example.py – Captures execution trajectories to disk using RLMLogger(log_dir="./logs") for later inspection with the visualizer.

Key Documentation Files

Beyond executable scripts, the repository provides written tutorials:

• docs/getting-started.md – Step-by-step installation, configuration, and first-run guide.
• docs/architecture.md – In-depth description of the REPL-LM-handler architecture and communication protocols.

Running the Examples

To execute any example:

1. Install the package: pip install rlms
2. Set required API keys (e.g., OPENAI_API_KEY)
3. Run the desired script: python examples/quickstart.py

For sandboxed examples (Docker, Modal, Prime), ensure the respective SDK and permissions are configured according to docs/getting-started.md.

Summary

• The quick-start script (examples/quickstart.py) provides the minimal code needed to initialize an RLM client and execute completions.
• Nine standalone examples cover local execution, Docker/Modal/Prime sandboxes, batched queries, custom tools, and trajectory logging.
• Core implementation resides in rlm/core/rlm.py for the client, rlm/core/lm_handler.py for the server, and rlm/environments/ for REPL implementations.
• Documentation in docs/getting-started.md and docs/architecture.md provides comprehensive setup and architectural guidance.
• The RLMLogger system enables full execution replay via the visualizer tool.

Frequently Asked Questions

Where can I find the RLM quick-start tutorial?

The primary quick-start tutorial is located at examples/quickstart.py in the repository root. This script demonstrates basic client initialization and a single completion call. Comprehensive written instructions are also available in docs/getting-started.md.

Do I need Docker to run the RLM examples?

No, Docker is only required for the sandboxed examples. You can run examples/quickstart.py, examples/lm_in_repl.py, and most other scripts using the LocalREPL environment, which executes code in your host process. Docker, Modal, and Prime sandboxes are optional for isolated execution.

How do I visualize the execution traces from RLM?

Use the RLMLogger class as demonstrated in examples/logger_example.py. Initialize it with RLMLogger(log_dir="./logs") to capture trajectories as JSONL files. Then navigate to the visualizer/ directory and run npm run dev to launch the web interface for replaying execution graphs.

Can I extend RLM with custom functions for the model to call?

Yes, the examples/custom_tools_example.py file demonstrates how to register user-defined functions that become available as tools within the REPL environment. These functions are injected alongside standard globals like llm_query and rlm_query, allowing the model to invoke your domain-specific logic during execution.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}