SynPlanner 1.7.0

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

Quick start

1. Download pre-trained models, rules, and building blocks:

synplan download_preset --preset synplanner-gps --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/emolecules-salt-ln/building_blocks.tsv \
  --policy_network synplan_data/policy/supervised_gps/v1/v1/ranking_policy.ckpt \
  --results_dir planning_results

Paths above are what synplanner-gps writes — the download command prints each one.

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.

For local tutorials covering all steps from data curation to protection scoring, see the tutorials/ directory and the documentation.

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.; Madzhidov, T.; Varnek, A. Route Clustering by Strategic Bonds. ChemRxiv, 2025. doi:10.26434/chemrxiv-2025-lnkz6-vz

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

Westerlund, A. M. et al. Toward Lab-Ready AI Synthesis Plans with Protection Strategies and Route Scoring. ChemRxiv, 2025. doi:10.26434/chemrxiv-2025-68ff6