End-to-end retrosynthetic planning from raw reaction data

---

SynPlanner is an open-source tool for retrosynthetic planning. It integrates Monte Carlo Tree Search (MCTS) with graph neural networks to evaluate applicable reaction rules (policy network) and the synthesizability of intermediate products (value network).

• Data curation: standardize and filter raw chemical reaction data
• Rule extraction: extract reaction templates with configurable specificity
• Model training: train policy and value networks (supervised + RL)
• Retrosynthesis: MCTS-based planning with multiple search strategies
• Route quality: competing-sites scoring for functional group selectivity (Westerlund et al.)
• Route clustering: group routes by strategic bonds (Gilmullin et al.)
• Visualization: HTML route reports and interactive GUI

Installation

Requires: Python 3.10 – 3.14 · Linux x86_64, macOS arm64 · Docker images for other platforms

pip install SynPlanner
synplan --version

The base install provides chemistry tools, ChemFrame/pandas analysis, and CPU planning with ONNX policies and value networks. Choose an install for your workflow:

Workflow	Install
Chemistry, data tables and analysis, and ONNX planning on CPU	pip install SynPlanner
Curate reaction data and run atom mapping	pip install 'SynPlanner[curation]'
Train models, use tutorial notebooks, and export ONNX	pip install 'SynPlanner[training]'
Streamlit planning interface	pip install 'SynPlanner[gui]'
All three workflows	pip install 'SynPlanner[all]'
Use existing Torch checkpoints	pip install 'SynPlanner[cpu]'

training includes JupyterLab and widgets; launch tutorials with jupyter lab. For tutorials that also prepare reaction data or run atom mapping, install SynPlanner[curation,training] or SynPlanner[all].

With uv, select a Torch backend using cpu, cu126, or cu128, for example uv sync --no-dev --extra training --extra cu128 for CUDA 12.8 training. Use --extra curation --extra cu128 for GPU atom mapping, or combine curation and training for the full data-to-model workflow. For all workflows with CUDA 12.8, use uv sync --no-dev --extra all --extra cu128. These backend indexes are configured for uv; pip users should select their Torch build through the PyTorch package index. See ONNX export and inference to convert existing ranking checkpoints.

Quick start

1. Install Torch support for the existing published checkpoint presets, then download models, rules, and building blocks:

pip install 'SynPlanner[cpu]'
synplan download_preset --preset synplanner-gps-mcule-molport --save_to synplan_data

2. Write your targets and fetch a planning config (configs/ is not installed by pip):

echo 'CC(=O)Oc1ccccc1C(=O)O' > targets.smi
curl -O https://raw.githubusercontent.com/Laboratoire-de-Chemoinformatique/SynPlanner/main/configs/planning_standard.yaml

3. Run planning on a target molecule:

synplan planning \
  --config planning_standard.yaml \
  --targets targets.smi \
  --reaction_rules synplan_data/policy/supervised_gps/v1/reaction_rules.tsv \
  --building_blocks synplan_data/building_blocks/mcule-molport-2026-08/building_blocks.json.gz \
  --policy_network synplan_data/policy/supervised_gps/v1/v1/ranking_policy.ckpt \
  --results_dir planning_results

The download command prints each path. If a same-name .onnx file exists beside a checkpoint on Hugging Face, it downloads that file instead; use the printed ranking_policy path for --policy_network. ONNX planning needs only the base install.

Tip

Every tutorial runs in your browser. Open the tutorial index and click the badge next to the one you want — it installs SynPlanner and downloads its data for you. Nothing to set up.

The full CLI includes commands for every pipeline step: reaction_mapping, reaction_standardizing, reaction_filtering, rule_extracting, ranking_policy_training, planning, clustering, and more. Run synplan --help for the complete list.

The tutorials cover every step from data curation to protection scoring, route clustering and library design; the documentation explains the methods behind them.

Using SynPlanner with an AI agent

If you use Claude Code, Codex, Cursor, Copilot, or another agent that supports the Agent Skills format, this repository ships a skill that teaches the agent how to use SynPlanner correctly — which API to reach for, how chython differs from RDKit, and what to do by default.

Copy skills/synplanner-usage/ into your agent's skills directory — .claude/skills/, .cursor/skills/, or ~/.codex/skills/ — or ~/.claude/skills/ to make it available in every project. No further setup is needed.

It bundles a task index mapping each task to the API pieces it needs, in order.

For LLMs: llms.txt · skill, raw Markdown

Team

Questions & bug reports: open an issue or contact Tagir Akhmetshin (lead developer, maintainer) and Almaz Gilmullin (maintainer)

Contributors: Timur Madzhidov (initiator), Alexandre Varnek (supervisor), Dmitry Zankov (data curation, tutorials, reproducibility), Philippe Gantzer (GUI, writing module), Dmitry Babadeev (planning, visualization), Anna Pinigina (rule extraction), Milo Roucairol (search strategies), Mikhail Volkov (testing)

Citation

If you use SynPlanner in your research, please cite:

Akhmetshin, T.; Zankov, D.; Gantzer, P.; Babadeev, D.; Pinigina, A.; Madzhidov, T.; Varnek, A. SynPlanner: An End-to-End Tool for Synthesis Planning. J. Chem. Inf. Model. 2025, 65 (1), 15–21. doi:10.1021/acs.jcim.4c02004

If you use route clustering, please also cite:

Gilmullin, A.; Akhmetshin, T.; Zankov, D.; Klimchuk, O.; Horvath, D.; Madzhidov, T.; Varnek, A. Leveraging the Condensed Graph of Reaction for Clustering Retrosynthetic Pathways. J. Chem. Inf. Model. 2026, ASAP. doi:10.1021/acs.jcim.6c00489

If you use the protection / route quality scoring, please also cite:

Westerlund, A. M.; Sigmund, L. M.; Mijangos, M. V.; Kannas, C.; Genheden, S.; Kabeshov, M. Toward Lab-Ready AI Synthesis Plans with Protection Strategies and Route Scoring. J. Chem. Inf. Model. 2026, 66 (11), 6361–6375. doi:10.1021/acs.jcim.6c01147