tooluniverse-natural-product-dereplication

# Natural Product Dereplication & Chemotaxonomy

Decide whether a putative natural product is **already known**, identify the **microbe that produces it**, attach the **literature reference**, and assign its **ChemOnt chemical class**. This is the dereplication question every NP chemist and metabolomics analyst asks of a new feature: *"have we seen this before, and what makes it?"*

**LOOK UP DON'T GUESS**: Never assume an NPAID, producing organism, exact mass, or chemical class. Every identity, provenance, and taxonomy claim must come from a live tool call.

**Scope (microbial NPs only)**: NPAtlas covers natural products from **bacteria and fungi**. It does NOT cover plant, animal, or marine-invertebrate metabolites unless a microbial producer was reported. A "no NPAtlas hit" therefore means *not a known microbial NP* — it does not prove the molecule is novel in an absolute sense.

---

## Backing Tools (all keyless; verify before quoting)

| Tool | Input | Returns |
|------|-------|---------|
| `NPAtlas_search_compounds` | `name` / `inchikey` / `formula` / `smiles`, `limit` | list of {npaid, name, molecular_formula, molecular_weight, exact_mass, inchikey, smiles}. (origin_organism is `null` here — fetch the full record for provenance) |
| `NPAtlas_get_compound` | `npaid` (e.g. `NPA014588`) | full record incl. `origin_organism` (producing microbe + taxonomic lineage) and `origin_reference` (title/doi/journal/year) |
| `ClassyFire_classify_by_inchikey` | `inchikey` (full 27-char) | ChemOnt kingdom→superclass→class→subclass→direct_parent, molecular_framework, substituents. `classified:false` if not in cache |
| `OPSIN_name_to_structure` | `name` (systematic IUPAC) | smiles / inchi / inchikey. `parsed:false` for trade/trivial names |
| `PubChem_get_CID_by_compound_name` | `name` | `{IdentifierList:{CID:[...]}}` |
| `PubChem_get_compound_properties_by_CID` | `cid`, `properties` (e.g. `["MolecularFormula","MolecularWeight","InChIKey","IUPACName"]`) | property table — use to obtain an InChIKey for arbitrary compounds |

---

## Workflow

```
Phase 0: Classify input — name / formula / exact mass / InChIKey / SMILES?
Phase 1: Obtain an InChIKey (the universal key for ClassyFire & precise NPAtlas match)
Phase 2: Dereplicate against NPAtlas (known microbial NP? which organism? which paper?)
Phase 3: Assign ChemOnt chemical class via ClassyFire
Phase 4: Cross-reference identity in PubChem
Phase 5: Report — known/novel call + provenance + class hierarchy + interpretation note
```

### Phase 0 — Classify the input

- **Full InChIKey** (27 chars, `XXXXXXXXXXXXXX-XXXXXXXXXX-X`) → skip to Phase 2; it is already the universal key.
- **Molecular formula / exact mass** → go straight to NPAtlas formula search (Phase 2); these are the rawest dereplication inputs (typical of an untargeted MS feature).
- **SMILES** → usable directly in `NPAtlas_search_compounds(smiles=...)`; also feed to PubChem for an InChIKey.
- **Systematic IUPAC name** (e.g. `2-acetyloxybenzoic acid`) → Phase 1 via OPSIN.
- **Trivial / trade / common name** (e.g. `staurosporine`, `penicillin`) → Phase 1 via PubChem (OPSIN will return `parsed:false` for these).

### Phase 1 — Obtain an InChIKey

```python
# Systematic IUPAC name → structure (OPSIN). parsed:false ⇒ fall through to PubChem.
op = tu.tools.OPSIN_name_to_structure(name="2-acetyloxybenzoic acid")
inchikey = op["data"]["inchikey"]  # only if op["data"]["parsed"]

# Trivial/common name → PubChem CID → properties (incl. InChIKey)
cid = tu.tools.PubChem_get_CID_by_compound_name(name="staurosporine")["data"]["IdentifierList"]["CID"][0]
props = tu.tools.PubChem_get_compound_properties_by_CID(
    cid=cid, properties=["MolecularFormula","MolecularWeight","InChIKey","IUPACName"])
inchikey = props["data"]["PropertyTable"]["Properties"][0]["InChIKey"]
```

The InChIKey is what makes dereplication exact: an InChIKey match is a structure match; a name match is not (synonyms, analogs, and salts share names).

### Phase 2 — Dereplicate against NPAtlas

Search by the most specific key available. Prefer **InChIKey** (exact structure), then **formula** (catches isomers — useful for an MS feature with only a formula), then **name** (loosest — returns analogs).

```python
# Exact, structure-level
hits = tu.tools.NPAtlas_search_compounds(inchikey="HKSZLNNOFSGOKW-FYTWVXJKSA-N", limit=5)
# MS-feature style (formula or exact mass) — expect multiple isomeric hits
hits = tu.tools.NPAtlas_search_compounds(formula="C28H26N4O3", limit=10)
```

For each candidate NPAID, fetch the **full record** to get the producing organism and reference (search results carry `origin_organism: null`):

```python
rec = tu.tools.NPAtlas_get_compound(npaid="NPA014588")["data"]
organism   = rec["origin_organism"]["name"]            # e.g. "Streptomyces"
lineage    = rec["origin_organism"]["ancestors"]       # domain→...→family
reference  = rec["origin_reference"]                    # title, doi, journal, year
```

### Phase 3 — Assign ChemOnt chemical class

```python
cf = tu.tools.ClassyFire_classify_by_inchikey(inchikey=inchikey)["data"]
# cf["kingdom"], cf["superclass"], cf["class"], cf["subclass"], cf["direct_parent"]
# cf["molecular_framework"], cf["substituents"]
```

If `classified:false`, the InChIKey is not in the ClassyFire cache — report the class as *unavailable* (do not invent one). A correct InChIKey is required; a wrong stereo/protonation layer will miss the cache.

### Phase 4 — Cross-reference identity in PubChem

Confirm the same molecule exists in PubChem (CID, IUPAC name, formula, MW) so the identity is anchored to a second independent database. Disagreement in molecular formula between NPAtlas and PubChem is a red flag that the name/structure resolution went astray.

### Phase 5 — Report

Deliver:
1. **Dereplication call** — *Known microbial NP* (with NPAID) **or** *No NPAtlas match (possibly novel / non-microbial)*.
2. **Provenance** — producing organism + taxonomic lineage + literature reference (title,