# accio-lab/dressage architecture

> Architecture diagram of the GitHub repository accio-lab/dressage, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/accio-lab/dressage
- Repository: https://github.com/accio-lab/dressage

## Overview

1. **Overall shape**
   Dressage is a Python RL orchestration layer that sits between upstream **slime** training and agent execution environments. It adds two main capabilities: agent/tool execution through **paddocks**, and token-level trajectory recording through a shared **proxy**.

2. **Top-level runtime boundaries**
   The repo splits into three major runtime domains:
   - `dressage/` for rollout, sandbox, proxy, reward, and training glue
   - `blackbox_server/` for the in-sandbox HTTP service used by blackbox agents
   - `slime/` as an upstream submodule that provides the training/rollout substrate Dressage hooks into
   This is important for the diagram: Dressage extends slime rather than replacing it.

3. **End-to-end control flow**
   The main flow is: slime rollout hooks invoke Dressage’s generate path, a **paddock** acquires or attaches to a sandbox session, the agent runs, and all model calls go through the Dressage **proxy** to inference. The proxy records token-wise evidence, then the session is finalized into trajectories and converted into slime samples for training.

4. **Proxy as the central data recorder**
   `dressage/proxy/` is the core observability and trajectory layer. It mediates LLM calls, records per-token metadata, supports generation interruption/resume via `GenerationController`, and handles tokenization strategies like **TITO**. It also owns session management and trajectory storage, which makes it the canonical source of rollout evidence.

5. **Paddocks define interaction semantics**
   `dressage/paddock/` abstracts “how the agent interacts with the world.”
   - **Whitebox paddock**: Python-native tool loops where the agent directly calls tools.
   - **Blackbox paddock**: the agent is an external HTTP process managed through `blackbox_server`.
   This is the boundary between environment logic and sandbox placement.

6. **Sandbox layer handles isolation and placement**
   `dressage/sandbox/` provides the execution substrate, independent of agent type. There are two main providers:
   - **local bubblewrap pool** under `local/bwrap/`, with manager/supervisor/slot lifecycle
   - **remote E2B** under `remote/e2b/`
   The sandbox layer exposes provider-neutral concepts like leases/specs, so paddocks can request a sandbox without caring whether it is local or remote.

7. **BlackboxServer is the in-sandbox agent host**
   `blackbox_server/` is a FastAPI service that runs inside a sandbox and hosts exactly one active agent session at a time. It uses an adapter pattern (`adapters/`) to support backends like `opencode` and `openclaw`, while proxying model calls back through the Dressage proxy. This server is the key boundary for blackbox agents: it decouples rollout control from the concrete agent process.

8. **Rollout orchestration and async modes**
   `dressage/rollout/` contains the rollout engines and slime integration hooks. It supports sync, fully async, and partial async execution, plus multi-segment handling for trajectories that split due to compaction or schema changes. The `generate/` subpackage contains the two execution entry points: blackbox dispatch and whitebox agent scaffolding.

9. **Training/data conversion pipeline**
   `dressage/training/` and `dressage/rollout/artifacts/` turn recorded trajectories into training-ready samples. This layer handles reward post-processing, pause/resume semantics, and conversion of one trajectory into multiple samples when segments exist. The training path is designed to preserve token-level metadata, segment lineage, and prompt-equal weighting before handing data back to slime.

10. **Reward and recipe boundaries**
   `dressage/reward/` provides a registry and helpers for task-specific reward logic, while `dressage/recipes/` contains end-to-end example agents for **ALFWorld** and **HotpotQA**. These recipes show how a concrete task plugs into the same paddock/proxy/sandbox pipeline without changing the core runtime architecture.

11. **Configuration and runtime plumbing**
   `dressage/config/` and `dressage/runtime/` centralize environment-driven defaults, path resolution, and service naming. In practice, these modules glue together sandbox endpoints, proxy locations, model/runtime paths, and rollout behavior so that the same architecture can run locally, in containers, or against remote sandboxes.

12. **What to emphasize in an architecture diagram**
   The most important diagram boundaries are:
   - slime training loop vs Dressage rollout extensions
   - paddock logic vs sandbox isolation
   - in-sandbox blackbox agent vs external proxy/inference service
   - proxy recording vs training conversion
   The critical data path is not “agent to model” directly; it is **agent → proxy → inference → proxy → trajectory store → sample conversion → training**.

Main entry points: [`dressage/proxy`](https://github.com/accio-lab/dressage/tree/main/dressage/proxy) (Proxy), [`dressage/paddock/blackbox/paddock.py`](https://github.com/accio-lab/dressage/blob/main/dressage/paddock/blackbox/paddock.py) (Blackbox), [`dressage/sandbox`](https://github.com/accio-lab/dressage/tree/main/dressage/sandbox) (Sandbox), [`dressage/rollout`](https://github.com/accio-lab/dressage/tree/main/dressage/rollout) (Rollout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_slime["slime"]
  node_slime_core["Slime<br/>upstream substrate"]
end

subgraph group_dressage_core["dressage"]
  node_rollout["Rollout<br/>orchestration"]
  node_generate_blackbox["Blackbox gen<br/>dispatch"]
  node_generate_whitebox["Whitebox gen<br/>scaffold<br/>[whitebox_agent.py]"]
  node_paddock["Paddock<br/>interaction boundary"]
  node_whitebox_paddock["Whitebox<br/>tool loop<br/>[paddock.py]"]
  node_blackbox_paddock["Blackbox<br/>remote agent host<br/>[paddock.py]"]
  node_sandbox["Sandbox<br/>isolation layer"]
  node_bwrap_pool["Bwrap pool<br/>local sandbox"]
  node_e2b_provider["E2B<br/>remote sandbox<br/>[provider.py]"]
  node_proxy[("Proxy<br/>trajectory recorder")]
  node_generation_controller["Gen controller<br/>resume control"]
  node_trajectory_store["Trajectory store<br/>evidence store"]
  node_training["Training<br/>sample conversion"]
  node_reward["Reward<br/>task scoring"]
  node_recipes["Recipes<br/>examples"]
  node_runtime_config["Config/runtime<br/>plumbing"]
end

subgraph group_blackbox_server["blackbox server"]
  node_bb_api["API"]
  node_bb_adapters["Adapters<br/>agent backends"]
  node_bb_proxy["LLM proxy<br/>in-sandbox proxy"]
  node_bb_sessions["Session store<br/>active session state<br/>[session_store.py]"]
end

node_slime_core -->|"rollout hooks"| node_rollout
node_rollout -->|"dispatch"| node_generate_blackbox
node_rollout -->|"dispatch"| node_generate_whitebox
node_generate_blackbox -->|"session launch"| node_blackbox_paddock
node_generate_whitebox -->|"tool loop"| node_whitebox_paddock
node_paddock -->|"lease sandbox"| node_sandbox
node_blackbox_paddock -->|"hosted in"| node_bb_api
node_whitebox_paddock -->|"model calls"| node_proxy
node_blackbox_paddock -->|"model calls"| node_proxy
node_proxy -->|"control"| node_generation_controller
node_proxy -->|"record"| node_trajectory_store
node_trajectory_store -->|"samples"| node_training
node_reward -->|"post-process"| node_training
node_sandbox -->|"local provider"| node_bwrap_pool
node_sandbox -->|"remote provider"| node_e2b_provider
node_blackbox_paddock -->|"lifecycle"| node_bb_sessions
node_bb_api -->|"dispatch"| node_bb_adapters
node_bb_api -->|"proxy out"| node_bb_proxy
node_bb_sessions -->|"session bound"| node_bb_proxy
node_recipes -->|"examples"| node_whitebox_paddock
node_recipes -->|"task logic"| node_reward
node_runtime_config -->|"defaults"| node_sandbox
node_runtime_config -->|"defaults"| node_proxy

click node_slime_core "https://github.com/accio-lab/dressage/tree/main/slime"
click node_rollout "https://github.com/accio-lab/dressage/tree/main/dressage/rollout"
click node_generate_blackbox "https://github.com/accio-lab/dressage/blob/main/dressage/rollout/generate/blackbox_dispatch.py"
click node_generate_whitebox "https://github.com/accio-lab/dressage/blob/main/dressage/rollout/generate/whitebox_agent.py"
click node_paddock "https://github.com/accio-lab/dressage/tree/main/dressage/paddock"
click node_whitebox_paddock "https://github.com/accio-lab/dressage/blob/main/dressage/paddock/whitebox/paddock.py"
click node_blackbox_paddock "https://github.com/accio-lab/dressage/blob/main/dressage/paddock/blackbox/paddock.py"
click node_sandbox "https://github.com/accio-lab/dressage/tree/main/dressage/sandbox"
click node_bwrap_pool "https://github.com/accio-lab/dressage/tree/main/dressage/sandbox/local/bwrap"
click node_e2b_provider "https://github.com/accio-lab/dressage/blob/main/dressage/sandbox/remote/e2b/provider.py"
click node_proxy "https://github.com/accio-lab/dressage/tree/main/dressage/proxy"
click node_generation_controller "https://github.com/accio-lab/dressage/blob/main/dressage/proxy/generation_controller.py"
click node_trajectory_store "https://github.com/accio-lab/dressage/blob/main/dressage/proxy/trajectory_store.py"
click node_training "https://github.com/accio-lab/dressage/tree/main/dressage/training"
click node_reward "https://github.com/accio-lab/dressage/tree/main/dressage/reward"
click node_recipes "https://github.com/accio-lab/dressage/tree/main/dressage/recipes"
click node_runtime_config "https://github.com/accio-lab/dressage/tree/main/dressage/config"
click node_bb_api "https://github.com/accio-lab/dressage/tree/main/blackbox_server/api"
click node_bb_adapters "https://github.com/accio-lab/dressage/tree/main/blackbox_server/adapters"
click node_bb_proxy "https://github.com/accio-lab/dressage/blob/main/blackbox_server/proxy/rollout_llm_proxy.py"
click node_bb_sessions "https://github.com/accio-lab/dressage/blob/main/blackbox_server/store/session_store.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_slime_core toneBlue
class node_rollout,node_generate_blackbox,node_generate_whitebox,node_paddock,node_whitebox_paddock,node_blackbox_paddock,node_sandbox,node_bwrap_pool,node_e2b_provider,node_proxy,node_generation_controller,node_trajectory_store,node_training,node_reward,node_recipes,node_runtime_config toneAmber
class node_bb_api,node_bb_adapters,node_bb_proxy,node_bb_sessions toneMint
```

## Components

### slime

Upstream training and rollout substrate

- [Slime](https://github.com/accio-lab/dressage/tree/main/slime): upstream substrate · Upstream rollout/training base that Dressage extends · `slime`

### dressage

Core orchestration, proxy, sandbox, and training layers

- [Rollout](https://github.com/accio-lab/dressage/tree/main/dressage/rollout): orchestration · Sync, async, and multi-segment rollout engines and slime hooks · `dressage/rollout`
- [Blackbox gen](https://github.com/accio-lab/dressage/blob/main/dressage/rollout/generate/blackbox_dispatch.py): dispatch · Rollout entrypoint for launching blackbox agent sessions · `dressage/rollout/generate/blackbox_dispatch.py`
- [Whitebox gen](https://github.com/accio-lab/dressage/blob/main/dressage/rollout/generate/whitebox_agent.py): scaffold · Rollout entrypoint for native agent/tool loops · `dressage/rollout/generate/whitebox_agent.py`
- [Paddock](https://github.com/accio-lab/dressage/tree/main/dressage/paddock): interaction boundary · Abstracts how an agent interacts with the world · `dressage/paddock`
- [Whitebox](https://github.com/accio-lab/dressage/blob/main/dressage/paddock/whitebox/paddock.py): tool loop · Python-native tool execution inside Dressage · `dressage/paddock/whitebox/paddock.py`
- [Blackbox](https://github.com/accio-lab/dressage/blob/main/dressage/paddock/blackbox/paddock.py): remote agent host · Manages external agent sessions through blackbox_server · `dressage/paddock/blackbox/paddock.py`
- [Sandbox](https://github.com/accio-lab/dressage/tree/main/dressage/sandbox): isolation layer · Provider-neutral sandbox leasing and placement · `dressage/sandbox`
- [Bwrap pool](https://github.com/accio-lab/dressage/tree/main/dressage/sandbox/local/bwrap): local sandbox · Local bubblewrap manager, supervisor, and slot lifecycle · `dressage/sandbox/local/bwrap`
- [E2B](https://github.com/accio-lab/dressage/blob/main/dressage/sandbox/remote/e2b/provider.py): remote sandbox · Remote sandbox provider · `dressage/sandbox/remote/e2b/provider.py`
- [Proxy](https://github.com/accio-lab/dressage/tree/main/dressage/proxy): trajectory recorder · Central LLM mediation, token recording, session and trajectory storage · `dressage/proxy`
- [Gen controller](https://github.com/accio-lab/dressage/blob/main/dressage/proxy/generation_controller.py): resume control · Coordinates generation interruption, resumption, and last-step handling · `dressage/proxy/generation_controller.py`
- [Trajectory store](https://github.com/accio-lab/dressage/blob/main/dressage/proxy/trajectory_store.py): evidence store · Persists token-level rollout evidence and session trajectories · `dressage/proxy/trajectory_store.py`
- [Training](https://github.com/accio-lab/dressage/tree/main/dressage/training): sample conversion · Post-processes trajectories into training-ready samples · `dressage/training`
- [Reward](https://github.com/accio-lab/dressage/tree/main/dressage/reward): task scoring · Reward registry and helpers for task-specific scoring · `dressage/reward`
- [Recipes](https://github.com/accio-lab/dressage/tree/main/dressage/recipes): examples · End-to-end task integrations such as ALFWorld and HotpotQA · `dressage/recipes`
- [Config/runtime](https://github.com/accio-lab/dressage/tree/main/dressage/config): plumbing · Environment defaults, path resolution, and service naming · `dressage/config`

### blackbox server

In-sandbox HTTP host for blackbox agents

- [API](https://github.com/accio-lab/dressage/tree/main/blackbox_server/api): fastapi · HTTP endpoints for health, rollout, and sessions · `blackbox_server/api`
- [Adapters](https://github.com/accio-lab/dressage/tree/main/blackbox_server/adapters): agent backends · Backend adapters for opencode, openclaw, and other agents · `blackbox_server/adapters`
- [LLM proxy](https://github.com/accio-lab/dressage/blob/main/blackbox_server/proxy/rollout_llm_proxy.py): in-sandbox proxy · Forwards model calls back through Dressage proxy from inside the sandbox · `blackbox_server/proxy/rollout_llm_proxy.py`
- [Session store](https://github.com/accio-lab/dressage/blob/main/blackbox_server/store/session_store.py): active session state · Tracks the single active blackbox session · `blackbox_server/store/session_store.py`

## Connections

- Slime → Rollout: rollout hooks · Dressage extends slime's training/rollout substrate
- Rollout → Blackbox gen: dispatch · Rollout selects the blackbox generation path
- Rollout → Whitebox gen: dispatch · Rollout selects the whitebox generation path
- Blackbox gen → Blackbox: session launch · Blackbox generation acquires or attaches to a sandboxed agent session
- Whitebox gen → Whitebox: tool loop · Whitebox generation scaffolds native agent/tool execution
- Paddock → Sandbox: lease sandbox · Paddocks request provider-neutral sandbox placement
- Blackbox → API: hosted in · Blackbox paddock talks to the in-sandbox HTTP agent server
- Whitebox → Proxy: model calls · Whitebox executions route LLM requests through the shared proxy
- Blackbox → Proxy: model calls · Blackbox agent sessions route LLM requests through the shared proxy
- Proxy → Gen controller: control · Proxy manages interruption, resume, and last-step behavior
- Proxy → Trajectory store: record · Proxy persists token-level evidence and session trajectories
- Trajectory store → Training: samples · Recorded trajectories are converted into training-ready samples
- Reward → Training: post-process · Reward outputs feed training-time reward processing
- Sandbox → Bwrap pool: local provider · Local bubblewrap pool supplies sandbox instances
- Sandbox → E2B: remote provider · Remote E2B supplies sandbox instances
- Blackbox → Session store: lifecycle · Blackbox paddock manages the active session lifecycle
- API → Adapters: dispatch · API routes agent requests to the selected backend adapter
- API → LLM proxy: proxy out · In-sandbox server forwards model calls back to Dressage proxy
- Session store → LLM proxy: session bound · The active blackbox session is tied to proxy-mediated rollouts
- Recipes → Whitebox: examples · Recipes demonstrate concrete whitebox agent integrations
- Recipes → Reward: task logic · Recipes provide task-specific reward implementations
- Config/runtime → Sandbox: defaults · Configuration resolves sandbox endpoints and provider settings
- Config/runtime → Proxy: defaults · Configuration resolves proxy locations and runtime paths
