renkin 0.1.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 kent-tokyo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,28 +1,67 @@
-# RENKIN — Retrosynthesis Engine
+# RENKIN — **R**etrosynthetic **E**xploration **N**etwork for **K**nowledge-**I**nformed **N**avigation
 
 > **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.
 
+[![CI](https://github.com/kent-tokyo/renkin/actions/workflows/ci.yml/badge.svg)](https://github.com/kent-tokyo/renkin/actions/workflows/ci.yml)
 [![Crates.io](https://img.shields.io/crates/v/renkin)](https://crates.io/crates/renkin)
+[![PyPI](https://img.shields.io/pypi/v/renkin)](https://pypi.org/project/renkin/)
+[![npm](https://img.shields.io/npm/v/renkin)](https://www.npmjs.com/package/renkin)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
-[![WASM](https://img.shields.io/badge/WASM-ready-brightgreen)](https://github.com/kent-tokyo/renkin/tree/master/demo)
+[![WASM](https://img.shields.io/badge/WASM-ready-brightgreen)](https://kent-tokyo.github.io/renkin/playground/)
 [![Pure Rust](https://img.shields.io/badge/Pure-Rust-orange?logo=rust)](https://www.rust-lang.org)
 
-[日本語版 README](./README_ja.md)
+[日本語版 README](./README_ja.md) · [**Documentation**](https://kent-tokyo.github.io/renkin/) · [**Live Demo →**](https://kent-tokyo.github.io/renkin/playground/)
 
 ---
 
 ## 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 — a core problem in **drug discovery** and **medicinal chemistry**.
+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.
 
-Built entirely in Rust with the [`chematic`](https://docs.rs/chematic/) cheminformatics crate, RENKIN solves the fundamental speed and dependency problems of existing Python-based CASP tools (AiZynthFinder, ASKCOS, Retro\*, etc.). It ships as:
+Built entirely in Rust with the [`chematic`](https://docs.rs/chematic/) cheminformatics crate. Zero C/C++ dependencies.
 
-- **CLI** — single binary, `cargo build --release`
-- **Python package** — `import renkin` via PyO3 + maturin
-- **WASM module** — 493 KB bundle, runs in the browser with no server
+**[→ Try the Live Playground](https://kent-tokyo.github.io/renkin/playground/)** — runs entirely in WebAssembly, no installation needed.  
+**[→ Full Documentation](https://kent-tokyo.github.io/renkin/)** — API reference, examples, benchmark.
 
-All from a single pure-Rust codebase with zero C/C++ dependencies.
+---
+
+## Installation
+
+```bash
+pip install renkin          # Python
+cargo add renkin            # Rust
+npm install renkin          # JavaScript / Node.js
+```
+
+---
+
+## Quick Start
+
+```python
+import renkin
+
+result = renkin.find_routes(
+    "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']}]")
+```
+
+```javascript
+import init, { find_routes } from './pkg/renkin.js';
+await init();
+const result = JSON.parse(find_routes("CC(=O)Oc1ccccc1C(=O)O", 5, 3, 0));
+```
+
+```bash
+./target/release/renkin --target "CC(=O)Oc1ccccc1C(=O)O" --depth 5 \
+    --templates data/templates_extracted.smi
+```
 
 ---
 
@@ -30,16 +69,48 @@ All from a single pure-Rust codebase with zero C/C++ dependencies.
 
 | Feature | Detail |
 |---|---|
-| **Pure Rust** | Zero C/C++ dependencies. Cross-platform with `cargo build` alone |
-| **A\* / AND-OR Tree Search** | Retro\*-equivalent algorithm proven more efficient than MCTS for retrosynthesis |
-| **SA Score heuristic** | `chematic::chem::sa_score` guides search toward synthetically accessible precursors |
-| **Beam search** | `--beam-width N` limits heap size for memory-bounded exploration |
-| **Graph-based Ar–Ar cleavage** | Bridge-bond detection via DFS — correctly handles biaryl (Suzuki) disconnections |
-| **Parallel rule application** | `rayon` parallelises SMIRKS rule evaluation; sequential fallback on WASM |
-| **Python bindings** | `maturin` extension — `import renkin; renkin.find_routes(...)` |
-| **WASM-ready** | 493 KB bundle via `wasm-pack`; browser demo with 2D structure rendering |
-| **~400 building blocks** | Curated commercial starting materials covering esters, amines, halides, heterocycles, amino acids, sulfonyl chlorides, boronic acids and more |
-| **Benchmark CLI** | `renkin-bench --input targets.smi` produces a JSON success/timing report |
+| **Pure Rust** | Zero C/C++ dependencies — cross-platform with `cargo build` alone |
+| **A\* / AND-OR Tree Search** | Retro\*-equivalent algorithm, proven more efficient than MCTS |
+| **SA Score heuristic** | Admissible h = Σ(1 + 0.5·(sa−1)/9) guides toward accessible precursors |
+| **Beam search** | `--beam-width N` for memory-bounded exploration |
+| **314 reaction rules** | 31 hand-crafted + 283 auto-extracted from USPTO-50k via rdchiral |
+| **Auto template extraction** | `scripts/extract_templates.py` — rdchiral + chematic-compatible simplification |
+| **Graph-based biaryl cleavage** | Bridge-bond DFS for correct Suzuki disconnection |
+| **Parallel rule application** | `rayon` on non-WASM; sequential fallback on wasm32 |
+| **Python** | `pip install renkin` — pre-built wheels for Linux/macOS/Windows |
+| **WASM** | ~500 KB bundle — runs in the browser at near-native speed |
+| **463 building blocks** | Aryl halides, boronic acids, heterocycles, amines, acids, amino acids |
+
+---
+
+## Benchmark
+
+USPTO-50k test set (4,907 molecules, full evaluation):
+
+| Config | Solved | Rate | BBs | Rules | depth |
+|---|---|---|---|---|---|
+| v0.1.0 initial | 366/4907 | 7.5% | 463 | 31 | 3 |
+| + auto templates (top-300) | 1363/4907 | 27.8% | 463 | 222 | 3 |
+| + depth=5, top-500 templates | **2315/4907** | **47.2%** | 463 | 314 | 5 |
+
+Surpasses ASKCOS (41%) and reaches AiZynthFinder lower bound (45%) with only 463 curated BBs.  
+Competitor reference: AiZynthFinder 45–53% (depth≤5, 6M BBs, 50k templates).  
+[Full benchmark details →](https://kent-tokyo.github.io/renkin/benchmark/)
+
+---
+
+## Competitive Landscape
+
+| Tool | Language | License | WASM | Zero-dep | Algorithm | Template source | Stock |
+|---|---|---|---|---|---|---|---|
+| **ASKCOS** | Python | CC BY-NC | No | No (Docker, 64 GB) | MCTS + A\* | USPTO (ML) | ZINC |
+| **AiZynthFinder** | Python | MIT | No | No (conda + model) | MCTS | USPTO (ML, ~50k) | eMolecules (~6M) |
+| **SYNTHIA** | Closed | Proprietary | No | No | SMARTS + AND/OR | Manual curated | Sigma-Aldrich |
+| **IBM RXN** | Closed | Cloud SaaS | No | No | Transformer | USPTO | — |
+| **Retro\*** | Python | MIT | No | No (unmaintained) | A\* + AND/OR | USPTO (ML) | eMolecules |
+| **★ RENKIN** | **Rust** | **MIT** | **Yes** | **Yes** | **A\* + AND/OR** | Hand-curated + rdchiral (314) | 463+ |
+
+**RENKIN's goal**: match or exceed neural-network-based tools using only curated rules and auto-extracted SMIRKS templates — no GPU, no training data, no black boxes. At 47.2% USPTO-50k (surpassing ASKCOS and reaching AiZynthFinder's lower bound), RENKIN demonstrates that a transparent, rule-based engine in pure Rust can compete with deep-learning approaches. And it runs anywhere: browser, CLI, Python — single `cargo build`.
 
 ---
 
@@ -51,9 +122,9 @@ Target SMILES
      ▼
 ┌─────────────────────────┐
 │     chem_env.rs         │  ← chematic wrapper
-│  - SMILES parse         │     SMARTS VF2 building-block check
-│  - SMIRKS retro rules   │     fragment sanitization
-│  - Building block check │     HashMap O(1) pre-filter
+│  - SMILES parse         │     canonical-SMILES HashSet BB lookup (O(1))
+│  - 314 retro rules      │     fragment sanitization + ring-leak filter
+│  - Building block check │     VF2 fallback for small sets
 └────────────┬────────────┘
              │  par_iter (rayon / sequential on WASM)
              ▼
@@ -77,193 +148,30 @@ Target SMILES
 
 ---
 
-## Technology Stack
-
-- **Language**: Rust (Edition 2024)
-- **Cheminformatics**: [`chematic`](https://crates.io/crates/chematic) v0.4.9+
-  - `chematic-smiles` — SMILES parsing & canonical SMILES
-  - `chematic-smarts` — VF2 substructure matching (building block identity)
-  - `chematic-rxn` — SMIRKS reaction application (`run_reactants`)
-  - `chematic-chem` — SA Score, molecular weight, aromaticity descriptors
-- **Search**: A\* + AND/OR Tree (Retro\* equivalent)
-- **Parallelism**: [`rayon`](https://crates.io/crates/rayon) — parallel SMIRKS rule application
-- **Python**: [`PyO3`](https://pyo3.rs) + [`maturin`](https://www.maturin.rs)
-- **WASM**: [`wasm-bindgen`](https://rustwasm.github.io/wasm-bindgen/) + [`wasm-pack`](https://rustwasm.github.io/wasm-pack/)
-
----
-
-## Installation
-
-### As a library
-
-```toml
-# Cargo.toml
-[dependencies]
-renkin = "0.1"
-```
-
-### CLI (from source)
-
-```bash
-git clone https://github.com/kent-tokyo/renkin
-cd renkin
-cargo build --release
-```
-
-### Python
-
-```bash
-pip install maturin
-git clone https://github.com/kent-tokyo/renkin && cd renkin
-python -m venv .venv && source .venv/bin/activate
-maturin develop --features python
-```
-
----
-
-## Getting Started
-
-### CLI
-
-```bash
-# Retrosynthesis (Aspirin, depth 3)
-./target/release/renkin --target "CC(=O)Oc1ccccc1C(=O)O" --depth 3
-
-# With beam search (top-50 nodes)
-./target/release/renkin --target "CC(=O)Oc1ccccc1C(=O)O" --depth 5 --beam-width 50
-```
-
-```
---target / -t      Target molecule SMILES
---depth  / -d      Max retrosynthesis depth (default: 5)
---max-routes / -n  Max routes to return (default: 5)
---beam-width / -w  Beam search width, 0 = unlimited A* (default: 0)
---building-blocks  Path to .smi file of commercial starting materials
-```
-
-### Python
-
-```python
-import renkin, json
-
-routes = json.loads(renkin.find_routes(
-    "CC(=O)Oc1ccccc1C(=O)O",   # Aspirin
-    depth=3,
-    max_routes=5,
-))
-print(routes["routes_found"])   # number of routes found
-for r in routes["routes"]:
-    print(r["depth"], [s["rule"] for s in r["steps"]])
-```
-
-### WASM
-
-```bash
-wasm-pack build --target web --no-default-features
-# Output: pkg/  (npm-ready package)
-# Browser demo: python3 -m http.server 8080 → http://localhost:8080/demo/
-```
-
-```javascript
-import init, { find_routes } from './pkg/renkin.js';
-await init();
-
-const result = JSON.parse(find_routes(
-  "CC(=O)Oc1ccccc1C(=O)O",  // target SMILES
-  3,   // depth
-  5,   // max_routes
-  0,   // beam_width (0 = unlimited A*)
-));
-console.log(result.routes_found);
-```
-
-### Benchmark
-
-```bash
-# Input: one SMILES per line, optional name after whitespace
-./scripts/run_benchmark.sh --input data/benchmark_targets.smi --depth 5
-```
-
-```json
-{
-  "total": 42, "solved": 37, "success_rate": 0.88,
-  "avg_depth": 1.05, "avg_time_ms": 2.5,
-  "results": [...]
-}
-```
-
----
-
-## CLI Output Example
-
-```json
-{
-  "target": "CC(=O)Oc1ccccc1C(=O)O",
-  "routes_found": 2,
-  "routes": [
-    {
-      "steps": [
-        {
-          "rule": "ester_cleavage",
-          "target": "CC(=O)Oc1ccccc1C(=O)O",
-          "precursors": ["CC(=O)O", "Oc1ccccc1C(=O)O"]
-        }
-      ],
-      "depth": 1
-    }
-  ]
-}
-```
-
-**depth: 0** means the target itself is a commercially available starting material (buy directly).
-
----
-
-## Retro-Rules (14 total)
-
-| Rule | Reaction type | Strategy |
-|---|---|---|
-| `ester_cleavage` | Ester → acid + alcohol | SMIRKS |
-| `amide_cleavage` | Amide → acid + amine | SMIRKS |
-| `friedel_crafts_acylation_retro` | Ar-C(=O)R → Ar-H + acyl chloride | SMIRKS |
-| `aryl_carboxylation_retro` | Ar-COOH → Ar-H + CO₂ surrogate | SMIRKS |
-| `aryl_amine_retro` | Ar-N → Ar-H + amine | SMIRKS |
-| `buchwald_hartwig_retro` | Ar-N → Ar-Br + amine | SMIRKS |
-| `aryl_ether_retro` | Ar-O → Ar-OH + fragment | SMIRKS |
-| `suzuki_retro` | Ar-Ar → Ar-Br + Ar-H | Graph (bridge-bond DFS) |
-| `cc_single_cleavage` | C–C → two fragments | SMIRKS |
-| `wittig_retro` | C=C → C=O + C=O | SMIRKS |
-| `reductive_amination_retro` | C–N → C=O + amine | SMIRKS |
-| `cn_aliphatic_cleavage` | C–N → two fragments | SMIRKS |
-| `co_aliphatic_cleavage` | C–O → two fragments | SMIRKS |
-| `alcohol_oxidation_retro` | C–OH → C=O | SMIRKS |
-
-`suzuki_retro` uses a graph-based bridge-bond algorithm instead of SMIRKS to correctly handle symmetric biaryls (biphenyl, 4-fluorobiphenyl, etc.) without the BFS leakage artifacts that affect SMIRKS-based approaches.
-
----
-
 ## Project Structure
 
 ```
 renkin/
 ├── Cargo.toml
 ├── src/
-│   ├── lib.rs           # public library (DEFAULT_BUILDING_BLOCKS, re-exports)
-│   ├── main.rs          # CLI binary
-│   ├── bin/
-│   │   └── benchmark.rs # renkin-bench binary
-│   ├── chem_env.rs      # chematic wrapper — parse, retro rules, BB check
-│   ├── score.rs         # SA Score heuristic + step cost
-│   ├── search.rs        # A* / AND-OR tree engine + beam pruning
-│   ├── python.rs        # PyO3 bindings (--features python)
-│   └── wasm.rs          # wasm-bindgen bindings (cfg = wasm32)
+│   ├── lib.rs               # public library
+│   ├── main.rs              # CLI binary  (--templates flag)
+│   ├── bin/benchmark.rs     # renkin-bench binary  (--templates flag)
+│   ├── chem_env.rs          # 314 retro rules, BB check, template loader
+│   ├── score.rs             # SA Score heuristic + step cost
+│   ├── search.rs            # A* / AND-OR tree engine + beam pruning
+│   ├── python.rs            # PyO3 bindings (--features python)
+│   └── wasm.rs              # wasm-bindgen bindings (cfg = wasm32)
 ├── data/
-│   ├── building_blocks.smi      # Commercial starting materials (~400 entries)
-│   └── benchmark_targets.smi   # 42-molecule benchmark set
-├── demo/
-│   └── index.html       # Browser WASM demo with 2D structure rendering
-└── scripts/
-    └── run_benchmark.sh # Benchmark runner with human-readable summary
+│   ├── building_blocks.smi          # 463 curated commercial starting materials
+│   ├── templates_extracted.smi      # 283 auto-extracted SMIRKS templates (top-500)
+│   ├── 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
+├── docs/                # MkDocs source → kent-tokyo.github.io/renkin/
+└── mkdocs.yml
 ```
 
 ---
@@ -272,31 +180,21 @@ renkin/
 
 - [x] **Phase 1** — SMIRKS retro-reaction rules + fragment sanitization
 - [x] **Phase 2** — A\* / AND-OR tree search, closed list, degenerate-route filter
-- [x] **Phase 3** — SA Score heuristic + beam search (`--beam-width`)
-- [x] **Phase 4** — Parallel rule application (`rayon`; sequential fallback on WASM)
-- [x] **Phase 5** — Python bindings (PyO3 + maturin)
-- [x] **Phase 6** — WASM build (493 KB, `pkg/` npm-ready)
-- [x] **Phase 7** — Benchmark CLI (`renkin-bench`)
-- [x] **Phase 8** — 21 unit tests, SMIRKS rules 5→14, building blocks ~30→~400
-- [x] **Phase 9** — Browser WASM demo (SmilesDrawer 2D rendering), benchmark target set
-- [x] **Phase 10** — Graph-based biaryl cleavage (suzuki_retro), O(1) BB HashMap index
-- [ ] **Phase 11** — Formal benchmark vs. AiZynthFinder / Retro\* on USPTO-50k
-- [ ] **Phase 12** — PyPI / npm publish
-
----
-
-## Competitive Landscape
-
-| Tool | Language | Algorithm | WASM | Zero-dep build |
-|---|---|---|---|---|
-| **ASKCOS** | Python | MCTS / A\* | No | No (Docker, 64 GB RAM) |
-| **AiZynthFinder** | Python | MCTS primary | No | No (conda, model download) |
-| **IBM RXN** | Closed | Transformer | No | No (cloud only) |
-| **SYNTHIA** | Closed | SMARTS + AND/OR | No | No (proprietary) |
-| **Retro\*** | Python | A\* + AND/OR | No | No (unmaintained) |
-| **★ RENKIN** | **Rust** | **A\* + AND/OR** | **Yes** | **Yes (`cargo build`)** |
-
-All existing open CASP tools are Python-based. RENKIN fills the vacant niche: Rust-native, WASM-deployable, zero-dependency, A\* search.
+- [x] **Phase 3** — SA Score heuristic + beam search
+- [x] **Phase 4** — Parallel rule application (rayon; sequential fallback on WASM)
+- [x] **Phase 5** — Python bindings (PyO3 + maturin) · `pip install renkin`
+- [x] **Phase 6** — WASM build · `npm install renkin`
+- [x] **Phase 7** — Benchmark CLI (`renkin-bench`) + initial USPTO-50k evaluation
+- [x] **Phase 8** — Unit tests · rules → 31 · building blocks → 463
+- [x] **Phase 9** — WASM browser playground + i18n (EN/JA/ZH)
+- [x] **Phase 10** — Graph-based biaryl cleavage · O(1) canonical-SMILES BB index
+- [x] **Phase 11** — Published to crates.io / PyPI / npm · GitHub Actions CI/CD
+- [x] **Phase 12** — MkDocs documentation site · GitHub Pages playground
+- [x] **Phase 13** — Formal USPTO-50k benchmark: **7.5%** (depth=3, 31 rules)
+- [x] **Phase 14** — Auto template extraction (rdchiral): **27.8%** (depth=3, 222 rules)
+- [x] **Phase 17** — chematic 0.4.12: Bug #13 (BFS leakage) + Bug #14 (canonical SMILES) fixed
+- [ ] **Phase 15** — Stereochemistry support (CIP SMIRKS)
+- [ ] **Phase 16** — Large-scale building block DB integration
 
 ---
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "renkin",
   "type": "module",
   "description": "Ultra-fast retrosynthesis engine for computer-aided synthesis planning (CASP) — pure Rust, WASM-ready, Python bindings via PyO3",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -19,18 +19,11 @@
   "sideEffects": [
     "./snippets/*"
   ],
-  "bugs": {
-    "url": "https://github.com/kent-tokyo/renkin/issues"
-  },
   "keywords": [
     "retrosynthesis",
     "cheminformatics",
     "chemistry",
     "wasm",
-    "webassembly",
-    "drug-discovery",
-    "casp",
-    "smiles",
-    "synthesis-planning"
+    "drug-discovery"
   ]
-}
+}