Mol qc

mol-qc — validity / synthesizability gate for generated molecules

A deterministic, legible validity / synthesizability / drug-likeness DRC for molecules a generative-chemistry model proposes. It catches what such a model can get wrong — an invalid valence that won't parse, a structure no chemist could synthesize, properties so extreme it isn't a small molecule — and returns a named reason for every flag, not just a score. No GPU, no network.

This is the programmatic version of the "inspect the molecule" sanity check generative-chemistry tools tell you to do by eye. The verdict separates disclosure from condemnation: the gate fails only broken or unmakeable molecules; structural alerts and drug-likeness notes are advisory disclosures, because PAINS / Rule-of-5 have well-known false positives (many marketed drugs hit them). Thresholds are medicinal-chemistry conventions — zero parameters fitted to accuracy.

contract	tier	catches
INVALID_MOLECULE	fails	does not parse / sanitize (bad valence or syntax)
UNSYNTHESIZABLE	fails	Ertl synthetic-accessibility score above the cap (not reasonably makeable)
EXTREME_PROPERTY	fails	egregiously out of small-molecule range (MW > 900 / cLogP > 7)
STRUCTURAL_ALERT	discloses	PAINS / Brenk hits (assay-interference / reactive — advisory)
LIPINSKI_RO5	discloses	≥2 Rule-of-5 violations (drug-likeness note)
VEBER	discloses	rotatable bonds > 10 / TPSA > 140 (oral-bioavailability note)

Install

pip install "karyon[chem]"      # pulls rdkit

Usage

Gate a single generated molecule (inline SMILES), or a batch in a .smi file (one SMILES per line, optional name):

karyon qualify "CC(=O)Oc1ccccc1C(=O)O" --modality mol    # one molecule (inline → modality required)
karyon qualify generated.smi --modality mol              # a batch (.smi)
karyon qualify generated.smi --modality mol --json       # machine-readable, for an agent to branch on

Output is a PASS / FAIL verdict plus, per molecule, one line per fired contract — · for a disclosed advisory, ✗ for a condemning one. The exit code is non-zero on FAIL, so it gates a pipeline directly. --json emits the stable spine schema ({modality, ok, items:[{name, ok, score, reasons}], batch}); a molecule passes iff score == 0 (the disclose-tier alerts carry weight 0).

From Python:

from karyon import qualify
r = qualify("generated.smi", modality="mol")             # or qualify("CC(=O)O...", modality="mol")
for name, v in r.items:                                   # e.g. GenMol / MolMIM output
    if v.score > 0:
        print(f"REJECT {name} — {v.messages}")

Composition with NVIDIA BioNeMo

Install alongside genmol-nim (or the MolMIM generator): the model proposes molecules, this skill qualifies the batch, so the agent only carries forward valid, makeable candidates and can explain every rejection. It complements the generator's advisory validation with a programmatic verdict — it qualifies the output, it does not generate molecules.

Validation

Three pre-registered predictions (PI-1 and PI-2 PASS; PI-3 descriptive):

prediction	result
PI-1 instrument — real drugs pass, planted/invalid decoys flagged	AUROC 1.000, flag-decoy 100%, real-drug pass 99% (92 approved drugs)
PI-2 faithful — the gate faithfully composes the canonical RDKit primitives	composition correctness 100% (gate INVALID/ALERT == fresh canonical RDKit calls) + owned Rule-of-5 100% vs hand computation
PI-3 effect — defect rates per generator (descriptive)	un-gated raw SMILES ~100% invalid (the validity gate's headline catch); a structure-aware generator (BRICS) is valid but carries structural alerts ~19% — a weak-condemn / high-disclose gate

Honest posture (disclosed): RDKit is the cheminformatics engine here — so mol-qc composes canonical primitives (sanitization, descriptors, the PAINS/Brenk FilterCatalog, the Ertl SA score) into a legible deterministic gate rather than reimplementing them. Its faithfulness is correct composition + correct owned rules (both 100%), not an independent reimplementation; an attempted independent complexity corroboration (SA vs RDKit BertzCT) is weak (ρ≈0.36 — the two measure complexity differently) and is reported, not claimed. Qualification, not accuracy.

Scope (honest)

A fast, legible validity / synthesizability / drug-likeness gate (the cheap, certain checks), not a binding-affinity, ADMET, or potency predictor. It owns the single-molecule axis; pair it with receptor-aware or property-prediction tooling for the quantitative axes.