agentic-codebase-navigator 1.0.1

Agentic codebase navigator built on Recursive Language Model (RLM) patterns.

agentic-codebase-navigator

An agentic codebase navigator built on Recursive Language Model (RLM) patterns. RLM enables LLMs to execute Python code iteratively, inspect results, and refine their approach until reaching a final answer.

• PyPI / distribution name: agentic-codebase-navigator
• Python import package: rlm

Installation

Via pip

pip install agentic-codebase-navigator

Via uv (recommended)

uv pip install agentic-codebase-navigator

With optional LLM providers

# OpenAI (included by default)
pip install agentic-codebase-navigator

# Anthropic
pip install "agentic-codebase-navigator[llm-anthropic]"

# Google Gemini
pip install "agentic-codebase-navigator[llm-gemini]"

# Azure OpenAI
pip install "agentic-codebase-navigator[llm-azure-openai]"

# LiteLLM (unified provider)
pip install "agentic-codebase-navigator[llm-litellm]"

# Portkey
pip install "agentic-codebase-navigator[llm-portkey]"

Quick Start

Basic usage with OpenAI

from rlm import create_rlm
from rlm.adapters.llm import OpenAIAdapter

# Create RLM with OpenAI (requires OPENAI_API_KEY env var)
rlm = create_rlm(
    OpenAIAdapter(model="gpt-4o"),
    environment="local",
    max_iterations=10,
)

# Run a completion
result = rlm.completion("What is 2 + 2? Use Python to calculate.")
print(result.response)

Using MockLLM for testing (no API keys required)

from rlm import create_rlm
from rlm.adapters.llm import MockLLMAdapter

# Deterministic mock for testing
rlm = create_rlm(
    MockLLMAdapter(model="test", script=["```repl\nx = 42\n```\nFINAL_VAR('x')"]),
    environment="local",
    max_iterations=2,
)

result = rlm.completion("test prompt")
assert result.response == "42"

Execution Environments

RLM supports multiple execution environments for running Python code blocks:

Local Environment (default)

Executes code in-process with a persistent namespace. Fast and convenient for development.

rlm = create_rlm(
    llm,
    environment="local",
    environment_kwargs={
        "execute_timeout_s": 30.0,           # Execution timeout (SIGALRM-based)
        "broker_timeout_s": 60.0,            # Timeout for nested LLM calls
        "allowed_import_roots": {"json", "math", "collections"},  # Allowed imports
    },
)

Default allowed imports: collections, dataclasses, datetime, decimal, functools, itertools, json, math, pathlib, random, re, statistics, string, textwrap, typing, uuid

Docker Environment

Executes code in an isolated container. Recommended for untrusted code or production use.

rlm = create_rlm(
    llm,
    environment="docker",
    environment_kwargs={
        "image": "python:3.12-slim",         # Docker image
        "subprocess_timeout_s": 120.0,       # Container execution timeout
        "proxy_http_timeout_s": 60.0,        # HTTP proxy timeout for LLM calls
    },
)

Requirements:

• Docker daemon running (docker info succeeds)
• Docker 20.10+ (for --add-host host.docker.internal:host-gateway)

Multi-Backend Routing

RLM supports registering multiple LLM backends. Code blocks can route nested calls to specific models:

from rlm import create_rlm
from rlm.adapters.llm import MockLLMAdapter

# Root model generates code that calls a sub-model
root_script = """```repl\nresponse = llm_query("What is the capital of France?", model="sub")```\nFINAL_VAR('response')"""

rlm = create_rlm(
    MockLLMAdapter(model="root", script=[root_script]),
    other_llms=[MockLLMAdapter(model="sub", script=["Paris"])],
    environment="local",
    max_iterations=3,
)

result = rlm.completion("hello")
assert result.response == "Paris"

# Usage is aggregated across all models
print(result.usage_summary.model_usage_summaries["root"].total_calls)  # 1
print(result.usage_summary.model_usage_summaries["sub"].total_calls)   # 1

Batched LLM queries

For efficiency, code can batch multiple LLM calls:

# Inside a ```repl block:
responses = llm_query_batched([
    "Question 1",
    "Question 2",
    "Question 3",
], model="fast-model")

CLI Usage

# Show version
rlm --version

# Run a completion with mock backend (no API keys)
rlm completion "What is 2+2?" --backend mock --model-name test

# Run with OpenAI
rlm completion "Explain recursion" --backend openai --model-name gpt-4o

# Output full JSON response
rlm completion "Calculate pi" --backend mock --json

# Enable JSONL logging
rlm completion "Hello" --backend mock --jsonl-log-dir ./logs

Configuration-Driven Usage

For complex setups, use configuration objects:

from rlm import create_rlm_from_config, RLMConfig, LLMConfig, EnvironmentConfig

config = RLMConfig(
    llm=LLMConfig(backend="openai", model_name="gpt-4o"),
    other_llms=[
        LLMConfig(backend="anthropic", model_name="claude-3-5-sonnet-20241022"),
    ],
    env=EnvironmentConfig(environment="docker"),
    max_iterations=15,
    max_depth=1,
)

rlm = create_rlm_from_config(config)
result = rlm.completion("Solve this step by step...")

Async Support

import asyncio
from rlm import create_rlm
from rlm.adapters.llm import MockLLMAdapter

async def main():
    rlm = create_rlm(
        MockLLMAdapter(model="test", script=["FINAL('done')"]),
        environment="local",
    )
    result = await rlm.acompletion("async test")
    print(result.response)

asyncio.run(main())

LLM Provider Configuration

Provider	Extra	Environment Variables
OpenAI	(default)	OPENAI_API_KEY
Anthropic	llm-anthropic	ANTHROPIC_API_KEY
Google Gemini	llm-gemini	GOOGLE_API_KEY
Azure OpenAI	llm-azure-openai	AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT
LiteLLM	llm-litellm	(varies by provider)
Portkey	llm-portkey	PORTKEY_API_KEY

Architecture

RLM uses a hexagonal (ports & adapters) architecture:

src/rlm/
├── domain/          # Pure business logic, ports (protocols), models
├── application/     # Use cases, configuration
├── infrastructure/  # Wire protocol, execution policies
├── adapters/        # LLM providers, environments, broker, loggers
└── api/             # Public facade, factories, registries

Key design principles:

• Domain layer has zero external dependencies
• Adapters implement domain ports (protocols)
• Dependencies flow inward (adapters -> application -> domain)
• All LLM provider SDKs are lazy-imported (optional extras)

Development

Setup

# Clone and setup
git clone https://github.com/Luiz-Frias/agentic-codebase-navigator.git
cd agentic-codebase-navigator

# Create venv with Python 3.12
uv python install 3.12
uv venv --python 3.12 .venv
source .venv/bin/activate

# Install with dev dependencies
uv sync --group dev --group test

Running Tests

# Unit tests (fast, hermetic)
uv run --group test pytest -m unit

# Integration tests (multi-component boundaries)
uv run --group test pytest -m integration

# End-to-end tests (public API flows). Docker-marked tests auto-skip if Docker isn't available.
uv run --group test pytest -m e2e

# Packaging smoke tests (build/install/import/CLI)
uv run --group test pytest -m packaging

# Performance/regression tests (opt-in)
uv run --group test pytest -m performance

# All tests
uv run --group test pytest

# With coverage
uv run --group test pytest --cov=rlm --cov-report=term-missing

Live provider smoke tests (opt-in)

These tests are skipped by default to avoid accidental spend. Enable with RLM_RUN_LIVE_LLM_TESTS=1 and the relevant API key:

RLM_RUN_LIVE_LLM_TESTS=1 OPENAI_API_KEY=... uv run --group test pytest -m "integration and live_llm"
RLM_RUN_LIVE_LLM_TESTS=1 ANTHROPIC_API_KEY=... uv run --group test pytest -m "integration and live_llm"

Code Quality

# Format
uv run --group dev ruff format src tests

# Lint
uv run --group dev ruff check src tests --fix

# Type check
uv run --group dev ty check src/rlm

API Reference

Core Classes

• RLM - Main facade for running completions
• ChatCompletion - Result object with response, usage, iterations
• RLMConfig - Configuration dataclass for create_rlm_from_config

Factory Functions

• create_rlm(llm, ...) - Create RLM with pre-built LLM adapter
• create_rlm_from_config(config) - Create RLM from configuration object

Adapters

• LLM: MockLLMAdapter, OpenAIAdapter, AnthropicAdapter, GeminiAdapter, AzureOpenAIAdapter, LiteLLMAdapter, PortkeyAdapter
• Environment: LocalEnvironmentAdapter, DockerEnvironmentAdapter
• Logger: JsonlLoggerAdapter, ConsoleLoggerAdapter, NoopLoggerAdapter

Acknowledgments

This project is built upon the excellent Recursive Language Models (RLM) research by Alex Zhang and colleagues from MIT OASYS Lab.

Resource	Link
Original Repository	github.com/alexzhang13/rlm
Research Paper	arXiv:2512.24601
Authors	Alex L. Zhang, Tim Kraska, Omar Khattab

This repository refactors the original RLM implementation into a hexagonal/modular monolith architecture while maintaining API compatibility. See ATTRIBUTION.md for full details.

Citation

@misc{zhang2025recursivelanguagemodels,
      title={Recursive Language Models},
      author={Alex L. Zhang and Tim Kraska and Omar Khattab},
      year={2025},
      eprint={2512.24601},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2512.24601},
}

License

MIT License - see LICENSE for details.

• Original work: Copyright (c) 2025 Alex Zhang
• Refactored work: Copyright (c) 2026 Luiz Frias