Metadata-Version: 2.4
Name: fleet-rlm
Version: 0.7.2
Summary: RLM-native FastAPI backend with DSPy and Daytona
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,daytona,recursive-language-model,rlm,agents
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS.md
Requires-Dist: dspy<3.4,>=3.3.0
Requires-Dist: packaging<27,>=24
Requires-Dist: daytona==0.202.0
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: alembic<2,>=1.18.5
Requires-Dist: asyncpg<1,>=0.31.0
Requires-Dist: psycopg<4,>=3.3.4
Requires-Dist: pydantic<3,>=2.13.4
Requires-Dist: pydantic-settings<3,>=2.14.2
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: pyyaml<7,>=6.0.3
Requires-Dist: sqlalchemy[asyncio]<3,>=2.0.51
Requires-Dist: fastapi[standard]==0.141.1
Requires-Dist: uvicorn<1,>=0.47.0
Requires-Dist: httpx2>=2.5.0
Requires-Dist: httpx<1,>=0.28
Requires-Dist: urllib3<3,>=2.7
Requires-Dist: mlflow<4,>=3.15
Requires-Dist: tomlkit<1,>=0.13
Requires-Dist: posthog<8,>=7.39.1
Provides-Extra: dev
Requires-Dist: pre-commit>=4.6.0; extra == "dev"
Requires-Dist: pytest>=9.1.1; extra == "dev"
Requires-Dist: pytest-asyncio>=1.3.0; extra == "dev"
Requires-Dist: pytest-cov<8,>=7.1; extra == "dev"
Requires-Dist: pytest-timeout>=2.4.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.5.0; extra == "dev"
Requires-Dist: ruff>=0.16.3; extra == "dev"
Requires-Dist: ty>=0.0.71; extra == "dev"
Provides-Extra: server
Requires-Dist: psycopg[binary]<4,>=3.3.4; extra == "server"
Requires-Dist: uvicorn[standard]<1,>=0.47.0; extra == "server"
Provides-Extra: benchmark
Requires-Dist: databricks-agents>=1.5; extra == "benchmark"
Provides-Extra: optimize
Requires-Dist: gepa>=0.1.1; extra == "optimize"
Dynamic: license-file

# Fleet RLM

**Recursive language-model backend with live streaming, durable sessions, and sandboxed execution.**

Fleet RLM runs [DSPy](https://github.com/stanfordnlp/dspy) `dspy.RLM` behind a compact FastAPI + SSE API. Each turn executes in an isolated [Daytona](https://www.daytona.io/) sandbox with workspace-scoped volumes, host-mediated tools, and a terminal client that streams reasoning, code, and output as it happens.

[![CircleCI](https://dl.circleci.com/status-badge/img/gh/Qredence/fleet-rlm/tree/main.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/Qredence/fleet-rlm/tree/main)
[![PyPI](https://img.shields.io/pypi/v/fleet-rlm?style=flat-square&logo=pypi&logoColor=white)](https://pypi.org/project/fleet-rlm/)
[![Python](https://img.shields.io/badge/python-3.11%20|%203.12%20|%203.13-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-2EA44F?style=flat-square)](LICENSE)
[![Docs](https://img.shields.io/badge/docs-Read%20the%20Docs-2C9ED0?style=flat-square&logo=readthedocs&logoColor=white)](https://fleet-rlm.readthedocs.io/)
[![DSPy](https://img.shields.io/badge/DSPy-3.3+-8B5CF6?style=flat-square)](https://dspy.ai/)
[![FastAPI](https://img.shields.io/badge/FastAPI-SSE-009688?style=flat-square&logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com/)

---

## Why Fleet RLM

- **RLM-native** — One fresh `dspy.RLM` per turn with Python REPL execution, native sub-LM queries, and optional recursive child RLMs.
- **Operator-visible streaming** — Reasoning, tool calls, interpreter code, and stdout flow over SSE to the maintained [pi-tui terminal](tools/fleet-tui/).
- **Durable by default** — Sessions, turns, attachments, artifacts, and workspace memory survive across runs.
- **Sandboxed execution** — Daytona interpreters run in isolated sandboxes with bounded workspace volumes and host-mediated memory tools.
- **Policy-driven runtime** — Non-secret behavior lives in `config/fleet.toml`; secret values stay in environment variables.

## Quick start

### 1. Install

```bash
git clone https://github.com/Qredence/fleet-rlm.git
cd fleet-rlm
uv sync --all-extras --dev
pnpm --dir tools/fleet-tui install --frozen-lockfile
```

You need **Node 22.19+** and **pnpm** for the terminal client (`fleet cli`). `uv sync` does not install TUI dependencies; run the `pnpm` step above before `fleet cli`.

### 2. Configure credentials

Pick a runtime profile in `config/fleet.toml` (`default_profile`; shipped default is `daytona-recursive`), then export the provider and Daytona variables for that profile. See the [profile matrix](docs/reference/profile-matrix.md) for the exact environment names.

Fleet connects through an OpenAI-compatible Chat Completions base URL, so
Databricks is only the shipped example. To use OpenAI or another compatible
provider, update the selected profile's `model`, `api_key_env`, and
`base_url_env` entries in `config/fleet.toml`; the base URL is typically the
provider's `/v1` root, such as `https://api.openai.com/v1`.

```bash
export FLEET_DATABASE_URL='postgresql+asyncpg://...'
export FLEET_DAYTONA_API_KEY='...'
export DATABRICKS_TOKEN='...'
export FLEET_DATABRICKS_AI_GATEWAY_BASE_URL='https://<workspace-id>.ai-gateway.gcp.databricks.com/mlflow/v1'

uv run python scripts/db_init.py
```

Startup never applies migrations automatically — initialize the database explicitly before serving.

### 3. Run

**Supervised backend + terminal** (recommended for local development):

```bash
uv run fleet cli
```

**Backend only:**

```bash
uv run fleet web
# or
uv run fleet-rlm serve-api --port 8000
```

Resume a durable session:

```bash
uv run fleet cli -- --session <session-uuid>
```

Before your first turn, verify Daytona connectivity:

```bash
uv run fleet doctor daytona
```

> **Profile mismatch fails fast.** `fleet cli` requires a Daytona profile that matches your credentials. Select profiles with `/profiles` in the TUI or edit `default_profile`, then restart Fleet.

## How a turn works

```text
Client  →  POST /api/sessions/{id}/turns  →  SSE stream
                │
                ├─ validate scope, attachments, skills
                ├─ TurnCoordinator opens run + prepares context
                ├─ RLMRunner executes one native dspy.RLM in Daytona
                ├─ stream reasoning, tools, code, output events
                └─ RunLifecycle commits result, artifacts, and turn history
```

The root agent can answer directly, delegate to sub-LMs, or fan out bounded recursive child RLMs. Session history stays host-side; workspace memory (`memory/MEMORIES.md`) persists across sandbox replacement.

## Commands

| Command | What it does |
| --- | --- |
| `uv run fleet cli` | Start backend + pi-tui terminal (Daytona profile required) |
| `uv run fleet web` | Start backend only on port 8000 |
| `uv run fleet doctor daytona` | Opt-in disposable probe of provider, DB, mounts, interpreter |
| `uv run python scripts/db_init.py` | Initialize or upgrade database to Alembic head |
| `make check` | Default validation lane (backend + TUI) |

Backend logs for supervised runs: `.fleet_rlm/logs/`.

## API surface

| Endpoint | Purpose |
| --- | --- |
| `POST /api/sessions/{session_id}/turns` | Idempotent turn execution over SSE |
| `/api/sessions` | Session CRUD and committed turn history |
| `/api/attachments` | Durable attachment upload and lookup |
| `/api/artifacts/{artifact_id}` | Committed artifact metadata and content |
| `GET /api/volume/tree` | Bounded read-only workspace volume tree (Daytona) |
| `/api/skills` | Bundled skill card discovery |
| `PUT /api/runs/{run_id}/cancellation` | Durable run cancellation |

Full contract: [HTTP API reference](docs/reference/http-api.md) and [OpenAPI](openapi.yaml).

## Project layout

| Path | Role |
| --- | --- |
| `src/fleet_rlm/` | Canonical Python backend |
| `tools/fleet-tui/` | Maintained pi-tui terminal client |
| `config/fleet.toml` | Runtime policy (profiles, limits, tracing) |
| `migrations/` | Alembic schema |
| `docs/` | Architecture, guides, and reference |

## Development

```bash
make check                 # lint, typecheck, tests (default lane)
make api-sync              # regenerate OpenAPI + TUI types
make check-security        # security scans
```

Contributing workflow and architecture rules: [CONTRIBUTING.md](CONTRIBUTING.md).

Key docs:

- [Architecture](docs/architecture.md)
- [Configuration](docs/reference/configuration.md)
- [Terminal UI guide](docs/how-to-guides/terminal-tui.md)
- [DSPy + Daytona integration](docs/how-to-guides/dspy-integration.md)
- [Testing strategy](docs/how-to-guides/testing-strategy.md)

## License

MIT — see [LICENSE](LICENSE).
