Predictive thermodynamics: pluggable dG'/dGf backends (equilibrator, dGPredictor, ModelSEED-DB)

[VibhavSetlur]

Summary

Adds a PredictiveThermoUtils facade that estimates standard transformed Gibbs energies of formation (compounds) and reaction (Δ_r G'°) by dispatching across a priority-ordered set of pluggable backends. Every backend degrades gracefully and never fabricates a value — unknown inputs return None plus a warning, so callers always know provenance.

Exposed as the lazy predictive_thermo property on KBUtilLib.

Backends (src/kbutillib/thermo_predictors/)

backend	source	notes
equilibrator	live component-contribution (equilibrator-api, optional dep)	condition-aware: pH, ionic strength, T, p_Mg
dgpredictor	Maranas/Tyo group-contribution reaction predictor (Freiburger fork)	runs out-of-process against a local clone to keep rdkit/openbabel + the ~150 MB model out of this process; KEGG stoichiometry in, kJ/mol Δ_r G'° out; detects a missing / Git-LFS-pointer model and reports unavailable
modelseed_db	baked transformed ΔG from the expanded-eQuilibrator ModelSEED Database fork	reads compounds.tsv/reactions.tsv directly with the stdlib csv reader; kcal→kJ; fixed pH 7 / I 0.25 M / 298.15 K; EQU/EQC/EQP provenance gate
modelseed	existing ThermoUtils ModelSEED lookups	always-on fallback, no new dependency
molgpk	Tyo-lab molGPK / OPAM2 (unreleased)	stub; reports unavailable until configured

Dispatch order: equilibrator → dgpredictor → modelseed_db → modelseed.

Design invariants

• Nothing in the subpackage imports a heavy/optional dependency at module-import time; all such imports are deferred into the backend that needs them.
• Backends never raise at construction when a dependency is absent.
• No-fabrication: unknown → None + warning, never a stand-in value.
• Heavy/fragile research code (dGPredictor) is isolated behind a subprocess worker, configured via thermo.dgpredictor.repo_path / DGPREDICTOR_REPO (and thermo.dgpredictor.python); modelseed_db via thermo.modelseed_db.biochem_root / MODELSEED_DATABASE_BIOCHEM_ROOT.

Packaging & tests

• Adds [project.optional-dependencies] equilibrator / thermo extras (core install unchanged).
• New dependency-free suite tests/test_predictive_thermo.py (22 passing, 1 skipped): graceful degradation, the no-fabrication invariant, dispatch fall-through, backend-status reporting, and kcal→kJ conversion against worked ATP / rxn00001 values.

Live validation (local)

• equilibrator ATP+H2O→ADP+Pi: -30.11 ± 0.30 kJ/mol @ pH7/I0.25/298.15 K
• dgpredictor same reaction: -26.14 ± 3.29 kJ/mol (agrees within model uncertainty)
• modelseed_db ATP cpd00002: -2296.39 kJ/mol (-548.85 kcal × 4.184); rxn00001: -14.48 kJ/mol

ruff clean on all touched files.

[VibhavSetlur]

Closing for now — keeping this branch open as a draft of work-in-progress rather than a review-ready PR. The predictive-thermodynamics layer is complete, but I'm holding the PR until the full thermo + cheminformatics scope is finished so it lands as one coherent, reviewable unit. The feature branch (VibhavSetlur:feature/thermo-cheminformatics-foundation) stays pushed; I'll reopen / re-file once everything is done.