# How to Contribute to the alexzhang13/rlm Project: A Complete Guide

> Learn how to contribute to the alexzhang13/rlm project. Follow our guide for setup, testing, and submitting pull requests for seamless collaboration.

- Repository: [az/rlm](https://github.com/alexzhang13/rlm)
- Tags: how-to-guide
- Published: 2026-06-18

---

**Contribute to the alexzhang13/rlm project by setting up a **uv**-based development environment, following the test-driven workflow defined in [`CONTRIBUTING.md`](https://github.com/alexzhang13/rlm/blob/main/CONTRIBUTING.md), and submitting pull requests that include passing unit tests and updated documentation.**

The **alexzhang13/rlm** (Recursive Language Models) repository is an open-source framework for building recursive LLM systems with isolated execution environments. Contributing to this project requires understanding its modular architecture—from the prompt parsing logic in [`rlm/utils/parsing.py`](https://github.com/alexzhang13/rlm/blob/main/rlm/utils/parsing.py) to the socket-based dispatchers in [`rlm/core/lm_handler.py`](https://github.com/alexzhang13/rlm/blob/main/rlm/core/lm_handler.py). This guide provides the exact steps to configure your workspace, adhere to codebase conventions, and submit high-quality contributions that align with the project's strict typing and testing standards.

## Project Architecture and Key Components

Understanding the repository structure is essential before you contribute to the alexzhang13/rlm project. The codebase is organized into distinct layers that handle everything from LLM client abstraction to sandboxed code execution.

### Core Library and Communication Utilities

The **core library** implements the recursive language model engine and inter-process communication. Key files include:

- **[`rlm/utils/parsing.py`](https://github.com/alexzhang13/rlm/blob/main/rlm/utils/parsing.py)** – Parses LM prompts and responses to handle recursive call detection.
- **[`rlm/utils/rlm_utils.py`](https://github.com/alexzhang13/rlm/blob/main/rlm/utils/rlm_utils.py)** – Provides high-level helpers for managing recursive LM invocations and depth tracking.
- **[`rlm/core/lm_handler.py`](https://github.com/alexzhang13/rlm/blob/main/rlm/core/lm_handler.py)** – Implements a multi-threaded TCP server that dispatches LM requests between environments.

### Clients and Execution Environments

The project abstracts LLM providers through a unified client interface and supports multiple execution backends:

- **[`rlm/clients/base_lm.py`](https://github.com/alexzhang13/rlm/blob/main/rlm/clients/base_lm.py)** – Defines the abstract `BaseLM` class that all LLM integrations must extend.
- **[`rlm/environments/local_repl.py`](https://github.com/alexzhang13/rlm/blob/main/rlm/environments/local_repl.py)** – Provides a non-isolated REPL implementation used for local development and testing.
- **[`rlm/environments/modal_repl.py`](https://github.com/alexzhang13/rlm/blob/main/rlm/environments/modal_repl.py)** – Implements an isolated sandbox using an HTTP broker pattern for secure code execution.

### Testing and Examples

Every contribution must maintain the existing test coverage patterns:

- **[`tests/test_local_repl.py`](https://github.com/alexzhang13/rlm/blob/main/tests/test_local_repl.py)** – Verifies basic REPL behavior and tool integration.
- **[`tests/test_rlm_query.py`](https://github.com/alexzhang13/rlm/blob/main/tests/test_rlm_query.py)** – Tests recursive calling logic and depth metadata propagation.
- **[`examples/quickstart.py`](https://github.com/alexzhang13/rlm/blob/main/examples/quickstart.py)** – Serves as a minimal entry point for verifying local setup.

## Setting Up the Development Environment

The alexzhang13/rlm project uses **uv** for dependency management and requires Python 3.12. Follow these exact steps to configure your local environment:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv --python 3.12
source .venv/bin/activate
uv pip install -e .[dev,test]
uv run pre-commit install

```

This installation sequence creates an isolated virtual environment, installs the core package with development and testing extras, and enables pre-commit hooks that enforce code quality checks automatically.

## Contribution Workflow

Follow this structured workflow to ensure your contribution meets the project's standards:

1. **Fork and clone** the repository from GitHub to your personal account.

2. **Create a feature branch** using conventional naming conventions:
   - `feature/add-custom-tool` for new functionality
   - `bugfix/fix-depth-metadata` for bug corrections

3. **Implement changes** with strict typing and style compliance:
   - Add explicit type hints to all function signatures
   - Run `uv run ruff check --fix .` to lint your code
   - Run `uv run ruff format .` to apply automatic formatting

4. **Add or update unit tests** in the `tests/` directory. Every new feature must include tests that verify both success and error paths, following the patterns in [`tests/test_local_repl.py`](https://github.com/alexzhang13/rlm/blob/main/tests/test_local_repl.py).

5. **Update documentation** if you modify public APIs. Edit [`README.md`](https://github.com/alexzhang13/rlm/blob/main/README.md) or files in `docs/` to reflect interface changes.

6. **Run the full test suite** to verify no regressions exist:
   ```bash
   uv run pytest
   ```

7. **Commit and push** your branch to your fork. Do not commit directly to the `main` branch.

8. **Open a Pull Request** that includes:
   - A summary of the technical changes
   - References to related issues (e.g., `Closes #42`)
   - Confirmation that pre-commit checks and the full test suite pass

## Practical Contribution Examples

### Adding a Custom Tool to the REPL

To add a `SHOW_TIME()` utility that returns the current UTC time, modify [`rlm/environments/local_repl.py`](https://github.com/alexzhang13/rlm/blob/main/rlm/environments/local_repl.py):

```python
def _setup_globals(self) -> dict:
    globals_dict = super()._setup_globals()
    import datetime

    def SHOW_TIME():
        """Return current UTC time as an ISO-8601 string."""
        return datetime.datetime.utcnow().isoformat()

    globals_dict["SHOW_TIME"] = SHOW_TIME
    return globals_dict

```

Then create a corresponding test in [`tests/repl/test_custom_tools.py`](https://github.com/alexzhang13/rlm/blob/main/tests/repl/test_custom_tools.py):

```python
def test_show_time(local_repl):
    result = local_repl.run("print(SHOW_TIME())")
    assert "T" in result.stdout  # Verifies ISO format presence

```

### Implementing a New LM Client

To integrate a hypothetical "AcmeAI" service, create [`rlm/clients/acme.py`](https://github.com/alexzhang13/rlm/blob/main/rlm/clients/acme.py):

```python
from rlm.clients.base_lm import BaseLM
from rlm.core.types import ModelUsageSummary, UsageSummary

class AcmeClient(BaseLM):
    def __init__(self, api_key: str, model_name: str = "acme-1"):
        super().__init__(model_name=model_name)
        self.api_key = api_key

    def completion(self, prompt, model=None):
        # Implement HTTP request to Acme API

        # Parse response and return formatted output

        pass

```

Register the client in [`rlm/clients/__init__.py`](https://github.com/alexzhang13/rlm/blob/main/rlm/clients/__init__.py) by importing `AcmeClient` and updating the `__all__` list.

### Running Verification Examples

Validate your environment by executing the quickstart demonstration:

```bash
uv run python examples/quickstart.py

```

This script instantiates a `LocalREPL`, loads a test context, and executes sample prompts to verify that the recursive calling pipeline functions correctly.

## Summary

- **Use uv for environment management**: Install Python 3.12, create a virtual environment, and install dependencies with `uv pip install -e .[dev,test]`.
- **Follow the test-driven workflow**: All changes require corresponding unit tests in `tests/` and must pass `uv run pytest`.
- **Maintain strict code quality**: Enforce typing and style using **ruff** and **pre-commit** hooks before submitting.
- **Understand the architecture**: Contributions touch `rlm/utils/` for parsing, `rlm/clients/` for LLM integrations, and `rlm/environments/` for execution logic.
- **Reference CONTRIBUTING.md**: The repository contains detailed guidelines for branching strategies and review processes.

## Frequently Asked Questions

### What Python version is required to contribute to alexzhang13/rlm?

The project requires **Python 3.12**, specified when creating the virtual environment with `uv venv --python 3.12`. This ensures compatibility with the type hints and async patterns used throughout the codebase.

### How do I run the test suite before submitting a contribution?

Execute `uv run pytest` from the repository root after installing development dependencies. The test suite includes unit tests for REPL behavior, recursive query logic, and depth metadata handling as found in [`tests/test_local_repl.py`](https://github.com/alexzhang13/rlm/blob/main/tests/test_local_repl.py) and [`tests/test_depth_metadata.py`](https://github.com/alexzhang13/rlm/blob/main/tests/test_depth_metadata.py).

### Where should I add tests for new features?

All unit tests belong in the `tests/` directory, mirroring the structure of the main package. New features should include tests that verify API contracts, such as adding test files under `tests/repl/` for environment changes or `tests/clients/` for new LLM integrations.

### What code style standards does the project enforce?

The project uses **ruff** for both linting and formatting, configured to enforce strict typing rules. Pre-commit hooks automatically run these checks, but you can manually execute `uv run ruff check --fix .` and `uv run ruff format .` to ensure compliance before committing.