---
title: RetroEnv
emoji: ⚗️
colorFrom: gray
colorTo: green
sdk: docker
app_port: 8000
base_path: /web
pinned: false
tags: [openenv, chemistry, retrosynthesis, tool-use]
datasets:
  - LiteFold/RetroEnv
short_description: Plan retrosynthesis routes with verifier-backed rewards.
---

# RetroEnv: OpenEnv server

An agent gets a target molecule and works back to purchasable starting materials. It uses tools to inspect molecules, search a fixed stock and training precedents, and check disconnections. It ends the episode by submitting molecule/reaction trees with `emit_routes`, and the verifier judges every step against a frozen reaction library; matching the patent route only adds a bonus.

The same server is used for training, evaluation and the browser playground at `/web`.

## Read the code

- [`retroenv_openenv/environment.py`](retroenv_openenv/environment.py): the MCP tools, the Task API, `reset`, and the terminal reward.
- [`retroenv_openenv/client.py`](retroenv_openenv/client.py): `RetroEnvClient` for one episode per WebSocket session, and `RemoteRetroRouteEnv` for TRL's `environment_factory`.
- [`retroenv_openenv/agent.py`](retroenv_openenv/agent.py), [`agent_anthropic.py`](retroenv_openenv/agent_anthropic.py), [`agent_responses.py`](retroenv_openenv/agent_responses.py): model loops for OpenAI-compatible chat, the Claude Messages API and the OpenAI Responses API.
- [`retroenv_openenv/ui.py`](retroenv_openenv/ui.py): the playground.
- [`../core/retroenv`](../core/retroenv): chemistry, stock search, tasks and the verifier. Every front-end shares it.

## The episode

| Step | What happens |
|---|---|
| `reset(split, index)` | Returns the prompt, target, depth budget, route count, constraints and tool names. It never returns known routes, patents or the stock list. |
| tool calls | MCP `call_tool`. Up to 32 calls per episode (`RETROENV_MAX_TOOL_CALLS`); `emit_routes` always stays available. |
| `emit_routes(submission)` | Scores the trees. That step returns `done=True` with the dense reward, once. |

| Tool | Answers from |
|---|---|
| `inspect_molecule`, `pubchem_lookup` | RDKit on the given SMILES |
| `stock_retrieve` | The task's stock (excluded building blocks absent): exact, InChIKey, class, SMARTS or similarity search, capped at 20 results |
| `reaction_precedent_search`, `search_literature`, `reaction_conditions_search` | Train-visible corpus reactions only |
| `validate_disconnection` | Train-visible reactions and frequent templates, never this task's hidden routes. Removed by `RETROENV_TOOLSET=unaided`. |
| `reaction_class_lookup` | The verifier's own reaction classifier |
| `emit_routes` | The verifier |

The Task API lists splits and public task rows without references: `GET /retro_route/splits`, and `POST /retro_route/task`, `/tasks`, `/task_range` and `/num_tasks`. The API docs are at `/docs`.

## Data and credits

The tasks, known routes, difficulty labels, stock and reaction library are
[LiteFold/RetroEnv](https://huggingface.co/datasets/LiteFold/RetroEnv), the dataset built and
released by [LiteFold](https://huggingface.co/LiteFold). This server serves it unchanged.

It derives from PaRoutes v2: S. Genheden and E. Bjerrum, *PaRoutes: towards a framework for
benchmarking retrosynthesis route predictions*, Digital Discovery 2022
([doi:10.1039/D2DD00015F](https://doi.org/10.1039/D2DD00015F)); data on
[Zenodo 7341155](https://zenodo.org/records/7341155), CC BY 4.0. PaRoutes takes its reactions from
D. Lowe, *Chemical reactions from US patents (1976 to Sep 2016)*
([figshare](https://doi.org/10.6084/m9.figshare.5104873.v1)), CC0. Software: RDKit, rdchiral,
3Dmol.js and OpenEnv.

## Data and splits

The server serves a pinned snapshot of [LiteFold/RetroEnv](https://huggingface.co/datasets/LiteFold/RetroEnv)
from the public bucket [FineEnvs/retroenv-bucket](https://huggingface.co/buckets/FineEnvs/retroenv-bucket).
`corpus-manifest.json`, beside the server code, pins it: the release revision, the serving index and the
SHA-256 of every file a server reads.

| Split | Tasks | Use |
|---|---:|---|
| `train` | 75,224 | RL rollouts |
| `dev` | 1,079 | checkpoint selection |
| `test_id` | 1,083 | unseen targets, training distribution |
| `test_hard` | 1,119 | longer, novel or rarer chemistry |
| `final_eval` | 50 | 17 easy, 17 medium, 16 hard from the two test splits (`dataset/build_final_eval.py`) |

`final_eval` names tasks of the test splits, so they score exactly as there.

## Run locally

From the project folder (`09-retroenv`):

```bash
uv sync --extra dev --extra eval
uv run bash envs/retro_route/openenv/start.sh
```

`start.sh` runs `prepare.py`, which downloads the pinned snapshot from the bucket (about 115 MB,
once), checks every file's SHA-256, and starts the server; a restart reuses the checked files.
Startup then takes about 10 s. To serve a local release directory without an index instead:

```bash
RETROENV_BENCHMARK_DIR=data/release/RetroEnv-RL uv run uvicorn retroenv_openenv.server:app --port 8000
```

Open <http://localhost:8000/web/> for the playground. Its Plan tab works the way the task does: pick
the molecule still to make, take a cut the rule library proposes (or type one), check it and its
pieces with the real tools, and add it to a route drawn as it grows; "Fill from the plan" turns that
route into the `emit_routes` submission. Each molecule is drawn in 2D and, from an RDKit conformer,
in 3D (vendored [3Dmol.js](https://3dmol.csb.pitt.edu/), so it works offline). To run one model
episode against the server:

```bash
uv run python envs/retro_route/openenv/rollout.py --server http://127.0.0.1:8000 \
  --split final_eval --index 0 --provider anthropic --model claude-opus-5-5
```

## Docker and Spaces

The image holds code and `corpus-manifest.json` only. On a Space the bucket is mounted read-only at
`/data` and `prepare.py` copies the snapshot from there; with nothing mounted it downloads it.

```bash
python deploy.py --stage-only --stage-dir /tmp/retroenv-space
docker build -t retroenv /tmp/retroenv-space
docker run --rm -p 8000:8000 retroenv                       # downloads the pinned snapshot
```

[FineEnvs/retroenv](https://huggingface.co/spaces/FineEnvs/retroenv) is deployed with:

```bash
python deploy.py --repo FineEnvs/retroenv --public
```

`deploy.py` refuses to deploy unless every file the manifest names is already in the bucket, mounts
the bucket, and sets the variables below. A new snapshot comes from `dataset/publish_bucket.py`,
which also rewrites `corpus-manifest.json`.

| Variable | Default | Meaning |
|---|---|---|
| `RETROENV_CORPUS_MANIFEST` | `corpus-manifest.json` here | The serving snapshot to fetch and check |
| `RETROENV_BUCKET_ROOT` | `/data` in the image | A mounted copy of the bucket; files missing there are downloaded |
| `RETROENV_BUCKET_ID` | the manifest's | The bucket to download from, if it was renamed |
| `RETROENV_PREPARED_DIR` | `prepared` | Where the checked snapshot is kept between restarts |
| `RETROENV_BENCHMARK_DIR` | none | A local release or prepared directory, used as is |
| `RETROENV_TASKS_REPO` | none | A release dataset `org/name[@revision]`, served without an index |
| `RETROENV_TOOLSET` | `full` | `unaided` removes `validate_disconnection` (an ablation) |
| `RETROENV_MAX_TOOL_CALLS` | `32` | Tool budget per episode |
| `RETROENV_DEFAULT_SPLIT` | `train` | Split used by a reset that names none |
| `MAX_CONCURRENT_ENVS` | `64` | WebSocket sessions per process |
| `ENABLE_WEB_INTERFACE` | `true` | Mount the playground at `/web` |