renkin 0.17.0 → 0.18.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,7 +325,7 @@ 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 |
@@ -539,6 +588,7 @@ renkin/                          ← Cargo workspace root
 ### Recently shipped
 
 - [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`
@@ -607,8 +657,8 @@ If you use RENKIN in academic work, please cite:
   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},
+  url       = {https://github.com/kent-tokyo/renkin/releases/tag/v0.18.0},
+  version   = {0.18.0},
   license   = {MIT}
 }
 ```

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.18.0",
   "license": "MIT",
   "repository": {
     "type": "git",