feat(verab): methoxy-aromatic O-demethylation rule discovery + genome degradation screening (Pickaxe)

[VibhavSetlur]

Summary

Implements the verAB use case from the AI meeting: discover the Pickaxe rule(s) that reproduce verAB aromatic O-demethylation, then screen methoxylated aromatic compounds against genome gene content to predict degradation capability (ADP1 and others). Wraps Pickaxe / MINE-Database (Shebek et al. 2023; mechanism-informed operators, Pate et al. 2026) in KBUtilLib under a single kbu.verab facade + kbu verab CLI, and emits reproducible KING coscientist input files + prompts.

⚠️ Stacks on #47. This branch is built on top of PR #47 (unified thermodynamics/cheminformatics), which is still open. Until #47 merges, this PR's diff also shows #47's commits. Merge #47 first, then this diff reduces to the verAB-only changes (23 files, ~6.6k lines). The verAB-only commits are 3fa9a63 → e235519.

The scientific workflow (Dr. Henry's ask)

Phase 1 — verAB rule discovery

• Canonical SMILES for the 5 seeds baked in: vanillate, isovanillate, guaiacol, 4-methoxybenzoate, veratrate.
• kbu verab discover runs Pickaxe expansion and identifies which operator(s) realize Ar-OCH3 → Ar-OH + HCHO, using the operator provenance Pickaxe records per reaction.
• Rule matching is structural (RDKit reaction-pattern match), with a text-match fallback when RDKit is absent.
• Emits KING coscientist artifacts (kbu verab emit-king): seeds.tsv/csv, discovered_rules.tsv, target_transformation.txt, prompt.md, manifest.json — ready to submit to KING.

Phase 2 — genome/degradation screening

• kbu verab enumerate: RDKit substructure scan over the ModelSEED biochem DB to find ALL methoxylated aromatics (works around the exact-match-only compound search).
• kbu verab screen: for each predicted product answers (a) is the reaction already in the DB? (b) is the product in the DB? (c) does the product have a downstream degradation pathway? (d) is that pathway in our models?
• predict_genome_degradation: maps the operator's EC (default EC 1.14.13.82, vanillate monooxygenase) to gene content per genome (ADP1 etc.) to predict which genomes can degrade which compounds.

API surface

kbu.verab.seed_compounds()                 # the 5 canonical methoxy-aromatic seeds
kbu.verab.discover_rules(generations=1)     # -> VerabDiscoveryResult (firing operators + confidence + EC hint)
kbu.verab.enumerate_methoxy_aromatics()     # RDKit substructure scan of biochem DB
kbu.verab.screen(...)                        # cross-reference products vs DB / models
kbu.verab.emit_king_workflow(outdir=...)     # KING coscientist input files + prompt
kbu.verab.status()                           # rdkit / minedatabase / backend availability

CLI: kbu verab discover|enumerate|screen|emit-king (all support --json).

Architecture

• New sub-package src/kbutillib/cheminformatics/verab/ (smarts, models, substructure, rule_discovery, screening, king_artifacts) — extends the existing real PickaxeBackend, never duplicates minedatabase calls.
• src/kbutillib/verab_utils.py facade (VerabUtils/VerabUtilsImpl) composed from network_expansion + biochem + model + genome + annotation, wired as a lazy kbu.verab toolkit property.
• Optional KING app bundle at src/kbutillib/king_app_verab/.
• No top-level rdkit/minedatabase imports anywhere — full graceful degradation via BackendUnavailableError.

Dependencies / Python

• RDKit is optional (pip install KBUtilLib[cheminformatics] or conda). minedatabase's python_requires<3.10 is a pip-metadata gate only — bypassed by KBUtilLib's DependencyManager sys.path injection (runs on 3.11/3.12). MINE-Database resolves via dependencies.yaml. Documented in docs/thermo-cheminformatics/INSTALL.md.

Tests

• 158 passed / 13 skipped across the verAB suite (unit tests use fake backends; the 13 skips are the gated live-integration test + RDKit-absent-path tests).
• tests/test_verab.py, test_verab_screening.py, test_verab_king.py, test_verab_cli.py, test_verab_king_bundle.py, and gated test_verab_live.py (real MINE-Database + RDKit; KBUTILLIB_LIVE_CHEM=1).
• Zero new failures in the broad suite: verified against a pristine upstream/main worktree — baseline 339 failed / 1349 passed (pre-existing optional-dep gaps: cobra, requests_toolbelt, httpx, etc.); this branch 322 failed / 1572 passed (+223 passing = the new tests, −17 failures, same 59 pre-existing collection errors).

Follow-ups / deferred

• Live empirical confirmation of the exact firing operator id (test_verab_live.py) requires a MINE-Database checkout + RDKit in CI.
• The Pate-2026 mechanism-informed operator set isn't packaged in stock minedatabase; supported via a custom rule_list (config cheminformatics.verab.operator_rule_tsv); the operator is confirmed empirically, not hardcoded.
• Phase-2 substructure scan depends on ModelSEED SMILES coverage; compounds lacking SMILES are skipped with counts.

---

Update: mechanism-informed operators + robustness hardening

Following a critical self-audit against Dr. Henry's exact asks, five fixes were added so the feature genuinely delivers the requested scientific workflow (not just infrastructure):

FIX 1 (the core ask): Pate-2026 mechanism-informed operators are now the default

• Henry explicitly asked for the most accurate operators (Pate et al. 2026, JCIM). These are not bundled in stock Pickaxe. They ARE published in the paper's official data repo: stefanpate/coarse-grain-rxns (data/processed/rules/mechinferred_dt_019_rules_w_coreactants.tsv, ~14.5k operators).
• verAB now defaults to rule_set="mechinformed", resolved at runtime via cheminformatics.verab.operator_rule_tsv config → KBUTILLIB_VERAB_OPERATOR_TSV env → DependencyManager (repo added to dependencies.yaml).
• The operator TSV is NOT vendored — that repo has no LICENSE, so redistribution isn't permitted. If it isn't resolved, verAB falls back to the bundled metacyc_intermediate set (more mechanism-aware than metacyc_generalized) with an honest warning, and records the rule set actually used in the discovery result + KING manifest.
• Coreactant roles (WATER, METHYL_DONOR_CoF, …) are resolved from a KBUtilLib-authored role→SMILES table (our own code, not repo data) or a user-supplied operator_coreactant_tsv.
• The verAB O-demethylation operator is still confirmed empirically via RDKit at runtime (candidate ids 2783_1/7534_1/4304_1 recorded only as hints, never hardcoded as the answer).
• Install steps documented in docs/thermo-cheminformatics/INSTALL.md.

FIX 2: firing-operator attribution preserved as a list

Pickaxe reactions can fire multiple operators; the ingest previously collapsed them to one ;-joined string. Now PredictedReaction.operators keeps the full list (scalar operator retained for back-compat), so per-operator attribution isn't lost through discovery/screening/KING.

FIX 3: phase-2 screening distinguishes lookup FAILURE from not-found

DB query errors were silently swallowed to {} (false negatives). ScreeningRecord now carries lookup_ok + lookup_errors, so a failed lookup is visible instead of being reported as "not in DB".

FIX 4: genome degradation prediction is multi-EC + explainable

Was single hardcoded EC (1.14.13.82) + a bare bool. Now checks multiple EC terms (derivable from operators), and reports which EC/MSRXN matched which gene/feature per genome, keeping 1.14.13.82 only as a fallback hint.

FIX 5: KING artifacts aligned + honest

Consolidated the installable KING bundle to src/kbutillib/king_app/verab/ (validates against king_install.load_bundle); the manifest records the actual rule set used; prompt.md honestly states the dir is reproducible inputs + a ready-to-run prompt (not itself a KING bundle) and names the mechanism-informed default + fallback.

Tests

255 passed / 20 skipped across the cheminformatics + thermo + verab surface; no regressions. New unit tests cover operator resolution precedence, TSV normalization, fallback + honest warning, operator-list preservation, lookup-failure vs not-found, and multi-EC explainable genome prediction. The gated live test (KBUTILLIB_LIVE_CHEM=1 + RDKit + a MINE-Database/operator checkout) empirically confirms the firing operator.

Honest limitations (not yet delivered)

• Empirical confirmation of the exact mechanism-informed operator id requires running the live path (RDKit + minedatabase + the cloned operator TSV). Offline/CI runs use the metacyc_intermediate fallback and say so.
• The coreactant role→SMILES table is best-effort; cofactor-sensitive expansions may benefit from a user-curated operator_coreactant_tsv.
• Phase-2 substructure enumeration depends on ModelSEED SMILES coverage; compounds without SMILES are skipped (counted).
• KING compatibility is validated against load_bundle's schema; end-to-end execution inside KING coscientist has not been run here.