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

Contribute to the alexzhang13/rlm project by setting up a uv-based development environment, following the test-driven workflow defined in 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 to the socket-based dispatchers in 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 – Parses LM prompts and responses to handle recursive call detection.
• rlm/utils/rlm_utils.py – Provides high-level helpers for managing recursive LM invocations and depth tracking.
• 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 – Defines the abstract BaseLM class that all LLM integrations must extend.
• rlm/environments/local_repl.py – Provides a non-isolated REPL implementation used for local development and testing.
• 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 – Verifies basic REPL behavior and tool integration.
• tests/test_rlm_query.py – Tests recursive calling logic and depth metadata propagation.
• 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:

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.

5. Update documentation if you modify public APIs. Edit README.md or files in docs/ to reflect interface changes.

6. Run the full test suite to verify no regressions exist:

   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:

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:

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:

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 by importing AcmeClient and updating the __all__ list.

Running Verification Examples

Validate your environment by executing the quickstart demonstration:

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 and 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.

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