renkin 0.25.0 → 0.27.0

package/README.md

@@ -27,6 +27,8 @@ RENKIN is an open-source **retrosynthesis engine** for **computer-aided synthesi
 
 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.
 
+Use RENKIN as an independent audit layer for retrosynthesis routes generated by RENKIN or AiZynthFinder — see [RENKIN Bridge / `audit-route`](#key-features) below.
+
 ---
 
 ## Installation
@@ -344,7 +346,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 [--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. RENKIN-native route JSON only in v0.25.0; the audit model itself is tool-neutral, built to take further source adapters later |
+| **RENKIN Bridge / `audit-route`** | `renkin audit-route route.json [--format auto\|renkin\|aizynthfinder] [--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) and 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); `--format auto` detects the input shape and hard-errors rather than guessing on anything ambiguous. [5-minute walkthrough with real output →](https://kent-tokyo.github.io/renkin/guides/aizynthfinder-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` |
@@ -381,6 +383,18 @@ 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
 ```
 
 ---
@@ -608,7 +622,8 @@ see "Earlier milestones" below for older shipped work.
 
 ### Recently shipped
 
-- [x] **RENKIN Bridge Preview** (`renkin audit-route`, shipped v0.25.0) — *Keep your current workflow. Add an auditable second opinion.* 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. The audit model is tool-neutral; v0.25.0 ships the first adapter for RENKIN-native route JSON. `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.
+- [x] **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](https://kent-tokyo.github.io/renkin/guides/audit-reproducibility-contract/) (verified-vs-supported versions, unknown-field tolerance, report-schema rules, adapter-fixture runbook). The [browser playground](https://kent-tokyo.github.io/renkin/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.
+- [x] **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`](tests/fixtures/aizynthfinder/v4.4.1/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.
 - [x] Coverage mode (`--search-mode coverage`, [#101](https://github.com/kent-tokyo/renkin/issues/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
 - [x] 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](https://github.com/kent-tokyo/renkin/issues/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
 - [x] LightGBM candidate reranker, trained/gated offline and wired into route search ([#101](https://github.com/kent-tokyo/renkin/issues/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

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.25.0",
+  "version": "0.27.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/renkin.d.ts

@@ -1,6 +1,14 @@
 /* tslint:disable */
 /* eslint-disable */
 
+/**
+ * Static capabilities of this WASM build (browser edition), as a JSON
+ * string -- real counts read from the same compiled-in data `find_routes`
+ * itself searches against, not a hardcoded UI string that can drift from
+ * what the engine actually has loaded.
+ */
+export function capabilities(): string;
+
 /**
  * Find retrosynthetic routes for a target molecule (WASM entry point).
  *
@@ -22,6 +30,23 @@
  */
 export function find_routes(target: string, depth: number, max_routes: number, beam_width: number): string;
 
+/**
+ * Find retrosynthetic routes with element filtering (WASM entry point).
+ *
+ * Same as [`find_routes`] plus `avoid_elements`/`require_elements`: comma-
+ * separated element symbols, identical format and conversion
+ * (`chem_env::elem_symbols_to_mask`) as the CLI's own `--avoid-elements`/
+ * `--require-elements` flags, so browser filtering behaves exactly like
+ * the CLI's, not a separately-maintained copy. A distinct function name
+ * rather than optional/extra parameters on `find_routes`, so a caller on
+ * an old build gets a real "no such export" `TypeError` instead of a
+ * silently-ignored argument -- this playground's own JS previously relied
+ * on `try { 6-arg call } catch { 4-arg call }` to bridge this gap, which
+ * meant `avoid_elements`/`require_elements` silently never took effect
+ * against any WASM build that predates this function.
+ */
+export function find_routes_v2(target: string, depth: number, max_routes: number, beam_width: number, avoid_elements: string, require_elements: string): string;
+
 /**
  * Return the crate version string.
  */
@@ -31,12 +56,14 @@ export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembl
 
 export interface InitOutput {
     readonly memory: WebAssembly.Memory;
+    readonly capabilities: () => [number, number];
     readonly find_routes: (a: number, b: number, c: number, d: number, e: number) => [number, number];
+    readonly find_routes_v2: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => [number, number];
     readonly version: () => [number, number];
     readonly __wbindgen_externrefs: WebAssembly.Table;
+    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
     readonly __wbindgen_malloc: (a: number, b: number) => number;
     readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
-    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
     readonly __wbindgen_start: () => void;
 }
 

package/renkin.js

@@ -1,5 +1,25 @@
 /* @ts-self-types="./renkin.d.ts" */
 
+/**
+ * Static capabilities of this WASM build (browser edition), as a JSON
+ * string -- real counts read from the same compiled-in data `find_routes`
+ * itself searches against, not a hardcoded UI string that can drift from
+ * what the engine actually has loaded.
+ * @returns {string}
+ */
+export function capabilities() {
+    let deferred1_0;
+    let deferred1_1;
+    try {
+        const ret = wasm.capabilities();
+        deferred1_0 = ret[0];
+        deferred1_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+    }
+}
+
 /**
  * Find retrosynthetic routes for a target molecule (WASM entry point).
  *
@@ -39,6 +59,47 @@ export function find_routes(target, depth, max_routes, beam_width) {
     }
 }
 
+/**
+ * Find retrosynthetic routes with element filtering (WASM entry point).
+ *
+ * Same as [`find_routes`] plus `avoid_elements`/`require_elements`: comma-
+ * separated element symbols, identical format and conversion
+ * (`chem_env::elem_symbols_to_mask`) as the CLI's own `--avoid-elements`/
+ * `--require-elements` flags, so browser filtering behaves exactly like
+ * the CLI's, not a separately-maintained copy. A distinct function name
+ * rather than optional/extra parameters on `find_routes`, so a caller on
+ * an old build gets a real "no such export" `TypeError` instead of a
+ * silently-ignored argument -- this playground's own JS previously relied
+ * on `try { 6-arg call } catch { 4-arg call }` to bridge this gap, which
+ * meant `avoid_elements`/`require_elements` silently never took effect
+ * against any WASM build that predates this function.
+ * @param {string} target
+ * @param {number} depth
+ * @param {number} max_routes
+ * @param {number} beam_width
+ * @param {string} avoid_elements
+ * @param {string} require_elements
+ * @returns {string}
+ */
+export function find_routes_v2(target, depth, max_routes, beam_width, avoid_elements, require_elements) {
+    let deferred4_0;
+    let deferred4_1;
+    try {
+        const ptr0 = passStringToWasm0(target, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(avoid_elements, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ptr2 = passStringToWasm0(require_elements, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len2 = WASM_VECTOR_LEN;
+        const ret = wasm.find_routes_v2(ptr0, len0, depth, max_routes, beam_width, ptr1, len1, ptr2, len2);
+        deferred4_0 = ret[0];
+        deferred4_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred4_0, deferred4_1, 1);
+    }
+}
+
 /**
  * Return the crate version string.
  * @returns {string}