renkin 0.30.0 → 0.32.0

package/README.md

@@ -21,13 +21,19 @@
 
 ---
 
+**Keep your planner. Audit every route.** Audit retrosynthesis routes from AiZynthFinder, Syntheseus, or RENKIN — locally, reproducibly, and without sending molecular structures anywhere.
+
+[**Audit a route in your browser →**](https://kent-tokyo.github.io/renkin/playground/) · [**Python quick start ↓**](#audit-a-route) · [**Route planning engine ↓**](#quick-start)
+
+---
+
 ## What is RENKIN?
 
-RENKIN is an open-source **retrosynthesis engine** for **computer-aided synthesis planning (CASP)** that automatically discovers optimal chemical reaction routes from a target molecule back to cheap, commercially available starting materials.
+RENKIN Bridge is a tool-neutral **route auditor**: it checks structural integrity, stock coverage, and declared-reaction forward-replay for routes from **AiZynthFinder**, **Syntheseus**, 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`](https://kent-tokyo.github.io/renkin/guides/audit-reproducibility-contract/)), structures never leaving your machine unless you explicitly ask.
 
-Built entirely in Rust with the [`chematic`](https://docs.rs/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.
+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.
 
-Use RENKIN as an independent audit layer for retrosynthesis routes generated by RENKIN or AiZynthFinder — see [RENKIN Bridge / `audit-route`](#key-features) below.
+Built entirely in Rust with the [`chematic`](https://docs.rs/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.
 
 ---
 
@@ -39,6 +45,10 @@ 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` — see the [compatibility spike](https://github.com/kent-tokyo/renkin/blob/master/docs/design/syntheseus-0.8-compatibility-spike.md)).
+
 ---
 
 ## Live Playground
@@ -47,8 +57,44 @@ npm install renkin          # JavaScript (browser / bundler -- see docs/api/wasm
 
 ---
 
+## 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**
+
+```python
+import json
+import renkin
+
+report = json.loads(
+    renkin.audit_route(open("trees.json").read(), format="aizynthfinder")
+)
+print(report["summary"])
+```
+
+**Syntheseus** (`pip install renkin[syntheseus]`)
+
+```python
+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"])
+```
+
+**In your browser** — no installation, no upload, no server: [**Try the Playground →**](https://kent-tokyo.github.io/renkin/playground/)
+
+Full walkthroughs with real output, end to end: [AiZynthFinder](https://kent-tokyo.github.io/renkin/guides/aizynthfinder-audit-demo/) · [Syntheseus](https://kent-tokyo.github.io/renkin/guides/syntheseus-audit-demo/).
+
+---
+
 ## Quick Start
 
+*Planning a route from scratch, not auditing one you already have — see [Audit a Route](#audit-a-route) above for that.*
+
 ```python
 import json
 import renkin
@@ -114,8 +160,9 @@ that fix 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](https://kent-tokyo.github.io/renkin/benchmark/) for the current
-corrected numbers, full methodology, and known limitations).
+[Benchmark](https://kent-tokyo.github.io/renkin/benchmark/) for the corrected
+historical baseline, full methodology, and known limitations — that page is a
+frozen, single-commit measurement, not a live number).
 
 ---
 
@@ -346,7 +393,7 @@ for the full acceptance criteria and licensing split.
 | **Ring-context safety guard** | `--ring-context-policy conservative --ring-context-sidecar <path>` — opt-in match-level filter that rejects an extracted template's ring-opening/closing disconnection when its historical training data never observed that bond as ring-forming/-breaking; default `disabled` (unchanged legacy behavior) — see [Issue #72](https://github.com/kent-tokyo/renkin/issues/72) |
 | **LightGBM candidate reranker** | `--reranker-model`/`--reranker-freq-table` (CLI) or `reranker_model_path`/`reranker_freq_table_path` (Python) — opt-in, ordering-only re-ranking via a frozen LightGBM model; never changes which candidates are generated, only their order, and reproduces legacy ordering byte-for-byte when off. Paired 100-target route-search gate: `route_to_configured_stock` 16→20 (+4/-0). `python3 scripts/fetch_reranker_model.py` fetches the frozen model (SHA-256-verified, not bundled in any package — see [Roadmap](#roadmap)) |
 | **Coverage mode** (opt-in) | `--search-mode coverage --coverage-templates <path>` (CLI) or `search_mode="coverage"`, `coverage_templates_path=...` (Python) — if the default template set finds no route, automatically escalates to a larger, separately loaded template set, cooperatively cancellable via `--coverage-timeout-secs`. Standard-mode output is byte-for-byte unchanged when not used. `python3 scripts/fetch_coverage_templates.py` fetches the frozen 2,000-template Stage-2 set (SHA-256-verified, not bundled in any package, same reasoning as the reranker model — see [Roadmap](#roadmap)) |
-| **RENKIN Bridge / `audit-route`** | `renkin audit-route route.json [--format auto\|renkin\|aizynthfinder\|syntheseus] [--stock stock.smi] [--output human\|json]` — tool-neutral route audit: 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. Reads RENKIN-native route JSON (v0.25.0), real AiZynthFinder route JSON — single-target and gzip-compressed batch output, verified against AiZynthFinder v4.4.1 specifically, not claimed for every version (v0.26.0) — and Syntheseus routes via the optional `renkin.syntheseus_exporter`'s `syntheseus-route-v1` interchange schema, since Syntheseus itself has no native route export (v0.30.0); `--format auto` detects the input shape and hard-errors rather than guessing on anything ambiguous. [AiZynthFinder walkthrough →](https://kent-tokyo.github.io/renkin/guides/aizynthfinder-audit-demo/) · [Syntheseus walkthrough →](https://kent-tokyo.github.io/renkin/guides/syntheseus-audit-demo/) |
+| **RENKIN Bridge / `audit-route`** | `renkin audit-route route.json [--format auto\|renkin\|aizynthfinder\|syntheseus] [--stock stock.smi] [--output human\|json]` — tool-neutral route audit: 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. Reads RENKIN-native route JSON (v0.25.0), real AiZynthFinder route JSON — single-target and gzip-compressed batch output, verified against AiZynthFinder 4.3.2, 4.4.0, and 4.4.1 specifically, not claimed for every version (v0.26.0, version matrix widened v0.32.0) — and Syntheseus routes via the optional `renkin.syntheseus_exporter`'s `syntheseus-route-v1` interchange schema, since Syntheseus itself has no native route export (v0.30.0); `--format auto` detects the input shape and hard-errors rather than guessing on anything ambiguous. [AiZynthFinder walkthrough →](https://kent-tokyo.github.io/renkin/guides/aizynthfinder-audit-demo/) · [Syntheseus walkthrough →](https://kent-tokyo.github.io/renkin/guides/syntheseus-audit-demo/) |
 | **Route scoring** | `confidence`, `step_confidence`, `success_probability` (Retro-prob style), `convergency`, `atom_economy`, `route_cost` (`Σ BB cost + steps×0.5`, or actual prices via `--bb-prices`/`--stock`) per step/route — see caveat below the table |
 | **Step metadata provenance** | Each step reports `metadata_source`/`metadata_scope` so it's machine-readable whether `conditions`/`reaction_family` came from a rule-author default vs. something more grounded; absent (not fabricated) for extracted templates |
 | **Pareto multi-objective search** | `--format pareto` returns a Pareto front across `route_cost`/`success_probability`/`steps`; objectives configurable via `--objectives` |
@@ -504,7 +551,7 @@ The JSON output includes `avg_nodes_expanded`, `avg_confidence`, `avg_convergenc
 | `plan_with_constraints` | Constraint-DSL planning (element filters, step limits, confidence thresholds) |
 | `estimate_diversity` | Route diversity and coverage metrics |
 
-The server auto-detects `data/building_blocks.smi` and `data/templates_extracted_5000.smi` in the working directory. Falls back to the embedded `DEFAULT_BUILDING_BLOCKS` / `default_rules()` defaults if not found (152 unique building blocks per `ChemEnv::bb_count()`, 28 handcrafted rules — verified 2026-07-22; a "509-BB / 20-rule" figure was previously documented here without verification).
+The server auto-detects `data/building_blocks.smi` and `data/templates_extracted_5000.smi` in the working directory. Falls back to the embedded `DEFAULT_BUILDING_BLOCKS` / `default_rules()` defaults if not found (152 unique building blocks per `ChemEnv::bb_count()`, 27 handcrafted rules — verified 2026-08-22, after `aryl_amine_retro`'s removal (issue #77) dropped the count from 28; a "509-BB / 20-rule" figure was previously documented here without verification).
 
 ```bash
 cargo build --release
@@ -651,7 +698,7 @@ see "Earlier milestones" below for older shipped work.
 Percentage figures below are historical milestones at the time each was
 shipped, not current performance — several predate the validator-accuracy
 fix noted in [Current Limitations](#current-limitations) and are invalidated;
-see [Benchmark](#benchmark) for the current corrected numbers.
+see [Benchmark](#benchmark) for the corrected historical baseline.
 
 - [x] Reranker made actually usable: Python exposure + batteries-included model distribution ([#101](https://github.com/kent-tokyo/renkin/issues/101), v0.23.0) — see "Recently shipped" above for the current-cycle summary; full detail in [`CHANGELOG.md`](CHANGELOG.md)
 - [x] Stable `template_id` (`rule:<name>` / `smirks-sha256:<hex>`) + `--template-metadata` evidence sidecar + `renkin template ids` ([#41](https://github.com/kent-tokyo/renkin/issues/41) phase 1)

package/package.json

@@ -5,7 +5,7 @@
     "kent-tokyo <kent-tokyo@users.noreply.github.com>"
   ],
   "description": "Ultra-fast retrosynthesis engine for computer-aided synthesis planning (CASP) — pure Rust, WASM-ready, Python bindings via PyO3",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "license": "MIT",
   "repository": {
     "type": "git",