renkin 0.17.0 → 0.19.0

package/README.md

@@ -265,6 +265,55 @@ Yield/success prediction and automatic literature search are explicitly out
 of scope for this phase — tracked as future work in
 [#41](https://github.com/kent-tokyo/renkin/issues/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`:
+
+```json
+{
+  "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](docs/guides/reaction-evidence.md#substrate-specific-examples-schema_version-2)
+for full matching/validation semantics.
+
 ---
 
 ## Key Features
@@ -276,12 +325,13 @@ of scope for this phase — tracked as future work in
 | **Up to 50k reaction templates** | Auto-extracted from USPTO-50k/MIT via rdchiral; frequency-weighted priority; `--templates` for custom sets |
 | **Route scoring** | `confidence`, `step_confidence`, `success_probability` (Retro-prob style), `convergency`, `atom_economy` per step — see caveat below the table |
 | **Step metadata provenance** | Each step reports `metadata_source`/`metadata_scope` (e.g. `handcrafted_default`/`reaction_family`) so it's machine-readable whether `conditions`/`reaction_family` came from a rule-author default vs. something more grounded; absent for extracted templates, since nothing is fabricated for them. |
-| **Stable template IDs + evidence sidecar** | Every template gets a stable `template_id` — `rule:<name>` for hand-crafted rules, `smirks-sha256:<hex>` for extracted templates (independent of file order/position/count). Attach curated DOIs/patents, reported conditions, reported yields, and known side-reaction warnings via a `--template-metadata sidecar.json` file keyed by `template_id`; matching steps get an `evidence` field, everything else stays untouched — see [Template evidence metadata](#template-evidence-metadata) below. Run `renkin template ids <file.smi>` to list stable IDs for authoring a sidecar. Automatic yield/success prediction and literature search remain out of scope ([#41](https://github.com/kent-tokyo/renkin/issues/41)). |
+| **Stable template IDs + evidence sidecar** | Every template gets a stable `template_id` — `rule:<name>` for hand-crafted rules, `smirks-sha256:<hex>` for extracted templates (independent of file order/position/count). Attach curated DOIs/patents, reported conditions, reported yields, and known side-reaction warnings via a `--template-metadata sidecar.json` file keyed by `template_id`; matching steps get an `evidence` field, everything else stays untouched — see [Template evidence metadata](#template-evidence-metadata) below. `schema_version: 2` sidecars can additionally attach `examples` — curated records tied to one exact target/precursor set, matched by canonical SMILES and surfaced first in `--format explain`. Run `renkin template ids <file.smi>` to list stable IDs for authoring a sidecar. Automatic yield/success prediction and literature search remain out of scope ([#41](https://github.com/kent-tokyo/renkin/issues/41)). |
 | **Route cost scoring** | `route_cost = Σ(BB cost) + steps×0.5`; actual prices via `--bb-prices CSV` or `--stock stock.csv` |
 | **Pareto multi-objective search** | `--format pareto` returns a Pareto front across `route_cost`, `success_probability`, `steps`, etc.; objectives configurable via `--objectives cost:min,success_probability:max,steps:min` |
 | **Constraint DSL** | `--constraints constraints.json` — JSON-driven synthesis planning: element filters, step limits, confidence thresholds, preferred reaction families; enables LLM → RENKIN pipeline |
 | **Output formats** | `--format json` · `tree` · `mermaid` · `explain` (human-readable per-route analysis) · `compare` (side-by-side table) · `compare-json` · `pareto` |
 | **Failure diagnostics** | Zero-route JSON output includes `diagnostics` block with `likely_causes` and `suggestions` |
+| **Standalone forward prediction** | `renkin-forward predict --reactants <SMILES>...` enumerates and ranks forward reaction product candidates from reversed SMIRKS templates, independent of route search — see the [Forward Prediction guide](docs/guides/forward-prediction.md) |
 | **Forward validation** | `renkin-forward validate` verifies each step by applying templates forward; accepts `--route-json` or stdin |
 | **Plausibility report** | `renkin-bench --plausibility` — forward-validates best routes and reports composite plausibility score |
 | **PaRoutes benchmark** | `renkin-bench --input-format paroutes` for multi-step ground-truth evaluation with `depth_delta` and `route_diversity` |
@@ -314,6 +364,9 @@ of scope for this phase — tracked as future work in
 # 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
 
@@ -515,6 +568,8 @@ renkin/                          ← Cargo workspace root
 │   ├── 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
@@ -527,7 +582,9 @@ renkin/                          ← Cargo workspace root
 │   └── bench_chunks/                    # USPTO-50k per-chunk results
 ├── scripts/
 │   ├── extract_templates.py         # rdchiral template extraction pipeline
-│   └── run_benchmark_chunks.sh      # resumable chunked benchmark runner
+│   ├── run_benchmark_chunks.sh      # resumable chunked benchmark runner
+│   ├── train_reranker.py            # candidate reranker training/evaluation (dev tool, offline only — see docs/guides/reranker-candidate-pools.md)
+│   └── tests/                       # unittest suite for train_reranker.py
 ├── docs/                # MkDocs source → kent-tokyo.github.io/renkin/
 └── mkdocs.yml
 ```
@@ -538,7 +595,10 @@ renkin/                          ← Cargo workspace root
 
 ### Recently shipped
 
+- [x] `renkin-forward` CLI hardening — versioned `ForwardPredictionReport`, deterministic candidate IDs/merge/provenance, reactant-order-independent matching (up to 3 reactants), strict CLI/route-JSON validation
+- [x] RETROSPECT-inspired offline candidate-reranking foundation — candidate proposal/selection separation, feature schema v1, manifest v2, leakage-safe train/val/test splitting, 7 deterministic baseline arms + trained-ranker arm, paired bootstrap + offline gate tooling ([#59](https://github.com/kent-tokyo/renkin/pull/59); **foundation only — no trained model or accuracy result yet, not wired into route search**)
 - [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)
+- [x] Substrate-specific `examples` (`schema_version: 2`) — per-step exact-substrate vs. same-template-different-substrate resolution, surfaced in `--format explain` and as `match_kind` in JSON ([#41](https://github.com/kent-tokyo/renkin/issues/41) phase 2)
 - [x] `renkin-bench cascade` — multi-stage search (fast defaults → hard cases re-run deeper); only unsolved targets propagate to later stages. **78.0% → 95.9%** on USPTO-50k
 - [x] `renkin-bench --failure-taxonomy` — classify unsolved targets by cause (beam limit / depth limit / template gap / stock near-miss)
 - [x] Graph-based ester cleavage — BFS-leakage-free `R-C(=O)-O-R' → RCOOH + R'OH`
@@ -600,18 +660,10 @@ renkin/                          ← Cargo workspace root
 
 ## Citation
 
-If you use RENKIN in academic work, please cite:
-
-```bibtex
-@software{renkin2026,
-  author    = {kent-tokyo},
-  title     = {{RENKIN}: Retrosynthesis Engine for Knowledge-Informed Navigation},
-  year      = {2026},
-  url       = {https://github.com/kent-tokyo/renkin/releases/tag/v0.17.0},
-  version   = {0.17.0},
-  license   = {MIT}
-}
-```
+If you use RENKIN in academic work, please cite it — see [`CITATION.cff`](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.
 
 ---
 

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "renkin",
   "type": "module",
+  "collaborators": [
+    "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.17.0",
+  "version": "0.19.0",
   "license": "MIT",
   "repository": {
     "type": "git",