# alexzhang13/rlm architecture

> Architecture diagram of the GitHub repository alexzhang13/rlm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alexzhang13/rlm
- Repository: https://github.com/alexzhang13/rlm

## Overview

#### Purpose and Public Entry Points
This is a Python RLM library: it wraps API/local language models in a recursive execution harness, allowing a root model to inspect offloaded context in a Python REPL and invoke LM or nested RLM calls. Public imports originate at `rlm/__init__.py`; the principal orchestration API is `rlm/core/rlm.py`. Examples such as `examples/quickstart.py` and `examples/rlm_query_batched_example.py` demonstrate application integration.

#### RLM Orchestrator and Completion Lifecycle
`RLM` constructs a model backend plus execution environment, then drives `completion()` iterations. It supplies the prompt/context/history to the environment, accepts generated code, executes it, feeds observations back to the root LM, and terminates with an `RLMChatCompletion`-style result and optional trajectory metadata.
- `rlm/core/rlm.py`
- `rlm/core/types.py`
- `rlm/core/lm_handler.py`

#### LM Abstraction and Recursive Dispatch
The LM handler mediates root and subcalls, including batched calls and concurrency/depth constraints. REPL-visible functions such as single/batched LM queries and recursive RLM queries route from generated code back through host-side orchestration, a necessary boundary for isolated environments. Provider adapters normalize provider-specific API behavior behind the base interface.
- `rlm/core/comms_utils.py`
- `rlm/clients/base_lm.py`
- `rlm/clients/openai.py`

Supported external model services include OpenAI/Azure OpenAI, Anthropic, Gemini, and Portkey/OpenRouter-style routing; local vLLM is accessed through the OpenAI-compatible client.
- `rlm/clients/anthropic.py`
- `rlm/clients/gemini.py`
- `rlm/clients/portkey.py`

#### REPL Execution and Isolation Boundary
Environment implementations execute model-authored Python against context and tools. `LocalREPL` is the default same-process `exec` environment; IPython can run in process or a kernel subprocess. Persistent sessions retain versioned context/history between completions, while compaction summarizes running history. This is the main trust boundary: local execution shares host dependencies and is unsuitable for untrusted production inputs.
- `rlm/environments/base_env.py`
- `rlm/environments/local_repl.py`
- `rlm/environments/ipython_repl.py`

Container/cloud implementations isolate code but proxy recursive LM requests to the host. Docker requires a Docker runtime; Modal, Prime, Daytona, and E2B rely on their corresponding sandbox services/SDKs.
- `rlm/environments/docker_repl.py`
- `rlm/environments/modal_repl.py`
- `rlm/environments/prime_repl.py`

#### Prompts, Parsing, and Execution Contracts
Core utility modules define system prompts, parse model outputs into executable actions/results, count or manage tokens, and centralize domain exceptions. These form the contract between model text generation, REPL execution, and the iterative controller.
- `rlm/utils/prompts.py`
- `rlm/utils/parsing.py`
- `rlm/utils/token_utils.py`

#### Observability and Trajectory Visualization
The logger records configuration, root iterations, code execution, and nested calls as in-memory metadata and optionally JSONL files. A separate Next.js visualizer ingests these logs client-side and presents execution, trajectory, iteration, and aggregate views.
- `rlm/logger/rlm_logger.py`
- `visualizer/src/lib/parse-logs.ts`
- `visualizer/src/components/Dashboard.tsx`

#### Training Subproject
`training/` is an intentionally separate Python package integrating RLM execution with `verifiers` and Prime Intellect `prime-rl`. It exposes an RLM-backed task environment, uses subprocess-isolated local REPL execution, and defines workers, proxying, scoring rubrics, and configurable training jobs. OOLONG is the worked long-context QA environment.
- `training/src/rlm_train/env.py`
- `training/src/rlm_train/worker.py`
- `training/environments/oolong/oolong/env.py`

#### Documentation and Delivery
The distributable Python package is defined by `pyproject.toml` and targets Python 3.11+. Documentation is a separate Next.js site, while GitHub Actions publish the package and deploy/check docs. The docs and visualizer are supporting Node.js applications, not runtime dependencies of inference.
- `pyproject.toml`
- `docs/src/app/page.tsx`
- `.github/workflows/publish.yml`

Main entry points: [`rlm/core/rlm.py`](https://github.com/alexzhang13/rlm/blob/main/rlm/core/rlm.py) (RLM orchestrator), [`rlm/environments/base_env.py`](https://github.com/alexzhang13/rlm/blob/main/rlm/environments/base_env.py) (Environment interface), [`rlm/clients/base_lm.py`](https://github.com/alexzhang13/rlm/blob/main/rlm/clients/base_lm.py) (Base LM interface), [`rlm/core/lm_handler.py`](https://github.com/alexzhang13/rlm/blob/main/rlm/core/lm_handler.py) (LM handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["RLM Runtime"]
  node_public_api["Public API<br/>Python package exports<br/>[__init__.py]"]
  node_rlm["RLM orchestrator<br/>completion controller<br/>[rlm.py]"]
  node_types["Completion types<br/>result contracts<br/>[types.py]"]
  node_lm_handler["LM handler<br/>recursive dispatch<br/>[lm_handler.py]"]
  node_prompts_parsing["Prompt &amp; parsing contract<br/>runtime utilities<br/>[parsing.py]"]
  node_token_utils["Token management<br/>runtime utility<br/>[token_utils.py]"]
  node_comms["REPL-host bridge<br/>callback boundary<br/>[comms_utils.py]"]
end

subgraph group_execution["Execution Environments"]
  node_base_env["Environment interface<br/>execution contract<br/>[base_env.py]"]
  node_local_repl["Local REPL<br/>same-process executor<br/>[local_repl.py]"]
  node_ipython_repl["IPython REPL<br/>kernel executor<br/>[ipython_repl.py]"]
  node_isolated_repls["Container &amp; cloud REPLs<br/>isolated executors<br/>[docker_repl.py]"]
end

subgraph group_clients["Model Providers"]
  node_base_lm["Base LM interface<br/>provider abstraction<br/>[base_lm.py]"]
  node_openai["OpenAI-compatible client<br/>provider adapter<br/>[openai.py]"]
  node_other_providers["Other provider adapters<br/>[anthropic.py]"]
end

subgraph group_support["Observability &amp; Tools"]
  node_logger[("RLM logger<br/>trajectory recorder<br/>[rlm_logger.py]")]
  node_visualizer["Trajectory visualizer<br/>Next.js application<br/>[Dashboard.tsx]"]
  node_distribution["Package distribution<br/>Python package metadata<br/>[pyproject.toml]"]
  node_docs["Documentation site<br/>Next.js application<br/>[page.tsx]"]
  node_publish["Publish workflow<br/>GitHub Actions<br/>[publish.yml]"]
end

subgraph group_training["Training Package"]
  node_training_env["RLM training environment<br/>training task runtime<br/>[env.py]"]
  node_training_worker["Training workers<br/>job workers<br/>[worker.py]"]
  node_oolong["OOLONG environment<br/>long-context QA task<br/>[env.py]"]
end

node_public_api -->|"exports"| node_rlm
node_rlm -->|"dispatches calls"| node_lm_handler
node_rlm -->|"runs generated code"| node_base_env
node_rlm -->|"builds and parses loop"| node_prompts_parsing
node_rlm -->|"manages context"| node_token_utils
node_rlm -->|"returns"| node_types
node_rlm -->|"records trajectory"| node_logger
node_base_env -->|"implemented by"| node_local_repl
node_base_env -->|"implemented by"| node_ipython_repl
node_base_env -->|"implemented by"| node_isolated_repls
node_base_env -->|"exposes callbacks"| node_comms
node_comms -->|"host-side recursive calls"| node_lm_handler
node_lm_handler -->|"uses"| node_base_lm
node_base_lm -->|"implemented by"| node_openai
node_base_lm -->|"implemented by"| node_other_providers
node_logger -->|"JSONL logs ingested by"| node_visualizer
node_training_env -->|"executes with"| node_rlm
node_training_worker -->|"runs jobs"| node_training_env
node_oolong -->|"task environment"| node_training_env
node_distribution -->|"packages"| node_public_api
node_publish -->|"publishes"| node_distribution
node_publish -->|"deploys/checks"| node_docs

click node_public_api "https://github.com/alexzhang13/rlm/blob/main/rlm/__init__.py"
click node_rlm "https://github.com/alexzhang13/rlm/blob/main/rlm/core/rlm.py"
click node_types "https://github.com/alexzhang13/rlm/blob/main/rlm/core/types.py"
click node_lm_handler "https://github.com/alexzhang13/rlm/blob/main/rlm/core/lm_handler.py"
click node_prompts_parsing "https://github.com/alexzhang13/rlm/blob/main/rlm/utils/parsing.py"
click node_token_utils "https://github.com/alexzhang13/rlm/blob/main/rlm/utils/token_utils.py"
click node_base_env "https://github.com/alexzhang13/rlm/blob/main/rlm/environments/base_env.py"
click node_local_repl "https://github.com/alexzhang13/rlm/blob/main/rlm/environments/local_repl.py"
click node_ipython_repl "https://github.com/alexzhang13/rlm/blob/main/rlm/environments/ipython_repl.py"
click node_isolated_repls "https://github.com/alexzhang13/rlm/blob/main/rlm/environments/docker_repl.py"
click node_comms "https://github.com/alexzhang13/rlm/blob/main/rlm/core/comms_utils.py"
click node_base_lm "https://github.com/alexzhang13/rlm/blob/main/rlm/clients/base_lm.py"
click node_openai "https://github.com/alexzhang13/rlm/blob/main/rlm/clients/openai.py"
click node_other_providers "https://github.com/alexzhang13/rlm/blob/main/rlm/clients/anthropic.py"
click node_logger "https://github.com/alexzhang13/rlm/blob/main/rlm/logger/rlm_logger.py"
click node_visualizer "https://github.com/alexzhang13/rlm/blob/main/visualizer/src/components/Dashboard.tsx"
click node_training_env "https://github.com/alexzhang13/rlm/blob/main/training/src/rlm_train/env.py"
click node_training_worker "https://github.com/alexzhang13/rlm/blob/main/training/src/rlm_train/worker.py"
click node_oolong "https://github.com/alexzhang13/rlm/blob/main/training/environments/oolong/oolong/env.py"
click node_distribution "https://github.com/alexzhang13/rlm/blob/main/pyproject.toml"
click node_docs "https://github.com/alexzhang13/rlm/blob/main/docs/src/app/page.tsx"
click node_publish "https://github.com/alexzhang13/rlm/blob/main/.github/workflows/publish.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_public_api,node_rlm,node_types,node_lm_handler,node_prompts_parsing,node_token_utils,node_comms toneBlue
class node_base_env,node_local_repl,node_ipython_repl,node_isolated_repls toneAmber
class node_base_lm,node_openai,node_other_providers toneMint
class node_logger,node_visualizer,node_distribution,node_docs,node_publish toneRose
class node_training_env,node_training_worker,node_oolong toneIndigo
```

## Components

### RLM Runtime

Iterative recursive model execution.

- [Public API](https://github.com/alexzhang13/rlm/blob/main/rlm/__init__.py): Python package exports · `rlm/__init__.py`
- [RLM orchestrator](https://github.com/alexzhang13/rlm/blob/main/rlm/core/rlm.py): completion controller · Builds runtime and drives completion iterations. · `rlm/core/rlm.py`
- [Completion types](https://github.com/alexzhang13/rlm/blob/main/rlm/core/types.py): result contracts · `rlm/core/types.py`
- [LM handler](https://github.com/alexzhang13/rlm/blob/main/rlm/core/lm_handler.py): recursive dispatch · Enforces batching, concurrency, and recursion depth. · `rlm/core/lm_handler.py`
- [Prompt & parsing contract](https://github.com/alexzhang13/rlm/blob/main/rlm/utils/parsing.py): runtime utilities · Turns model output into executable actions and results. · `rlm/utils/parsing.py`
- [Token management](https://github.com/alexzhang13/rlm/blob/main/rlm/utils/token_utils.py): runtime utility · `rlm/utils/token_utils.py`
- [REPL-host bridge](https://github.com/alexzhang13/rlm/blob/main/rlm/core/comms_utils.py): callback boundary · Routes REPL-visible LM and nested-RLM calls to the host. · `rlm/core/comms_utils.py`

### Execution Environments

Model-authored code execution boundary.

- [Environment interface](https://github.com/alexzhang13/rlm/blob/main/rlm/environments/base_env.py): execution contract · `rlm/environments/base_env.py`
- [Local REPL](https://github.com/alexzhang13/rlm/blob/main/rlm/environments/local_repl.py): same-process executor · Default exec environment; not safe for untrusted code. · `rlm/environments/local_repl.py`
- [IPython REPL](https://github.com/alexzhang13/rlm/blob/main/rlm/environments/ipython_repl.py): kernel executor · Runs in-process or in a kernel subprocess. · `rlm/environments/ipython_repl.py`
- [Container & cloud REPLs](https://github.com/alexzhang13/rlm/blob/main/rlm/environments/docker_repl.py): isolated executors · Proxy recursive LM requests back to the host. · `rlm/environments/docker_repl.py`

### Model Providers

Normalized external model access.

- [Base LM interface](https://github.com/alexzhang13/rlm/blob/main/rlm/clients/base_lm.py): provider abstraction · `rlm/clients/base_lm.py`
- [OpenAI-compatible client](https://github.com/alexzhang13/rlm/blob/main/rlm/clients/openai.py): provider adapter · Also supports Azure and local vLLM endpoints. · `rlm/clients/openai.py`
- [Other provider adapters](https://github.com/alexzhang13/rlm/blob/main/rlm/clients/anthropic.py): provider adapters · Anthropic, Gemini, and Portkey/OpenRouter routing. · `rlm/clients/anthropic.py`

### Observability & Tools

- [RLM logger](https://github.com/alexzhang13/rlm/blob/main/rlm/logger/rlm_logger.py): trajectory recorder · Captures iterations, execution, and nested calls in memory or JSONL. · `rlm/logger/rlm_logger.py`
- [Trajectory visualizer](https://github.com/alexzhang13/rlm/blob/main/visualizer/src/components/Dashboard.tsx): Next.js application · Client-side dashboard for logged trajectories. · `visualizer/src/components/Dashboard.tsx`
- [Package distribution](https://github.com/alexzhang13/rlm/blob/main/pyproject.toml): Python package metadata · Targets Python 3.11+. · `pyproject.toml`
- [Documentation site](https://github.com/alexzhang13/rlm/blob/main/docs/src/app/page.tsx): Next.js application · Separate from inference runtime. · `docs/src/app/page.tsx`
- [Publish workflow](https://github.com/alexzhang13/rlm/blob/main/.github/workflows/publish.yml): GitHub Actions · Publishes package and deploys/checks docs. · `.github/workflows/publish.yml`

### Training Package

Separate RLM training integration.

- [RLM training environment](https://github.com/alexzhang13/rlm/blob/main/training/src/rlm_train/env.py): training task runtime · Integrates RLM execution with verifiers and prime-rl. · `training/src/rlm_train/env.py`
- [Training workers](https://github.com/alexzhang13/rlm/blob/main/training/src/rlm_train/worker.py): job workers · `training/src/rlm_train/worker.py`
- [OOLONG environment](https://github.com/alexzhang13/rlm/blob/main/training/environments/oolong/oolong/env.py): long-context QA task · `training/environments/oolong/oolong/env.py`

## Connections

- Public API → RLM orchestrator: exports
- RLM orchestrator → LM handler: dispatches calls
- RLM orchestrator → Environment interface: runs generated code
- RLM orchestrator → Prompt & parsing contract: builds and parses loop
- RLM orchestrator → Token management: manages context
- RLM orchestrator → Completion types: returns
- RLM orchestrator → RLM logger: records trajectory
- Environment interface → Local REPL: implemented by
- Environment interface → IPython REPL: implemented by
- Environment interface → Container & cloud REPLs: implemented by
- Environment interface → REPL-host bridge: exposes callbacks
- REPL-host bridge → LM handler: host-side recursive calls
- LM handler → Base LM interface: uses
- Base LM interface → OpenAI-compatible client: implemented by
- Base LM interface → Other provider adapters: implemented by
- RLM logger → Trajectory visualizer: JSONL logs ingested by
- RLM training environment → RLM orchestrator: executes with
- Training workers → RLM training environment: runs jobs
- OOLONG environment → RLM training environment: task environment
- Package distribution → Public API: packages
- Publish workflow → Package distribution: publishes
- Publish workflow → Documentation site: deploys/checks
