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. Each Session holds one resident native dspy.RLM and one caller-owned interpreter, reused across sequential clean Turns, 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. TurnRuntime opens the SSE stream and 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 into a PreparedTurn.
7. RLMRunner executes the Turn on the Session’s resident native dspy.RLM and interpreter, creating them on first use.
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. TurnRuntime runs cleanup. A clean Turn leaves the Session-scoped lease resident for the next Turn. A tainted Turn rotates to a fresh interpreter and Sandbox first.

​

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/

create_app() in src/fleet_rlm/app.py 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. TurnRuntime sequences claim and replay, checkpoint History, capabilities, execution, streaming, validation, commit, finalization, and post-commit work under one ownership model with one terminal settlement. 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 executes each Run on the Session’s resident native dspy.RLM and caller-owned interpreter, held in the Session RLM registry. Sequential clean Turns in the same Workspace-plus-Session scope reuse that runtime, so ordinary Python globals persist while it stays healthy and compatible. Failure, cancellation, timeout, claim loss, commit failure, authorization failure, or uncertain settlement taints the runtime, and Fleet rotates to a fresh interpreter and Sandbox before the next Turn, rehydrating only durable state.

​

Daytona substrate — src/fleet_rlm/daytona/

Daytona owns provisioning, lifecycle, filesystem, and Workspace operations through one process-owned AsyncDaytona. Workspace storage in src/fleet_rlm/workspace/storage.py scopes each grouped I/O to one ephemeral Sandbox that is deleted before the context exits, and it is the only transport edge to the workspace agent client. Workspace Memory semantics live in src/fleet_rlm/workspace/memory.py. See Daytona runtime for the substrate deep cut.

​

Composition — src/fleet_rlm/composition/

Composition modules assemble runtime inventories. The lifespan installs the production Daytona-backed inventory from composition/live.py, and tests import the testing composition 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/app.py
2. src/fleet_rlm/api/routes/turns.py
3. src/fleet_rlm/chat/turn_runtime.py
4. src/fleet_rlm/chat/run_lifecycle.py
5. src/fleet_rlm/rlm/runtime.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.