# RENKIN

Retrosynthesis planning and route auditing in Rust.

[![CI](https://github.com/kent-tokyo/renkin/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/kent-tokyo/renkin/actions/workflows/ci.yml)
[![Crates.io](https://img.shields.io/crates/v/renkin.svg)](https://crates.io/crates/renkin)
[![PyPI](https://img.shields.io/pypi/v/renkin.svg)](https://pypi.org/project/renkin/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

[Documentation](https://kent-tokyo.github.io/renkin/) · [Playground](https://kent-tokyo.github.io/renkin/playground/) · [日本語版](README_ja.md) · [中文](README_zh.md)

RENKIN has two uses:

- **Planner:** search retrosynthetic routes from a target molecule to building blocks.
- **Bridge:** audit routes from RENKIN, AiZynthFinder, Syntheseus, or SynPlanner.

Auditing is local and reproducible. Reports include structural checks, stock
coverage, forward replay, provenance, and a verifiable audit manifest.

Current release: **v1.0.8**. Public inputs are validated before execution;
WASM applies bounded search limits, and MCP numeric and element-filter
arguments fail closed when invalid. Standard MCP search also accepts an
optional cooperative `timeout_secs` budget.

The audit and private-stock policy layers are split into deterministic,
testable steps so their report schema and policy behavior remain stable.

## Install

```bash
pip install renkin
cargo add renkin
npm install renkin
```

For Syntheseus support:

```bash
pip install 'renkin[syntheseus]'
```

## Audit a route

```python
import json
import renkin

report = json.loads(
    renkin.audit_route(open("trees.json").read(), format="aizynthfinder")
)
print(report["summary"])
```

Use `format="syntheseus"`, `format="synplanner"`, or `format="renkin"` for
other supported route formats. The same audit pipeline is used for every
source.

```bash
renkin audit-route route.json --format auto --output json
```

Optional private stock and policy checks remain local:

```bash
renkin audit-route route.json \
  --private-stock private-vendors.csv \
  --stock-policy private-policy.json --output json
```

See the [audit guide](https://kent-tokyo.github.io/renkin/guides/audit-reproducibility-contract/),
[private stock policy](https://kent-tokyo.github.io/renkin/guides/private-stock-policy/),
and [route interchange](https://kent-tokyo.github.io/renkin/guides/evidence-carrying-interchange/).

## Plan a route

```python
import json
import renkin

result = json.loads(renkin.find_routes(
    target="CC(=O)Oc1ccccc1C(=O)O",  # aspirin
    depth=5,
    max_routes=3,
))

for route in result["routes"]:
    for step in route["steps"]:
        print(step["target"], "→", " + ".join(step["precursors"]))
```

CLI:

```bash
cargo run --release -- \
  --target "CC(=O)Oc1ccccc1C(=O)O" \
  --depth 5 --beam-width 100 --format tree
```

The planner uses A*/AND-OR search, template indexing, beam limits,
stock-aware scoring, and forward validation. See the [API documentation](https://docs.rs/renkin)
and [retrosynthesis guide](https://kent-tokyo.github.io/renkin/guides/rust-retrosynthesis/).

The following counts describe this checkout and may be invalidated by future
changes. The default planner includes 24 hand-crafted rules. The repository stock file
contains 402 compounds; installed users without that file use a compiled-in
152-compound fallback. Additional extracted templates can be supplied with
`--templates`.

## Components

| Component | Purpose |
| --- | --- |
| `renkin` | Planner, CLI, Python bindings, and WASM module |
| `renkin-forward` | Forward prediction, enumeration, hints, and validation |
| `renkin-kg` | Reaction knowledge-graph export |
| `renkin-mcp` | Local MCP server for search and audit |

The chemistry layer is [`chematic`](https://docs.rs/chematic/), with no
C/C++ dependency in the core.

## MCP

```bash
cargo run --release --bin renkin-mcp
```

The MCP server communicates over stdio and exposes search, validation,
explanation, constraints, diagnostics, and audit receipts. See the [MCP guide](https://kent-tokyo.github.io/renkin/guides/mcp/).

## Benchmark status

The registered Phase 55 shared-stock, shared-budget TEST comparison completed
690 targets: RENKIN found 481 strict routes (69.71%) and AiZynthFinder 4.4.1
found 32 (4.64%). The paired coverage difference was +65.07 percentage points
(95% CI +61.45 to +68.55). This is evidence only for the pinned cohort,
assets, stock, and budget; it is neither a universal CASP claim nor evidence
of laboratory success. Peak-RSS and time-to-first-route receipts remain open,
so it is not a whole-cohort performance claim.

See the [benchmark documentation](https://kent-tokyo.github.io/renkin/benchmark/)
for protocol, artifacts, and claim boundaries.

## Development

```bash
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all -- --check
```

Read [`AGENTS.md`](AGENTS.md), [`tasks/lessons.md`](tasks/lessons.md), and
the [roadmap](ROADMAP.md) before changing the chemistry or search core.

Important boundaries:

- stock identity is exact standardized canonical-SMILES membership;
- route success is not experimental success;
- external model output is evidence or candidates, not automatic validity;
- comparison manifests bind the tool, configuration, input files, and checked
  worktree state so resumed runs cannot silently mix configurations;
- benchmark claims must name the dataset, stock, versions, and endpoint.

## License

MIT. See [LICENSE](LICENSE).