fleet-rlm architecture

fleet-rlm is a Daytona-backed native dspy.RLM runtime with a FastAPI SSE transport in front of it. The backend is a thin coordination shell. One Run drives one fresh native dspy.RLM inside one interpreter context, and every observable behavior traces back to that pairing.

​

Layers at a glance

The Run coordination lane is the live center. Transport, persistence, and Skills all attach to it, and none of them replace it.

​

Runtime flow of one turn

1. The client posts to POST /api/sessions/{session_id}/turns with an Idempotency-Key header.
2. The transport resolves a deterministic local scope and validates the Turn input.
3. Attachment ownership and exact Skill selection are validated before any Run work begins.
4. TurnCoordinator.open() begins the SSE stream, coordinates heartbeat, terminal ordering, and cleanup.
5. RunLifecycle.begin() performs an atomic Run claim or a replay of an already-settled Run.
6. DefaultRunPreparer.prepare() assembles context, tools, and environment resources for the Run.
7. RLMRunner runs one fresh native dspy.RLM inside one interpreter context.
8. Runtime Events stream from the native trajectory, the interpreter, and the host-tool boundaries.
9. RunLifecycle.finish() validates the typed result and the private snapshot, promotes Artifact Candidate bytes on Daytona only, and commits Turn, Run, Checkpoint, and Artifact atomically or settles the failure.
10. The Run emits any artifact.created* events and then exactly one run.completed terminal event.
11. TurnCoordinator runs cleanup and the Interpreter Lease is released.

​

Root delegation ladder

Delegation inside one Run is a fixed four-step ladder:

1. Python — deterministic work inside the interpreter context.
2. Native llm_query / llm_query_batched — semantic work at the native boundary.
3. rlm_query — one iterative isolated subproblem.
4. Root-only rlm_query_batched — ordered independent child RLMs.

Recursive children remain one native level deep. RLM_NATIVE_CHILD_DEPTH = 1 is a fixed product invariant, not a tunable policy value. Fleet reserves the shared recursive budget atomically and controls sibling concurrency through recursion_max_parallel_children. See Recursive RLM for the child scheduling contract.

​

Layers in detail

​

FastAPI transport — src/fleet_rlm/api/

app.create_app() builds the FastAPI app and eagerly constructs the immutable bundled Skill catalog. The lifespan validates settings and installs exactly one complete Daytona runtime inventory. The transport does not contain business logic.

​

Turn coordination — src/fleet_rlm/chat/

The chat package owns the per-Turn lifecycle. TurnCoordinator sequences the SSE stream. RunLifecycle owns the Run claim, the private result snapshot, Artifact publication, atomic Turn Commit, and post-commit Memory promotion. Memory promotion is bounded and settled before the Run lease is released.

​

Native RLM runner — src/fleet_rlm/rlm/

RLMRunner runs one fresh native dspy.RLM per Run. Within one Run, interpreter calls reuse one context so Python state persists across RLM iterations. Every later Run receives a fresh context.

​

Daytona substrate — src/fleet_rlm/daytona/

Daytona owns provisioning, lifecycle, filesystem, and Workspace operations through one process-owned AsyncDaytona. WorkspaceVolumeGateway.open_workspace() scopes each grouped I/O to one ephemeral Sandbox that is deleted before the context exits. See Daytona runtime for the substrate deep cut.

​

Composition — src/fleet_rlm/composition/

Composition modules assemble runtime inventories for tests and specialized entry points. The lifespan never installs these directly, and tests import them explicitly.

​

Persistence — src/fleet_rlm/persistence/

Schema is Alembic-managed. The Turn repository is the durable seam between coordination and storage.

​

Sessions and assistant parts — src/fleet_rlm/sessions/

sessions/assistant_parts.py owns the closed Pydantic AssistantPart vocabulary for durable assistant content. Any new assistant content shape lives here first.

​

Skills — src/fleet_rlm/skills/

The bundled Skill catalog is immutable and is constructed eagerly during create_app(). Bundled Skills are dspy-rlm, long-context, workspace-files, data-analysis, and report-builder. Each Skill’s contract lives in its bundled SKILL.md and its resolver in src/fleet_rlm/skills/.

​

Reading order

Read these files in order when you need to understand the live backend:

1. src/fleet_rlm/api/app.py
2. src/fleet_rlm/api/routes/turns.py
3. src/fleet_rlm/chat/turn_coordinator.py
4. src/fleet_rlm/chat/run_lifecycle.py
5. src/fleet_rlm/rlm/runner.py
6. src/fleet_rlm/daytona/interpreter.py

​

Source of truth

When the docs disagree with the code, trust the code and the generated contracts. The canonical HTTP schema is openapi.yaml.