synomega 0.1.0__tar.gz

synomega-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zbc0315
+
+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.

synomega-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: synomega
+Version: 0.1.0
+Summary: Retrosynthesis toolkit: single-step prediction, multi-step route planning, synthesizability scoring
+Author: zbc0315
+License: MIT
+Project-URL: Homepage, https://github.com/zbc0315/synomega
+Project-URL: Repository, https://github.com/zbc0315/synomega
+Project-URL: Issues, https://github.com/zbc0315/synomega/issues
+Keywords: retrosynthesis,cheminformatics,synthesizability,rdkit,route-planning
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rdkit>=2023.3
+Requires-Dist: numpy>=1.23
+Provides-Extra: gnn
+Requires-Dist: torch>=2.0; extra == "gnn"
+Requires-Dist: torch_geometric>=2.4; extra == "gnn"
+Requires-Dist: pyyaml>=6.0; extra == "gnn"
+Provides-Extra: viz
+Requires-Dist: graphviz>=0.20; extra == "viz"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# synomega
+
+Retrosynthesis toolkit: **single-step prediction → multi-step route planning → synthesizability scoring**.
+
+```
+synthesizability   is this target reachable from purchasable material, in N steps?
+     ↑
+search             Retro* / MCTS / best-first over an AND-OR graph
+     ↑
+singlestep         product SMILES -> ranked reactant candidates
+```
+
+The layers are decoupled by a deliberately narrow interface: a single-step
+backend only implements `predict(smiles, top_k) -> [Prediction]`. Whether it is
+a graph neural network, a transformer, or plain template matching is invisible
+to the planner.
+
+## Install
+
+```bash
+pip install -e .            # core: rdkit + numpy, no torch
+pip install -e '.[gnn]'     # adds the D-MPNN neural backend
+```
+
+The neural backend is an **optional** extra on purpose — the template-rule
+backend runs anywhere, with no GPU and no torch.
+
+## Quick start
+
+```python
+from synomega import Planner, SynthesizabilityScorer
+from synomega.singlestep import TemplateGNN
+from synomega.stock import InMemoryStock
+
+model   = TemplateGNN.from_pretrained("../ml-template-gnn/runs/uspto50k_r0_min10")
+stock   = InMemoryStock.from_keys_file("emolecules.keys.gz")
+planner = Planner(model, stock, algorithm="retrostar")
+
+result = planner.plan("CC(=O)Nc1ccccc1", max_depth=5, time_limit=60)
+print(result.solved)
+print(result.best_route.describe())
+```
+
+```
+target: CC(=O)Nc1ccccc1
+solved: True  steps: 2  depth: 2  bb_coverage: 1.00
+  [1] CC(=O)O.Nc1ccccc1>>CC(=O)Nc1ccccc1  (score=0.4348)
+  [2] O=[N+]([O-])c1ccccc1>>Nc1ccccc1  (score=0.2174)
+```
+
+### Synthesizability
+
+```python
+scorer = SynthesizabilityScorer(planner)
+
+r = scorer.score("CC(=O)Nc1ccccc1", max_steps=5)
+r.solved         # True — a complete route to purchasable material exists
+r.bb_coverage    # 1.0 — fraction of leaves that are buyable
+r.min_depth      # 2 — steps in the shortest solved route
+
+report = scorer.score_batch(targets, max_steps=5)
+report.solve_rate         # headline benchmark number
+report.mean_bb_coverage
+report.to_dataframe()
+```
+
+## The two synthesizability metrics
+
+These get conflated in the literature; synomega keeps them apart because they
+answer different questions.
+
+| Metric | Meaning | Use it for |
+|---|---|---|
+| `solved@N` / `solve_rate` | Binary: does a route of depth ≤ N exist whose leaves are **all** purchasable? | Comparing against published numbers |
+| `bb_coverage@N` | Continuous: fraction of the best route's leaves that are purchasable | Ranking molecules by how close they are |
+
+`bb_coverage` matters because most targets are unsolved at realistic step
+limits. A 5-step route with 4 of 5 leaves buyable scores 0.8, not 0 — so a
+near-miss is distinguishable from a total failure.
+
+## CLI
+
+```bash
+# one-time: precompute InChIKeys so later loads take seconds, not minutes
+synomega build-stock --catalogue emolecules.smi.gz --out emolecules.keys.gz
+
+synomega plan  --target "CC(=O)Nc1ccccc1" --model runs/uspto50k_r0_min10 \
+             --stock emolecules.keys.gz --stock-is-keys --max-steps 5
+
+synomega score --targets targets.smi --model runs/uspto50k_r0_min10 \
+             --stock emolecules.keys.gz --stock-is-keys \
+             --max-steps 5 --out report.json
+```
+
+## Search algorithms
+
+| Algorithm | Character | When |
+|---|---|---|
+| `retrostar` | Expands the frontier molecule with the lowest estimated **total route cost** (Chen et al. 2020) | Default |
+| `mcts` | UCT with greedy rollouts; tolerates an unreliable top-1 | When the single-step model is weak |
+| `bfs` | Best-first on `g + h` | Baseline, debugging |
+
+All three share the AND-OR graph, the budget, and the route extractor, so they
+are directly comparable.
+
+## Design notes
+
+**AND-OR graph, not a tree.** A molecule node is solved if it is in stock or
+*any* of its reactions is solved; a reaction is solved if *all* its reactants
+are. Molecules are interned by InChIKey, so an intermediate reached down two
+branches is one node expanded once. Cycles are rejected when the edge is
+created — a route that makes X from X is not a route.
+
+**Batched expansion.** Search is naturally "expand one node, call the model
+once", which leaves a GPU idle. The algorithms pull a batch of frontier nodes
+and issue one `predict_batch`.
+
+**Caching.** Search revisits the same molecule constantly. `Planner(cache=True)`
+(the default) memoizes expansions; `cache_path=` persists them to SQLite so the
+cache survives across runs.
+
+**Stock membership is by InChIKey**, so keys computed here match a vendor
+catalogue written by a different toolkit. There is deliberately no Bloom-filter
+backend: false positives would inflate solve-rate and quietly break
+comparability with published numbers.
+
+## Status
+
+Implemented and tested: chem layer, single-step interface + template-rule and
+D-MPNN backends, expansion cache, AND-OR graph, all three search algorithms,
+route extraction/scoring/serialization, synthesizability metrics, CLI.
+
+Reserved but not implemented: reaction conditions (`RouteStep.conditions` is
+always `None`); a condition model can fill it without touching the search layer.
+
+```bash
+pytest          # 43 tests
+```

synomega-0.1.0/README.md

@@ -0,0 +1,138 @@
+# synomega
+
+Retrosynthesis toolkit: **single-step prediction → multi-step route planning → synthesizability scoring**.
+
+```
+synthesizability   is this target reachable from purchasable material, in N steps?
+     ↑
+search             Retro* / MCTS / best-first over an AND-OR graph
+     ↑
+singlestep         product SMILES -> ranked reactant candidates
+```
+
+The layers are decoupled by a deliberately narrow interface: a single-step
+backend only implements `predict(smiles, top_k) -> [Prediction]`. Whether it is
+a graph neural network, a transformer, or plain template matching is invisible
+to the planner.
+
+## Install
+
+```bash
+pip install -e .            # core: rdkit + numpy, no torch
+pip install -e '.[gnn]'     # adds the D-MPNN neural backend
+```
+
+The neural backend is an **optional** extra on purpose — the template-rule
+backend runs anywhere, with no GPU and no torch.
+
+## Quick start
+
+```python
+from synomega import Planner, SynthesizabilityScorer
+from synomega.singlestep import TemplateGNN
+from synomega.stock import InMemoryStock
+
+model   = TemplateGNN.from_pretrained("../ml-template-gnn/runs/uspto50k_r0_min10")
+stock   = InMemoryStock.from_keys_file("emolecules.keys.gz")
+planner = Planner(model, stock, algorithm="retrostar")
+
+result = planner.plan("CC(=O)Nc1ccccc1", max_depth=5, time_limit=60)
+print(result.solved)
+print(result.best_route.describe())
+```
+
+```
+target: CC(=O)Nc1ccccc1
+solved: True  steps: 2  depth: 2  bb_coverage: 1.00
+  [1] CC(=O)O.Nc1ccccc1>>CC(=O)Nc1ccccc1  (score=0.4348)
+  [2] O=[N+]([O-])c1ccccc1>>Nc1ccccc1  (score=0.2174)
+```
+
+### Synthesizability
+
+```python
+scorer = SynthesizabilityScorer(planner)
+
+r = scorer.score("CC(=O)Nc1ccccc1", max_steps=5)
+r.solved         # True — a complete route to purchasable material exists
+r.bb_coverage    # 1.0 — fraction of leaves that are buyable
+r.min_depth      # 2 — steps in the shortest solved route
+
+report = scorer.score_batch(targets, max_steps=5)
+report.solve_rate         # headline benchmark number
+report.mean_bb_coverage
+report.to_dataframe()
+```
+
+## The two synthesizability metrics
+
+These get conflated in the literature; synomega keeps them apart because they
+answer different questions.
+
+| Metric | Meaning | Use it for |
+|---|---|---|
+| `solved@N` / `solve_rate` | Binary: does a route of depth ≤ N exist whose leaves are **all** purchasable? | Comparing against published numbers |
+| `bb_coverage@N` | Continuous: fraction of the best route's leaves that are purchasable | Ranking molecules by how close they are |
+
+`bb_coverage` matters because most targets are unsolved at realistic step
+limits. A 5-step route with 4 of 5 leaves buyable scores 0.8, not 0 — so a
+near-miss is distinguishable from a total failure.
+
+## CLI
+
+```bash
+# one-time: precompute InChIKeys so later loads take seconds, not minutes
+synomega build-stock --catalogue emolecules.smi.gz --out emolecules.keys.gz
+
+synomega plan  --target "CC(=O)Nc1ccccc1" --model runs/uspto50k_r0_min10 \
+             --stock emolecules.keys.gz --stock-is-keys --max-steps 5
+
+synomega score --targets targets.smi --model runs/uspto50k_r0_min10 \
+             --stock emolecules.keys.gz --stock-is-keys \
+             --max-steps 5 --out report.json
+```
+
+## Search algorithms
+
+| Algorithm | Character | When |
+|---|---|---|
+| `retrostar` | Expands the frontier molecule with the lowest estimated **total route cost** (Chen et al. 2020) | Default |
+| `mcts` | UCT with greedy rollouts; tolerates an unreliable top-1 | When the single-step model is weak |
+| `bfs` | Best-first on `g + h` | Baseline, debugging |
+
+All three share the AND-OR graph, the budget, and the route extractor, so they
+are directly comparable.
+
+## Design notes
+
+**AND-OR graph, not a tree.** A molecule node is solved if it is in stock or
+*any* of its reactions is solved; a reaction is solved if *all* its reactants
+are. Molecules are interned by InChIKey, so an intermediate reached down two
+branches is one node expanded once. Cycles are rejected when the edge is
+created — a route that makes X from X is not a route.
+
+**Batched expansion.** Search is naturally "expand one node, call the model
+once", which leaves a GPU idle. The algorithms pull a batch of frontier nodes
+and issue one `predict_batch`.
+
+**Caching.** Search revisits the same molecule constantly. `Planner(cache=True)`
+(the default) memoizes expansions; `cache_path=` persists them to SQLite so the
+cache survives across runs.
+
+**Stock membership is by InChIKey**, so keys computed here match a vendor
+catalogue written by a different toolkit. There is deliberately no Bloom-filter
+backend: false positives would inflate solve-rate and quietly break
+comparability with published numbers.
+
+## Status
+
+Implemented and tested: chem layer, single-step interface + template-rule and
+D-MPNN backends, expansion cache, AND-OR graph, all three search algorithms,
+route extraction/scoring/serialization, synthesizability metrics, CLI.
+
+Reserved but not implemented: reaction conditions (`RouteStep.conditions` is
+always `None`); a condition model can fill it without touching the search layer.
+
+```bash
+pytest          # 43 tests
+```

synomega-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "synomega"
+version = "0.1.0"
+description = "Retrosynthesis toolkit: single-step prediction, multi-step route planning, synthesizability scoring"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "zbc0315" }]
+keywords = ["retrosynthesis", "cheminformatics", "synthesizability", "rdkit", "route-planning"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Chemistry",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "rdkit>=2023.3",
+    "numpy>=1.23",
+]
+
+[project.urls]
+Homepage = "https://github.com/zbc0315/synomega"
+Repository = "https://github.com/zbc0315/synomega"
+Issues = "https://github.com/zbc0315/synomega/issues"
+
+[project.optional-dependencies]
+# Neural single-step backends (D-MPNN template classifier).
+gnn = [
+    "torch>=2.0",
+    "torch_geometric>=2.4",
+    "pyyaml>=6.0",
+]
+viz = ["graphviz>=0.20"]
+dev = ["pytest>=7.0"]
+
+[project.scripts]
+synomega = "synomega.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

synomega-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

synomega-0.1.0/src/synomega/__init__.py

@@ -0,0 +1,55 @@
+"""synomega — retrosynthesis toolkit.
+
+Three layers, deliberately decoupled:
+
+    synthesizability   is this target reachable from purchasable material?
+        ↑
+    search             multi-step route planning over an AND-OR graph
+        ↑
+    singlestep         product SMILES -> ranked reactant candidates
+
+Quick start::
+
+    from synomega import Planner, SynthesizabilityScorer
+    from synomega.singlestep import TemplateGNN
+    from synomega.stock import InMemoryStock
+
+    model   = TemplateGNN.from_pretrained("runs/uspto50k_r0_min10")
+    stock   = InMemoryStock.from_file("emolecules.smi")
+    planner = Planner(model, stock, algorithm="retrostar")
+
+    result = planner.plan("CC(=O)Nc1ccccc1", max_depth=5)
+    print(result.best_route.describe())
+
+    scorer = SynthesizabilityScorer(planner)
+    print(scorer.score("CC(=O)Nc1ccccc1", max_steps=5))
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .chem import Molecule, Reaction
+from .planner import Planner
+from .route import Route
+from .search import Budget, SearchResult
+from .singlestep import Prediction, SingleStepModel
+from .stock import BuildingBlockSet, InMemoryStock
+from .synthesizability import BatchReport, MoleculeReport, SynthesizabilityScorer
+
+__all__ = [
+    "__version__",
+    "Planner",
+    "SynthesizabilityScorer",
+    "MoleculeReport",
+    "BatchReport",
+    "Route",
+    "SearchResult",
+    "Budget",
+    "Molecule",
+    "Reaction",
+    "Prediction",
+    "SingleStepModel",
+    "BuildingBlockSet",
+    "InMemoryStock",
+]

synomega-0.1.0/src/synomega/chem/__init__.py

@@ -0,0 +1,20 @@
+"""Chemistry primitives: molecules, reactions, retro-template application."""
+
+from .mol import Molecule, MoleculeError, canonicalize, inchi_key, split_components
+from .reaction import Conditions, Reaction, extract_product, parse_reaction_smiles
+from .template import TemplateLibrary, TemplateOutcome, apply_template
+
+__all__ = [
+    "Molecule",
+    "MoleculeError",
+    "canonicalize",
+    "inchi_key",
+    "split_components",
+    "Reaction",
+    "Conditions",
+    "parse_reaction_smiles",
+    "extract_product",
+    "TemplateLibrary",
+    "TemplateOutcome",
+    "apply_template",
+]

synomega-0.1.0/src/synomega/chem/features.py

@@ -0,0 +1,150 @@
+"""Atom/bond featurization for the D-MPNN template classifier.
+
+⚠️  This is a VERBATIM mirror of `ml-template-gnn/src/template_gnn/featurize.py`.
+It is vendored so synomega can run inference from a checkpoint without depending
+on the training repo. It MUST stay bit-identical to whatever produced the
+checkpoint you load — any drift silently corrupts predictions rather than
+raising, so `synomega.singlestep.template_gnn` asserts ATOM_FDIM against the
+checkpoint's first-layer weight shape.
+
+Atom features (45 dim), bond features (12 dim). See the training repo for the
+full field-by-field breakdown.
+"""
+
+from __future__ import annotations
+
+import math
+
+from rdkit import Chem
+from rdkit.Chem import AllChem, rdchem
+
+ATOM_LIST = [6, 7, 8, 9, 15, 16, 17, 35, 53]
+DEGREE_LIST = list(range(6))
+CHARGE_LIST = [-2, -1, 0, 1, 2]
+CHIRALITY_LIST = [
+    rdchem.ChiralType.CHI_UNSPECIFIED,
+    rdchem.ChiralType.CHI_TETRAHEDRAL_CW,
+    rdchem.ChiralType.CHI_TETRAHEDRAL_CCW,
+    rdchem.ChiralType.CHI_OTHER,
+]
+NUM_H_LIST = list(range(5))
+HYBRIDIZATION_LIST = [
+    rdchem.HybridizationType.SP,
+    rdchem.HybridizationType.SP2,
+    rdchem.HybridizationType.SP3,
+    rdchem.HybridizationType.SP3D,
+    rdchem.HybridizationType.SP3D2,
+]
+
+ATOM_FDIM = (
+    len(ATOM_LIST) + 1
+    + len(DEGREE_LIST) + 1
+    + len(CHARGE_LIST) + 1
+    + len(CHIRALITY_LIST)
+    + len(NUM_H_LIST) + 1
+    + len(HYBRIDIZATION_LIST) + 1
+    + 1  # is_aromatic
+    + 1  # is_in_ring
+    + 1  # mass
+    + 1  # chi_pauling / 4
+    + 1  # q_gasteiger (masked)
+    + 1  # q_valid
+)
+
+PAULING_EN = {
+    1: 2.20, 3: 0.98, 4: 1.57, 5: 2.04, 6: 2.55, 7: 3.04, 8: 3.44, 9: 3.98,
+    11: 0.93, 12: 1.31, 13: 1.61, 14: 1.90, 15: 2.19, 16: 2.58, 17: 3.16,
+    19: 0.82, 20: 1.00, 26: 1.83, 27: 1.88, 28: 1.91, 29: 1.90, 30: 1.65,
+    33: 2.18, 34: 2.55, 35: 2.96, 47: 1.93, 50: 1.96, 53: 2.66,
+    78: 2.28, 79: 2.54, 80: 2.00,
+}
+
+BOND_TYPE_LIST = [
+    rdchem.BondType.SINGLE,
+    rdchem.BondType.DOUBLE,
+    rdchem.BondType.TRIPLE,
+    rdchem.BondType.AROMATIC,
+]
+STEREO_LIST = [
+    rdchem.BondStereo.STEREONONE,
+    rdchem.BondStereo.STEREOANY,
+    rdchem.BondStereo.STEREOZ,
+    rdchem.BondStereo.STEREOE,
+    rdchem.BondStereo.STEREOCIS,
+    rdchem.BondStereo.STEREOTRANS,
+]
+
+BOND_FDIM = len(BOND_TYPE_LIST) + 1 + 1 + len(STEREO_LIST)
+
+
+def _one_hot(value, choices, allow_other: bool = True) -> list[int]:
+    feat = [0] * (len(choices) + (1 if allow_other else 0))
+    try:
+        idx = choices.index(value)
+    except ValueError:
+        if not allow_other:
+            return feat
+        idx = len(choices)
+    feat[idx] = 1
+    return feat
+
+
+def compute_gasteiger(mol: Chem.Mol) -> bool:
+    """Annotate Gasteiger charges in place; False when RDKit refuses."""
+    try:
+        AllChem.ComputeGasteigerCharges(mol)
+        return True
+    except Exception:
+        return False
+
+
+def atom_features(atom: Chem.Atom) -> list[float]:
+    z = atom.GetAtomicNum()
+    chi = PAULING_EN.get(z, 2.0) / 4.0
+
+    q = 0.0
+    q_valid = 0
+    if atom.HasProp("_GasteigerCharge"):
+        raw = atom.GetDoubleProp("_GasteigerCharge")
+        if math.isfinite(raw):
+            q = raw
+            q_valid = 1
+
+    return (
+        _one_hot(z, ATOM_LIST)
+        + _one_hot(atom.GetTotalDegree(), DEGREE_LIST)
+        + _one_hot(atom.GetFormalCharge(), CHARGE_LIST)
+        + _one_hot(atom.GetChiralTag(), CHIRALITY_LIST, allow_other=False)
+        + _one_hot(atom.GetTotalNumHs(), NUM_H_LIST)
+        + _one_hot(atom.GetHybridization(), HYBRIDIZATION_LIST)
+        + [1 if atom.GetIsAromatic() else 0]
+        + [1 if atom.IsInRing() else 0]
+        + [atom.GetMass() * 0.01]
+        + [chi, q, float(q_valid)]
+    )
+
+
+def bond_features(bond: Chem.Bond) -> list[float]:
+    return (
+        _one_hot(bond.GetBondType(), BOND_TYPE_LIST, allow_other=False)
+        + [1 if bond.GetIsConjugated() else 0]
+        + [1 if bond.IsInRing() else 0]
+        + _one_hot(bond.GetStereo(), STEREO_LIST, allow_other=False)
+    )
+
+
+def largest_fragment(mol: Chem.Mol) -> Chem.Mol:
+    frags = Chem.GetMolFrags(mol, asMols=True, sanitizeFrags=False)
+    if len(frags) == 1:
+        return mol
+    return max(frags, key=lambda m: m.GetNumHeavyAtoms())
+
+
+__all__ = [
+    "ATOM_FDIM",
+    "BOND_FDIM",
+    "atom_features",
+    "bond_features",
+    "compute_gasteiger",
+    "largest_fragment",
+]