Metadata-Version: 2.4
Name: fleet-rlm
Version: 0.4.2
Summary: Recursive Language Models with DSPy + Modal for secure long-context code execution
Author: Qredence
License-Expression: MIT
Project-URL: Homepage, https://github.com/qredence/fleet-rlm
Project-URL: Repository, https://github.com/qredence/fleet-rlm
Project-URL: Issues, https://github.com/qredence/fleet-rlm/issues
Project-URL: Documentation, https://fleet-rlm.readthedocs.io/
Keywords: dspy,llm,modal,recursive-language-model,rlm,agents
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS.md
Requires-Dist: dspy==3.1.3
Requires-Dist: hydra-core<2,>=1.3
Requires-Dist: markitdown[all]<1,>=0.1.0
Requires-Dist: omegaconf<3,>=2.3
Requires-Dist: modal>=1.3.2
Requires-Dist: pypdf<7,>=6
Requires-Dist: pydantic<3,>=2.12.5
Requires-Dist: python-dotenv>=1.2.1
Requires-Dist: pyyaml<7,>=6.0.3
Requires-Dist: structlog<25,>=24.1.0
Requires-Dist: tomli>=2.0.0; python_version < "3.11"
Requires-Dist: typer<1,>=0.21.1
Provides-Extra: dev
Requires-Dist: pre-commit>=3.7; extra == "dev"
Requires-Dist: pytest>=8.2; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Requires-Dist: ty>=0.0.1a16; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.1; extra == "dev"
Provides-Extra: mcp
Requires-Dist: fastmcp<3,>=2.14.0; extra == "mcp"
Requires-Dist: httpx[socks]<1,>=0.28.1; extra == "mcp"
Requires-Dist: pydantic<3,>=2.12.5; extra == "mcp"
Provides-Extra: server
Requires-Dist: fastapi[standard]<1,>=0.115; extra == "server"
Requires-Dist: pydantic<3,>=2.12.5; extra == "server"
Requires-Dist: scalar-fastapi<2,>=1.5.0; extra == "server"
Requires-Dist: uvicorn[standard]<1,>=0.32; extra == "server"
Requires-Dist: websockets<16,>=14; extra == "server"
Provides-Extra: full
Requires-Dist: fastmcp<3,>=2.14.0; extra == "full"
Requires-Dist: httpx[socks]<1,>=0.28.1; extra == "full"
Requires-Dist: pydantic<3,>=2.12.5; extra == "full"
Requires-Dist: fastapi[standard]<1,>=0.115; extra == "full"
Requires-Dist: uvicorn[standard]<1,>=0.32; extra == "full"
Requires-Dist: scalar-fastapi<2,>=1.5.0; extra == "full"
Requires-Dist: websockets<16,>=14; extra == "full"
Dynamic: license-file

# fleet-rlm

[![PyPI version](https://img.shields.io/pypi/v/fleet-rlm.svg)](https://pypi.org/project/fleet-rlm/)
[![Python versions](https://img.shields.io/pypi/pyversions/fleet-rlm.svg)](https://pypi.org/project/fleet-rlm/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![CI](https://github.com/Qredence/fleet-rlm/actions/workflows/ci.yml/badge.svg)](https://github.com/Qredence/fleet-rlm/actions/workflows/ci.yml)

**Secure, cloud-sandboxed Recursive Language Models (RLM) with DSPy and Modal.**

`fleet-rlm` provides a production-ready implementation of **Recursive Language Modeling** aligned with the [DSPy RLM API](https://dspy.ai/api/modules/RLM/). It gives your AI agent a secure "computer" in the cloud to read, search, and analyze massive datasets without local resource constraints.

[Paper](https://arxiv.org/abs/2501.123) | [Contributing](CONTRIBUTING.md) | [Docs](docs/)

---

## Architecture

```
User ─── CLI / API / WebSocket ─── RLMReActChatAgent (dspy.Module)
                                        │
                          ┌──────────────┼──────────────┐
                          │              │              │
                     load_document  rlm_query      edit_file
                     list_files     (recursive)    search_code
                     read_file_slice ...            ...
                          │              │
                          ▼              ▼
                   ModalInterpreter ── dspy.RLM
                          │              │
                          ▼              ▼
                   Modal Sandbox (isolated Python REPL)
                   ├── Persistent Volume (/data/)
                   ├── Execution Profiles (ROOT / DELEGATE / MAINTENANCE)
                   └── Session State (per workspace/user)
```

## Features

- **Interactive Agent**: `RLMReActChatAgent` (a `dspy.Module`) combines fast, interactive chat with deep, recursive task execution via `rlm_query`.
- **DSPy Aligned**: Implements `dspy.RLM`, `dspy.Module`, and `dspy.Tool` interfaces — compatible with DSPy optimizers (`BootstrapFewShot`, `MIPROv2`).
- **Secure Sandbox**: Code runs in isolated **Modal** containers with persistent storage volumes, execution profiles, and sensitive data redaction.
- **Recursive Delegation**: Large tasks are broken down via `rlm_query` sub-agents with depth enforcement to prevent infinite recursion.
- **PDF Ingestion**: Native document loading via MarkItDown with pypdf fallback; OCR guidance for scanned PDFs.
- **Session State**: Per-workspace, per-user session persistence with manifests stored on Modal volumes.
- **MCP Server**: Expose fleet-rlm capabilities as an MCP tool server via `serve-mcp`.
- **Observability**: Real-time streaming of thoughts, tool execution, trajectory normalization, and structured logging.

## Quick Start

### 1. Install

```bash
pip install fleet-rlm
```

Optional extras for server and MCP support:

```bash
pip install fleet-rlm[server]   # FastAPI server + WebSocket
pip install fleet-rlm[mcp]      # MCP server
pip install fleet-rlm[full]     # All extras
```

### 2. Configure

Set up your Modal and LLM credentials:

```bash
modal setup
modal volume create rlm-volume-dspy
modal secret create LITELLM DSPY_LM_MODEL=openai/gpt-4o DSPY_LLM_API_KEY=sk-...
```

### 3. Run

```bash
# Interactive chat (requires OpenTUI / Bun)
fleet-rlm code-chat --opentui

# One-shot task
fleet-rlm run-basic --question "What are the first 12 Fibonacci numbers?"

# Document analysis
fleet-rlm run-architecture --docs-path docs/architecture.md --query "Extract all components"

# API server (FastAPI + WebSocket)
fleet-rlm serve-api --port 8000

# MCP server
fleet-rlm serve-mcp --transport stdio
```

## Development Setup

```bash
# Clone and install
git clone https://github.com/qredence/fleet-rlm.git
cd fleet-rlm
uv sync --extra dev

# With server/MCP support
uv sync --extra dev --extra server --extra mcp

# Copy environment template
cp .env.example .env

# Quality gate
uv run ruff check src tests && uv run ty check src && uv run pytest -q
```

## Documentation

- [Concepts](docs/explanation/rlm-concepts.md) — Core architecture (Agent, RLM, Sandbox)
- [User Flows](docs/user_flows.md) — Interaction diagrams (Chat, Tools, Delegation)
- [Architecture](docs/explanation/architecture.md) — System components and hierarchy
- [Tutorials](docs/tutorials/index.md) — Step-by-step lessons
- [How-To Guides](docs/how-to-guides/index.md) — Installation, deployment, troubleshooting
- [CLI Reference](docs/reference/cli.md) — Full CLI command reference
- [HTTP API Reference](docs/reference/http-api.md) — Server endpoints and WebSocket protocol
- [Source Layout](docs/reference/source-layout.md) — Package structure guide

## Contributing

We welcome contributions! Please see our [Contribution Guide](CONTRIBUTING.md) and run the quality gate before submitting:

```bash
uv run ruff check src tests && uv run ty check src && uv run pytest -q
```

## License

MIT License — see [LICENSE](LICENSE).

Based on [Recursive Language Modeling](https://arxiv.org/abs/2501.123) research by **Alex L. Zhang** (MIT CSAIL), **Omar Khattab** (Stanford), and **Tim Kraska** (MIT).
