RENKIN — Retrosynthesis Engine for Knowledge-Informed Navigation

Computer-Aided Synthesis Planning (CASP) · Pure Rust · WebAssembly · Python
Named after 錬金 (れんきん, renkin) — Japanese for alchemy: just as alchemists transformed base metals into gold, RENKIN transforms target molecules back into cheap starting materials.

日本語版 README · 中文版 README · Documentation · Live Demo →

Keep your planner. Audit every route. Audit retrosynthesis routes from AiZynthFinder, Syntheseus, SynPlanner, or RENKIN — locally, reproducibly, and without sending molecular structures anywhere.

Audit a route in your browser → · Python quick start ↓ · Route planning engine ↓

What is RENKIN?

RENKIN Bridge is a tool-neutral route auditor: it checks structural integrity, stock coverage, and declared-reaction forward-replay for routes from AiZynthFinder, Syntheseus, SynPlanner, or RENKIN's own planner — the identical pass/fail/partial pipeline regardless of which tool produced the route, entirely local and reproducible (every audit records a verifiable audit_manifest), structures never leaving your machine unless you explicitly ask.

RENKIN is also, in its own right, an open-source retrosynthesis engine for computer-aided synthesis planning (CASP) that automatically discovers chemical reaction routes from a target molecule back to cheap, commercially available starting materials.

Built entirely in Rust with the chematic cheminformatics crate — zero C/C++ dependencies, #![forbid(unsafe_code)] throughout. One codebase compiles to a native CLI, a Rust library, Python wheels (PyO3), and a WebAssembly module that runs entirely client-side in the browser.

Installation

pip install renkin          # Python
cargo add renkin            # Rust
npm install renkin          # JavaScript (browser / bundler -- see docs/api/wasm.md)

Auditing Syntheseus routes needs one more, optional package: pip install renkin[syntheseus] (verified against Syntheseus 0.7.2 and 0.8.0).

Live Playground

→ Try it now — runs entirely in WebAssembly: no installation, no server, no network calls.

Audit a Route

Bring a route from wherever you already plan them — every path below runs through the identical audit pipeline: the same pass/fail/partial verdict regardless of source tool, or whether you ran it from the CLI, Python, or a browser tab.

AiZynthFinder

import json
import renkin

report = json.loads(
    renkin.audit_route(open("trees.json").read(), format="aizynthfinder")
)
print(report["summary"])

For an evidence-boundary report, add --chemical-review to renkin audit-route ... --output json. The optional report is deterministic; missing conditions, selectivity, and substrate-scope evidence remain not_evaluable. See the chemical review rubric.

Syntheseus (pip install renkin[syntheseus])

import json
import renkin
from renkin.syntheseus_exporter import dumps_syntheseus_route_v1

route_json = dumps_syntheseus_route_v1(my_synthesis_graph)
report = json.loads(renkin.audit_route(route_json, format="syntheseus"))
print(report["summary"])

SynPlanner

import json
import renkin

report = json.loads(
    renkin.audit_route(open("routes.json").read(), format="synplanner")
)
print(report["summary"])

In your browser — no installation, no upload, no server: Try the Playground →

Full walkthroughs with real output, end to end: AiZynthFinder · Syntheseus · SynPlanner.

Quick Start

Planning a route from scratch, not auditing one you already have — see Audit a Route above for that.

import json
import renkin

result = json.loads(
    renkin.find_routes(
        target="CC(=O)Oc1ccccc1C(=O)O",  # Aspirin
        depth=5,
        max_routes=3,
    )
)

for route in result["routes"]:
    for step in route["steps"]:
        print(f"  {step['target']} → {' + '.join(step['precursors'])}  [{step['rule']}]")

import init, { find_routes } from './pkg/renkin.js';
await init();
const result = JSON.parse(find_routes("CC(=O)Oc1ccccc1C(=O)O", 5, 3, 0));

./target/release/renkin --target "CC(=O)Oc1ccccc1C(=O)O" --depth 5 \
    --templates data/templates_extracted_5000.smi --format tree

Target: CC(=O)Oc1ccccc1C(=O)O
Routes found: 3

Route 1  [score=1.02, depth=1]
OC(=O)c1ccccc1OC(=O)C
└── [extracted_169]
    ├── OC(=O)C  ✓ BB
    └── [OH]c1ccccc1C(=O)O  ✓ BB

Route 2  [score=1.02, depth=1]
OC(=O)c1ccccc1OC(=O)C
└── [extracted_145]
    ├── CC(=O)Cl  ✓ BB
    └── [OH]c1ccccc1C(=O)O  ✓ BB

Route 3  [score=1.03, depth=1]
OC(=O)c1ccccc1OC(=O)C
└── [extracted_238]
    ├── c1cccc(c1O)C(O)=O  ✓ BB
    └── C([OH])(=O)C  ✓ BB

Use --format mermaid for GitHub/Notion-compatible flowcharts.

Current Limitations

Current release: v1.0.2.

⚠️ The corrected 4,903-target v1.0.1 shared-stock comparison is complete. RENKIN recorded 591/4,903 primary successes (12.05%) versus AiZynthFinder 4.4.1's 200/4,903 (4.08%); the paired difference was +7.975 percentage points with 95% CI [+7.098, +8.852]. The full v1.0.1 arm passed integrity verification, so both the statistical and formal publication gates pass. This is a result for the declared shared-stock endpoint, not universal CASP superiority. Historical 78.0%/95.9%/81.8%(ChEMBL) figures elsewhere in this repo predate validator fixes and are invalidated. RENKIN does not predict yields, calibrated experimental success probabilities, or side reactions, and does not search the literature automatically (success_probability is a template-frequency search-ranking score, not a calibrated prediction — see Benchmark for the corrected historical baseline, full methodology, and known limitations — that page is a frozen, single-commit measurement, not a live number).

Why RENKIN?

RENKIN is designed as a Rust-native synthesis planning stack:

Constraint-based Search

Restrict routes by the element composition of their building blocks.

Default search — all 5 routes for biphenyl:

renkin --target "c1ccc(-c2ccccc2)cc1" --templates data/templates_extracted_5000.smi --format tree

Routes found: 5
Route 1  [score=1.00, depth=1]  c1ccccc1Br + c1c(B(O)O)cccc1
Route 2  [score=1.03, depth=1]  c1ccccc1Br + c1c(B(O)O)cccc1
Route 3  [score=1.06, depth=1]  c1cc(Cl)ccc1 + c1c(B(O)O)cccc1
Route 4  [score=1.08, depth=1]  c1(I)ccccc1  + c1c(B(O)O)cccc1
Route 5  [score=1.08, depth=1]  c1ccccc1Br  + c1(B2OC(C(C)(C)O2)(C)C)ccccc1

Constrained search — boronic-acid coupling, no Br or I starting materials:

renkin --target "c1ccc(-c2ccccc2)cc1" --templates data/templates_extracted_5000.smi \
    --require-elements "B" --avoid-elements "Br,I" --format tree

Routes found: 1

Route 1  [score=1.06, depth=1]
c1ccccc1-c2ccccc2
└── [extracted_398]
    ├── c1cc(Cl)ccc1  ✓ BB
    └── c1c(B(O)O)cccc1  ✓ BB

Constraints compose freely and are enforced in two layers:

• --avoid-elements prunes expansions during search when a BB precursor contains a forbidden element (no dead-end nodes added to the heap).
• A final route-level post-filter is still applied for correctness.
• --require-elements is a route-level post-filter only.

Add --verbose to print search statistics (nodes expanded, elapsed time) to stderr. Performance counters are available in native builds only; disabled in WASM.

Add --search-diagnostics to add a search_diagnostics block to JSON output (beam eviction counts/scores, cross-template duplicate precursor signatures, rule-application attempts, stock-terminal/non-stock candidate counts, depth-wise branching factor, hypothetical dedup-strategy counts) — diagnostics-only bookkeeping, off by default, does not affect search behavior (Issue #101). Add --candidate-trace-limit <N> (implies --search-diagnostics) to also collect up to N per-candidate trace records (precursor signature, template provenance, beam rank/survival, whether it fed a returned route) — offline diagnostic use only, gated at collection time so the default no-trace path allocates nothing extra.

Template Evidence Metadata

Extracted templates only have a positional display name (extracted_{i}) that changes whenever the source .smi file is reordered or re-extracted, so external knowledge (a DOI, a reported yield, a known side reaction) can't be durably attached to one. Every template — hand-crafted and extracted — now has a stable template_id instead:

• Hand-crafted rules: rule:<rule_name> (e.g. rule:suzuki_retro).
• Extracted templates: smirks-sha256:<hex> — the SHA-256 hex digest of the trimmed SMIRKS string. Independent of file position, load order, and count; purely syntactic (no SMIRKS canonicalization — a semantically equivalent SMIRKS written differently gets a different ID).

Run renkin template ids <file.smi> to list every template's template_id, display name, SMIRKS, and weight (TSV by default, --format json for JSON) — use this to look up the IDs you need when authoring a sidecar file.

Attach curated evidence with --template-metadata sidecar.json (also available in Python as find_routes(..., template_metadata_path=...)), keyed by template_id:

{
  "schema_version": 1,
  "templates": {
    "smirks-sha256:ef8778a2888469d619c52cce7e74f6848e101049050dd1b765b78f32e3c94498": {
      "references": [
        { "id": "ref-1", "kind": "doi", "identifier": "10.xxxx/example" }
      ],
      "condition_candidates": [
        {
          "catalysts": ["Pd(PPh3)4"],
          "bases": ["K2CO3"],
          "solvents": ["EtOH", "water"],
          "temperature_c": { "min": 75.0, "max": 85.0 },
          "source": "literature",
          "scope": "template",
          "reference_ids": ["ref-1"]
        }
      ],
      "reported_yields": [
        {
          "percentage": { "min": 72.0, "max": 81.0 },
          "basis": "isolated",
          "source": "literature",
          "scope": "template",
          "reference_ids": ["ref-1"]
        }
      ],
      "warnings": [
        {
          "code": "possible_protodeboronation",
          "severity": "medium",
          "message": "Protodeboronation has been reported under prolonged aqueous heating.",
          "source": "literature",
          "scope": "template",
          "reference_ids": ["ref-1"]
        }
      ]
    }
  }
}

A matching step gets an evidence field with condition_candidates, reported_yields, references, and warnings; steps whose template has no sidecar entry get no evidence key at all. The sidecar is loaded and validated (schema version, duplicate/dangling reference IDs, yield range, range min <= max, non-empty DOI/patent identifiers) before search starts — malformed metadata is a hard error, and a template_id in the sidecar that matches no loaded rule prints a warning rather than failing silently.

What this is not:

• reported_yields is a curated record of what was reported externally — not a RENKIN prediction. step_confidence/success_probability are unaffected and keep meaning template-frequency-derived search-ranking scores, not experimental success rates.
• warnings reflects only what's explicitly present in the sidecar you supply — not automatic side-reaction detection.
• Templates without a matching sidecar entry get no fabricated evidence. Nothing is invented for missing data.

Yield/success prediction and automatic literature search are explicitly out of scope for this phase — tracked as future work in #41.

Substrate-specific examples (schema_version: 2)

Everything above is template-level: it applies to every step using that template, regardless of the actual molecule. schema_version: 2 adds examples — a per-template array where each entry is one curated record of this exact reaction, keyed by target_smiles/precursor_smiles:

{
  "schema_version": 2,
  "templates": {
    "smirks-sha256:...": {
      "references": [{ "id": "ref-1", "kind": "doi", "identifier": "10.xxxx/example" }],
      "examples": [{
        "id": "ex-1",
        "target_smiles": "c1ccc(-c2ccccc2)cc1",
        "precursor_smiles": ["Brc1ccccc1", "c1ccccc1"],
        "conditions": { "catalysts": ["Pd(PPh3)4"], "solvents": ["EtOH"], "source": "literature", "scope": "substrate_specific", "reference_ids": ["ref-1"] },
        "reported_yield": { "percentage": 78.0, "basis": "isolated", "source": "literature", "scope": "substrate_specific", "reference_ids": ["ref-1"] },
        "reference_ids": ["ref-1"]
      }]
    }
  }
}

examples requires schema_version: 2 (a hard error under 1); under schema_version: 2, reported yields must live under examples[].reported_yield too — a non-empty template-level reported_yields is a hard error there (it stays allowed under schema_version: 1), so a substrate-specific number can't leak onto every step using that template. Every condition/yield/warning nested inside an example must be scoped substrate_specific.

A route step's evidence.examples are resolved, not just copied from the sidecar: matched against that step by canonical target SMILES plus the canonical, order-independent precursor set (reordering precursor_smiles in the sidecar changes nothing), with every exact-substrate match kept and same-template-different-substrate precedents capped at 3. Each resolved entry carries a match_kind (exact_substrate/template_only) in the JSON itself, plus a template_examples_total count — so JSON/Python consumers, not just --format explain, can tell "evidence for this exact reaction" apart from "literature precedent for a different substrate." --format explain shows exact-substrate matches first, each labeled either Exact substrate example: or "different substrate; not a prediction", with conditions/ reported_yield/warnings each showing their own cited references directly underneath (deduplicated when the same reference backs more than one part of an example). See Reaction Evidence guide for full matching/validation semantics.

Importing evidence from ORD. renkin evidence match (exact-set batch template matching, no fuzzy/similarity matching) and scripts/ord_evidence_audit.py (offline, network-free) turn a locally-downloaded Open Reaction Database corpus into a schema_version: 2 sidecar — every accepted record is independently re-validated by RENKIN's own loader, and anything not uniquely matched, unambiguous, and provenanced is excluded and counted in an audit report rather than guessed at. RENKIN itself never fetches or searches the literature; reported yields are citations, not predictions. ORD's reaction data is CC-BY-SA-4.0, a different license from RENKIN's own MIT code — see Reaction Evidence guide for the full acceptance criteria and licensing split.

Key Features

step_confidence/success_probability are not yields or measured success rates. They're template-frequency-derived search-ranking scores (rule_weight / max_rule_weight, multiplied across a route's steps) used to order candidate disconnections during search — not a calibrated probability of experimental success, and not an expected isolated yield. Route-level experimental yield/success-rate reporting is not implemented.

Pipeline Examples

# Route cost scoring with commercial prices
renkin -t "Cc1ccc(-c2ccccc2)cc1" --bb-prices data/prices.csv --format json

# Standalone forward prediction — no route search involved
renkin-forward predict --reactants "Oc1ccccc1C(=O)O" "CCO" --report --max-results 5

# Forward validation — pipe find_routes output directly
renkin -t "CC(=O)Oc1ccccc1C(=O)O" --format json | renkin-forward validate

# Faster template retrieval with bond-center index (~24% speedup)
renkin -t "c1ccc(NC(=O)c2ccccc2)cc1" --templates data/templates_extracted_5000.smi --bond-index

# Audit a real AiZynthFinder route export with RENKIN (see the full walkthrough:
# https://kent-tokyo.github.io/renkin/guides/aizynthfinder-audit-demo/)
renkin audit-route tests/fixtures/aizynthfinder/v4.4.1/single_trees.json \
  --format aizynthfinder \
  --stock data/building_blocks.smi \
  --output human

# Same audit pipeline, either source — --format auto also detects both correctly
renkin -t "CC(=O)Oc1ccccc1C(=O)O" --format json > /tmp/renkin-route.json
renkin audit-route /tmp/renkin-route.json --format renkin
renkin audit-route tests/fixtures/aizynthfinder/v4.4.1/single_trees.json --format aizynthfinder

Benchmark

USPTO-50k test set (4,907 molecules, full evaluation):

Evaluation definition: A molecule is solved if find_routes returns at least one route whose leaf precursors are all in the building block set, within depth=5 and beam=100. Ground-truth reactants from USPTO-50k are not checked — any commercially accessible route counts.

Formal v1.0.1 shared-stock comparison (4,903 paired targets)

The paired RENKIN-minus-AiZynthFinder difference is +7.975 percentage points, with paired-bootstrap 95% CI [+7.098, +8.852]. The statistical and formal publication gates both PASS. The complete v1.0.1 arm passed target-set, manifest, schema, and route-hash integrity verification; all 591 reported routes had parseable normalized trees terminating in the configured shared stock. The frozen v1.0.0 HOLD artifact remains preserved separately. This is a shared-stock route endpoint, not experimental yield or universal CASP superiority. Protocol and status · corrected report

Corrected baseline (commit e20dc8c, 2026-07-22)

402 building blocks (unique compounds actually loaded from data/building_blocks.smi — see below), 5,000 extracted templates, 28 handcrafted rules, depth=5, beam=100. These three rates are a nested series over the same 4,907 targets, not independent numbers, and none is an experimentally-verified synthesis success rate or a human-chemist-reviewed route-accuracy figure. provenance_validated_solved_rate is not a measured chemical-accuracy rate and not a proven lower bound on correctness — it only counts routes the current validator can positively confirm, and an unknown fraction of "invalid" verdicts may be validator false negatives rather than real chemistry or route errors (the split is unmeasured). Full methodology, per-rule breakdown, and reproduction command: tasks/phase31_final_remeasurement_run.md · Full benchmark details →

Historical progression (pre-fix, invalidated — see notice above)

⚠️ The figures in this subsection (78.0% single-pass, 95.9% cascade, 81.8% ChEMBL OOD) predate the 31.11/31.12 fixes, are invalidated, and have not been re-measured. Kept for continuity only — do not cite as current performance.

Evaluation note: All numbers use the standard USPTO-50k train/test split (same corpus). Templates are extracted from the training set and evaluated on the test set. Numbers reflect performance within the USPTO-50k domain; out-of-distribution generalization was separately evaluated via ChEMBL approved drugs (81.8%, 409/500, also not re-measured).

* 29/50 chunks, previous binary
† 50/50 chunks — 72.1% (3,540/4,907) confirmed
BB counts in this historical table (463/480/509) are as originally documented at each point in time — legacy documentation values, not re-verified against ChemEnv::bb_count(). The corrected-baseline section above uses the actually-loaded count (402) for the current data/building_blocks.smi.

Note: LocalRetro (53.4%) and GLG (58.0%) report single-step top-1 prediction accuracy — a different metric, not directly comparable.

Benchmark scope note: USPTO-50k is used here as a standardized sanity benchmark, not as proof of broad real-world synthesis performance. The corpus covers a narrow slice of reaction space (primarily C–C and C–N bond formations common in pharmaceutical synthesis), and reaction types with sparse USPTO representation are systematically underserved. Out-of-distribution performance on ChEMBL approved drugs (81.8%, 409/500, pre-fix, not re-measured) suggested the rule set generalizes beyond the test corpus, but neither historical number should be interpreted as a guarantee of route quality on arbitrary targets.

PaRoutes compatibility

RENKIN is compatible with the PaRoutes multi-step benchmark. Download their stock compounds and target molecules, then pass them directly:

renkin-bench \
  --input paroutes_n1_targets.smi \
  --building-blocks paroutes_stock.smi \
  --templates data/templates_extracted_5000.smi \
  --depth 5 --beam-width 100

The JSON output includes avg_nodes_expanded, avg_confidence, avg_convergency, and avg_success_prob (Retro-prob style) alongside the standard solved/success_rate metrics.

Competitive Landscape

⚠️ RENKIN's row below uses the corrected raw_solved_rate (20.09%, see notice near the top of this README) — the 95.9% cascade figure some earlier versions of this table cited is invalidated and not re-measured; it is not included here.

raw_solved_rate is the closest available RENKIN metric to the published route-finding success rates of the other planners above, but the figures are not directly comparable — stock size, template library, target set, search budget, and route-quality checks all differ across systems, and this table does not establish RENKIN as better or worse than the alternatives.

RENKIN's goal: match state-of-the-art accuracy using only curated rules and auto-extracted SMIRKS templates — no GPU, no training data, no black boxes. Under RENKIN's benchmark setting (corrected baseline, commit e20dc8c, 2026-07-22), it reaches 20.09% raw_solved_rate (986/4,907) single-pass — see the Benchmark section above for the full nested-metric series and why the stricter provenance_validated_solved_rate (0.88%) is not RENKIN's measured or bounded correctness rate. RENKIN runs anywhere: browser, CLI, Python — single cargo build.

⚠️ The table above lists tools under different evaluation conditions. No matched-condition experiment against other tools has been performed.

MCP Server

renkin-mcp exposes retrosynthesis as an MCP tool so AI agents (Claude, etc.) can call it directly.

Setup — add to claude_desktop_config.json:

{
  "mcpServers": {
    "renkin": { "command": "/path/to/renkin-mcp" }
  }
}

Tools (7):

find_routes also accepts search_mode: "coverage" with a required coverage_templates path. It runs the standard Stage 1 first and escalates to Stage 2 only when Stage 1 finds no route; the response reports the selected stage, timeout status, and per-stage elapsed time.

The server auto-detects data/building_blocks.smi and the optional, locally generated data/templates_extracted_5000.smi in the working directory. It falls back to the embedded DEFAULT_BUILDING_BLOCKS / default_rules() defaults if they are not found (152 unique building blocks per ChemEnv::bb_count(), 23 handcrafted rules).

cargo build --release
# binary: target/release/renkin-mcp

Architecture

Workspace scope

┌──────────────────────────────────────────────────────────────────┐
│ renkin workspace (this repository)                               │
│                                                                  │
│  renkin  (retrosynthesis)         renkin-forward                  │
│  ──────────────────────           ─────────────────────────────  │
│  target → precursors              reactants → products           │
│  A* / AND-OR search               template-based forward         │
│  route scoring & constraints      (validates retro routes)       │
│        │                                    │                    │
│        └──────────────────┬─────────────────┘                    │
│                           ▼                                      │
│               chematic  (molecular representation,               │
│               SMILES, substructure matching, reaction SMARTS)    │
└──────────────────────────────────────────────────────────────────┘

Internal data flow (renkin crate)

Target SMILES
     │
     ▼
┌─────────────────────────┐
│     chem_env.rs         │  ← chematic wrapper
│  - SMILES parse         │     canonical-SMILES FxHashSet BB lookup (O(1))
│  - 23 built-in + up to 50k via --templates  │     fragment sanitization + ring-leak filter
│  - Building block check │     apply_retro memoization cache
└────────────┬────────────┘
             │  par_iter (rayon / sequential on WASM)
             ▼
┌─────────────────────────┐
│      search.rs          │  ← A* / AND-OR Tree Search
│  - Priority queue       │     SA Score heuristic + memoization
│  - Closed list          │     beam search (SmallVec frontier)
│  - Arc<PathNode> paths  │     O(1) path sharing per child
└────────────┬────────────┘
             │
             ▼
┌─────────────────────────┐
│      score.rs           │  ← Heuristic / Cost Function
│  - SA Score (chematic)  │     h = Σ(1 + 0.5·(sa−1)/9)
│  - MW step cost         │     g = Σ(1 + total_mw/2000)
└────────────┬────────────┘
             │
             ▼
┌─────────────────────────┐   (optional)
│      scorer.rs          │  ← Phase B: NN Template Scorer
│  - tract-onnx           │     Pure Rust ONNX inference
│  - --scorer flag        │     molecule-specific template ranking
└────────────┬────────────┘
             │
             ▼
  JSON  ←  CLI / Python / WASM

Project Structure

renkin/                          ← Cargo workspace root
├── Cargo.toml
├── src/                         ← renkin crate (retrosynthesis)
│   ├── lib.rs                   # public library
│   ├── main.rs                  # CLI binary (--templates, --template-metadata, --scorer, --constraints, --objectives flags)
│   ├── bin/benchmark.rs         # renkin-bench binary (--plausibility flag)
│   ├── bin/doctor.rs            # renkin-doctor diagnostic binary
│   ├── bin/fp.rs                # renkin-fp ECFP4 fingerprint (nn-scoring feature)
│   ├── bin/mcp.rs               # renkin-mcp stdio launcher
│   ├── mcp/                     # Dual-era protocol + 7 tool handlers
│   ├── chem_env.rs              # retro rules + BB lookup + template loader
│   ├── score.rs                 # SA Score heuristic + step cost
│   ├── search.rs                # A* / AND-OR tree engine + beam pruning
│   ├── scorer.rs                # Phase B: tract-onnx NN template scorer
│   ├── candidate.rs             # one-step candidate proposal (offline reranking foundation, not wired into search)
│   ├── pool_export.rs           # candidate-pool JSONL + reproducibility-manifest export
│   ├── python.rs                # PyO3 bindings (--features python)
│   └── wasm.rs                  # wasm-bindgen bindings (cfg = wasm32)
├── crates/                      ← sibling crates
│   ├── renkin-forward/          # forward reaction prediction (reactants → products)
│   └── renkin-kg/               # reaction knowledge graph builder (GraphML / Cypher export)
├── data/
│   ├── building_blocks.smi              # 402 curated commercial starting materials (loaded/deduplicated count)
│   ├── templates_extracted_500.smi      # 500 checked-in auto-extracted SMIRKS templates
│   ├── benchmark_targets.smi            # internal benchmark set
│   └── bench_chunks/                    # USPTO-50k per-chunk results
├── scripts/
│   ├── extract_templates.py         # rdchiral template extraction pipeline
│   ├── run_benchmark_chunks.sh      # resumable chunked benchmark runner
│   ├── train_reranker.py            # candidate reranker training/evaluation (dev tool, offline only)
│   └── tests/                       # unittest suite for train_reranker.py
├── docs/                # MkDocs source → kent-tokyo.github.io/renkin/
└── mkdocs.yml

Roadmap

Full shipped history (every release, in order): CHANGELOG.md. This section only tracks the current headline items and what's next — see "Earlier milestones" below for older shipped work.

Recently shipped

• SynPlanner Bridge (--format synplanner, shipped v0.34.0) — Keep SynPlanner. Audit its routes with RENKIN. A fourth route adapter, and the first whose native export carries real, forward-replayable atom mapping: renkin audit-route --format synplanner (also auto-detected) reads real SynPlanner 1.6.0 write_routes_json exports directly, no exporter package needed. Confirmed against real SynPlanner output twice — hand-constructed reactions through SynPlanner's own exporter, and a real CPU-only MCTS-searched planning run through the real synplan planning CLI end to end — every one of 317 real reaction nodes across a 167-route real search carries a structurally valid atom map, and real routes reach a genuine pass verdict, not just not_evaluable. New 4-way (RENKIN-native/AiZynthFinder/Syntheseus/SynPlanner) structural and policy-verdict parity tests. The browser playground's Audit tab gained SynPlanner as a fourth format option, with a one-click real-MCTS-output example. 5-minute walkthrough with real output →
• Syntheseus Bridge (--format syntheseus, shipped v0.30.0) — Syntheseus has no route export. RENKIN built one — and audits it exactly like every other adapter. A third route adapter alongside RENKIN-native and AiZynthFinder: the optional renkin.syntheseus_exporter (pip install renkin[syntheseus]) turns a real Syntheseus SynthesisGraph into the syntheseus-route-v1 interchange schema, which renkin audit-route --format syntheseus (also auto-detected) consumes through the identical audit pipeline every adapter shares. Forward validation honestly reports not_evaluable for every real Syntheseus route today — reaction_smiles carries no atom mapping, never faked into a pass. The browser playground's Audit tab gained Syntheseus as a third format option. 5-minute walkthrough with real output →
• Audit Policy Profiles (--policy informational|standard|strict, shipped v0.29.0) — One set of findings. Three ways to derive the verdict. Audit the same route under informational, standard, or strict policy without ever hiding or changing the underlying findings — policy only changes how the overall pass/fail/partial verdict is derived from findings already collected, recorded in audit_manifest.policy. Consistent across every surface: renkin audit-route --policy, the Rust API, the first Python binding for route auditing (renkin.audit_route()), and a new WASM audit_route_v2() (the existing audit_route() stays as a standard-policy wrapper). The browser playground's Audit tab gained a policy selector.
• Audit Playground ([ Audit a Route ] tab, shipped v0.28.0) — Audit a route in your browser — the same pipeline, the same verdict, zero network calls. The browser playground now audits a RENKIN or AiZynthFinder route export (single-route or Pandas batch) and an optional stock list entirely client-side, via a new audit_route WASM export that calls the identical report-building pipeline renkin audit-route uses — the same pass/fail/partial verdict either way, not a separately-maintained copy. Paste or upload, run off the main thread, download the JSON report.
• Reproducible Route Audit (audit_manifest on renkin audit-route --output json, shipped v0.27.0) — Reproduce what was audited, from which input, with which stock and policy. Every audit report now records RENKIN version, report schema version, source format/version, input/stock content SHA-256 hashes, and audit policy — tested for byte-identical determinism (auditing the same input twice), not just claimed. Adds a shared adapter conformance suite across RENKIN-native and AiZynthFinder route inputs, plus a written reproducibility/compatibility contract (verified-vs-supported versions, unknown-field tolerance, report-schema rules, adapter-fixture runbook). The browser playground also got a safety/UX pass this release: search runs off the main thread with cancel/time-budget support, structure rendering stays local by default (no third-party SMILES transmission), and search settings round-trip exactly through Copy CLI/Python.
• RENKIN Bridge — Cross-Tool Route Audit (renkin audit-route, RENKIN-native adapter shipped v0.25.0, AiZynthFinder adapter shipped v0.26.0) — Keep AiZynthFinder. Audit its routes with RENKIN. A tool-neutral route audit model: structural-integrity, stock, and declared-reaction forward-replay validation, each reported independently as pass/fail/not_evaluable, rolled up into a route-level pass/fail/partial verdict — never a silently force-passed boolean. v0.26.0 adds a real AiZynthFinder adapter (single-target and gzip batch JSON, verified against captured v4.4.1 output — see PROVENANCE.md) plus --format auto detection, so both tools' routes run through the exact same audit pipeline; auditing the real fixtures also surfaced and fixed a shared forward-replay bug where precursor ordering, not just chemistry, affected the verdict. renkin audit-route route.json --stock stock.smi --output json audits every route in a file and aggregates the results into one machine-readable report, regardless of which tool produced it.
• Coverage mode (--search-mode coverage, #101, shipped v0.24.0) — opt-in Stage-1/Stage-2 template-count escalation, addressing the candidate-generation coverage gap below. Confirmed by a one-shot 500-target formal-TEST (data/coverage_mode_formal_test/protocol_v2.md): coverage +6.0pp, net gain +30, zero regressions, zero reranker failures, Stage-2 timeout rate 0.25% — all against pre-registered thresholds. See the Key Features table above for the shipped surface
• Reranker made actually usable: Python exposure (find_routes()'s reranker_model_path/reranker_freq_table_path) and batteries-included model distribution (scripts/fetch_reranker_model.py, SHA-256-verified fetch from the v0.22.0 GitHub Release's canonical assets) (#101, shipped v0.23.0) — v0.22.0 proved the reranker works; v0.23.0 is the usability/distribution unlock, not a new accuracy claim
• LightGBM candidate reranker, trained/gated offline and wired into route search (#101 Task 35, CLI shipped v0.22.0) — LambdaMART model trained on real USPTO-50k labels, passed its VAL screening gate (top1 +11.7pp, MRR +11.3pp, top10 +9.3pp, bootstrap-CI-confirmed) and a formal 4,903-target TEST evaluation against the frozen model exactly once (top1 +12.7pp, MRR +11.9pp, top10 +9.1pp — consistent magnitude with VAL, no overfitting signal), then wired into find_routes as an ordering-only rank bonus and confirmed with a paired 100-target route-search gate: route_to_configured_stock 16→20/100 (+4/-0). See the Key Features table above
• Formal 500-target RENKIN vs AiZynthFinder comparison (#66) — under a fixed 500-target sample, shared 393-compound stock, and each tool's configured policy/budget, RENKIN Conservative's route_to_shared_stock outcome was 9.8 percentage points higher than AiZynthFinder's (73/500 vs 24/500). This is a protocol-specific paired result, not a general search-capability superiority claim; native-mode configurations use unmatched stocks and are not directly comparable.
• Ring-context safety guard for extracted templates (#72/#242) — opt-in --ring-context-policy/--ring-context-sidecar, catches extracted templates silently misapplying a ring-opening/closing disconnection their training data never saw; default remains disabled (unchanged legacy behavior)
• atom_economy no longer silently clamped to 100% when a route's represented precursor set can't account for the target's full mass (#79) — a new atom_economy_status field (normal/above_expected_range/not_evaluable) reports this explicitly instead

In progress

• Candidate-generation coverage gap — 33.0% (1,618/4,903) of the formal TEST corpus has zero positive candidates in-pool, a ceiling reranking cannot fix by construction. Template-diversity scaling remains a strong mechanism; a first provenance-bounded radius-zero abstraction track is now implemented and disjoint-VAL gated (#240), but its 4/22 targeted residual recovery is not a full-corpus remeasurement or a shipped default
• Template retrieval index (element bitmask + bond-center prefilter) for the 50k template set
• Calibrated route confidence (map success_probability to empirical solve rate)

Next

• Graph rule expansion — sulfonamide and carbamate cleavage (one PR per family, with structural and atom-accounting gates; carbamate shipped v0.61.0)
• Urea cleavage — validated atom-balanced disconnection to isocyanate + amine; implemented locally as the next-version candidate (not published)
• Stock-aware planning (price / hazard / availability re-ranking)
  • Deterministic policy-aware vendor-offer selection (price, lead time, availability) for exact private-stock matches
  • Optional local hazard labels and blocked-hazard policy decisions
  • Route-level stock score and deterministic multi-route ranking metadata
  • Constraint DSL route-cost cap (max_route_cost) with explicit route-cost semantics
  • Exact canonical building-block exclusion (avoid_building_blocks) for private/constrained stock policies
  • Exact canonical building-block requirement (require_building_blocks) for house-stock policies

Citation

If you use RENKIN in academic work, please cite it — see CITATION.cff for the canonical, version-tracked citation record. GitHub's "Cite this repository" button (top of the repo page) reads it directly and can export APA or BibTeX on demand.

Security

Report vulnerabilities via GitHub Private vulnerability reporting. See SECURITY.md.

License

MIT

GitHub Topics: retrosynthesis cheminformatics wasm rust drug-discovery casp synthesis-planning computational-chemistry

If RENKIN saves you time, a GitHub star helps others discover it.