molforge 0.3.0__tar.gz → 0.4.0__tar.gz

{molforge-0.3.0 → molforge-0.4.0}/CHANGELOG.md

@@ -7,6 +7,371 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] 2026-06-25
+
+### Added
+
+- **Provenance adoption pass 2 — MD wrappers and prep functions.**
+  Completes the wrapper-adoption work. Where
+  pass 1 demonstrated cross-wrapper chaining (ESMFold → Vina),
+  pass 2 exercises chaining **within** a single wrapper's
+  multi-step pipeline and across the composable prep functions —
+  the harder case and the one that proves the design composes.
+
+  Adopted (2 wrappers + 5 functions):
+
+  - **`molforge.wrappers.md.OpenMM`** — `prepare` / `minimize` /
+    `run` each attach a `Provenance` to the output's metadata. Each
+    step's parent is the previous step's `Provenance`, so a full
+    pipeline leaves the final `Trajectory` with a 3-deep chain
+    that reads as `["OpenMM.prepare", "OpenMM.minimize", "OpenMM.run"]`
+    oldest-first. When the input `Protein` has its own `Provenance`
+    (e.g. it came from ESMFold), the chain extends back through it
+    — a sequence-to-trajectory workflow ends with a 4-deep chain
+    that traces all the way to the sequence.
+
+  - **`molforge.wrappers.md.GROMACS`** — same three-step pattern
+    as OpenMM, with the engine strings `"GROMACS.prepare"`,
+    `"GROMACS.minimize"`, `"GROMACS.run"`. The minimize step
+    appends to `simulation.metadata` (since minimize returns the
+    same Simulation in-place, not a new one), preserving the
+    chain across the mutation.
+
+  - **`molforge.prep.{remove_heterogens, fix_missing_atoms,
+    add_caps, add_hydrogens, prepare_for_md}`** — each prep
+    function chains a `Provenance` step onto the output's
+    metadata. `prepare_for_md` (which composes the other four in
+    sequence) leaves the result with a 4-deep chain naturally:
+    `["molforge.prep.remove_heterogens",
+      "molforge.prep.fix_missing_atoms",
+      "molforge.prep.add_caps",
+      "molforge.prep.add_hydrogens"]`. No special handling needed
+    in the composite — the inner functions chain themselves.
+
+  Two helpers, both private:
+
+  - **`molforge.wrappers.md.{openmm,gromacs}._parent_provenance(meta)`**
+    — extracts a `Provenance | None` from a free-form metadata
+    dict, narrowing the type. Per-wrapper rather than shared so
+    each MD wrapper stays self-contained.
+
+  - **`molforge.prep._provenance.chain_prep_provenance(output, *,
+    engine, parameters, input_protein)`** — the DRY-up for the
+    five prep functions. One place to evolve the prep-side
+    provenance shape later (e.g. when we want to also stamp the
+    PDBFixer / OpenMM versions used).
+
+  Backwards compatibility: every existing ad-hoc metadata key
+  (`metadata["engine"]`, `metadata["run_dir"]`, `metadata["emtol"]`,
+  etc.) is preserved unchanged. The new `metadata[PROVENANCE]` is
+  additive.
+
+  Tests (`tests/unit/wrappers/test_provenance_adoption.py`, 8 new
+  in addition to the 11 from pass 1):
+
+  - `TestOpenMMProvenanceChain` (2 tests) drives a full prepare →
+    minimize → run pipeline against a real OpenMM install
+    (skipped if openmm missing). The headline scenario
+    `["ESMFold", "OpenMM.prepare", "OpenMM.run"]` is exercised
+    end-to-end.
+
+  - `TestGROMACSProvenanceWiring` (2 tests) — GROMACS needs the
+    `gmx` binary which CI usually lacks. The tests inspect the
+    module source to assert the three step engine strings appear
+    and that `_parent_provenance(...)` is used — a regression net
+    that catches future code that bypasses the helper without
+    needing the real engine to run.
+
+  - `TestPrepProvenanceChain` (4 tests) — exercises each prep
+    function individually, then a two-function chain, then the
+    full `prepare_for_md` 4-step chain, then the "ESMFold + 4
+    prep steps" 5-deep chain (the most realistic scenario).
+    Skipped if openmm + pdbfixer aren't both installed.
+
+  With pass 2 complete, the headline scenario from the roadmap
+  ("20 designs from ProteinMPNN, docked with Vina, refined with
+  OpenMM") is now fully traceable: every output object's
+  `metadata[PROVENANCE].chain()` reads as the producer pipeline,
+  with sufficient detail in each step's `parameters` to
+  reconstruct the exact call. The remaining provenance work is
+  optional polish: persistence to a sidecar format, hash-keyed
+  caching (the next roadmap item), and richer engine-version
+  introspection.
+
+- **Provenance adoption across folding, docking, and generative
+  wrappers (pass 1).** Builds on the `Provenance` surface added in
+  `9fafbba`. Every wrapper in scope now attaches a `Provenance` to
+  the output's `metadata[PROVENANCE]` alongside its existing ad-hoc
+  keys, so the "20 designs from ProteinMPNN, docked with Vina"
+  scenario is now traceable end-to-end.
+
+  Wrappers adopted:
+    - **Folding**: ESMFold, AlphaFold, Boltz, RoseTTAFold. Each
+      records its `__init__` config (model name, device, msa mode,
+      recycles, etc.) in `parameters` and the input sequence in
+      `inputs`. Folding has no upstream wrapper, so `parent` is
+      `None`.
+    - **Docking**: Vina, DiffDock. Each `DockingResult.metadata`
+      gets a `Provenance` covering the run (box, exhaustiveness,
+      seed, etc. in `parameters`; receptor + ligand refs in
+      `inputs`); when the receptor was a `Protein` with its own
+      `Provenance`, that becomes the `parent` so a Vina pose
+      docked against an ESMFold prediction chains back to the
+      sequence. Per-pose `Pose.metadata` keeps existing per-pose
+      keys (`confidence`, `source_file`) — poses aren't
+      independently produced, so they share the result-level
+      provenance rather than each carrying their own.
+    - **Generative**: RFdiffusion, ProteinMPNN. Each returned
+      design (a `Protein` for RFdiffusion, a `DesignedSequence`
+      for ProteinMPNN) gets its own `Provenance` — all designs
+      from one call share the same Provenance object (frozen +
+      immutable, so by-reference sharing is safe). `design_index`
+      stays as a separate metadata key, not part of `parameters`,
+      since it identifies *which* design rather than the engine
+      config.
+    - **`molforge.io.load_alphafold`**: the loader helper. The
+      engine name reflects that this is the loader, not the
+      AlphaFold run itself (`engine="load_alphafold"`); the file
+      path goes in `inputs["path"]`.
+
+  Existing ad-hoc metadata keys are preserved across every change
+  — `metadata["engine"]`, `metadata["source_sequence"]`,
+  `metadata["source_args"]`, etc. continue to work for 1.x
+  backwards compatibility. The new `metadata[PROVENANCE]` is
+  *additive*, not a replacement, until 2.x.
+
+  Two wrapper-side surface changes worth noting:
+    - `Vina._parse_poses_pdbqt` and `DiffDock._parse_outputs`
+      gained optional `provenance_parameters` /
+      `provenance_inputs` / `provenance_parent` kwargs (and
+      DiffDock additionally `receptor_ref` / `ligand_ref`). The
+      kwargs are optional so legacy tests calling the parsers
+      directly without those refs still work — they just don't
+      get a Provenance attached. The main `dock()` entry points
+      always pass them.
+    - The `Vina` module gained a `_provenance_ref` helper for
+      converting a `Protein | str | PathLike` to a JSON-native
+      string identifier.
+
+  Tests (`tests/unit/wrappers/test_provenance_adoption.py`, 11
+  new): one assertion per adopted wrapper plus a parent-chaining
+  integration test that exercises the headline scenario
+  (`ESMFold -> Vina` chain). Each adoption test holds the wrapper
+  to a uniform contract: `engine` matches the documented name,
+  `parameters` contains every promised key, `inputs` contains the
+  expected input identifier(s). The chaining test confirms
+  `result.metadata[PROVENANCE].chain()` reads as
+  `["ESMFold", "Vina"]` oldest-first.
+
+- **First-class provenance tracking: `molforge.core.Provenance`.** A
+  raw PDB and a folded AlphaFold prediction look identical at the
+  AtomArray level; the only difference is *how the structure was
+  produced*. Pre-existing engine wrappers already wrote some of this
+  information into `metadata` ad-hoc — ESMFold sets
+  `metadata["engine"] = "ESMFold"`, RFdiffusion sets
+  `metadata["source_args"]` — but the keys are scattered, the shapes
+  disagree across engines, and there's no concept of a *parent*
+  output, so a chain of operations (fold -> dock -> MD) is not
+  traceable. This commit canonicalises the shape.
+
+  The new `Provenance` dataclass (frozen, JSON-round-trippable) has:
+    - **`engine`** — producer name; an engine ("ESMFold", "Vina")
+      or a molforge function path ("molforge.prep.prepare_for_md").
+    - **`engine_version`** — engine's own version string.
+    - **`molforge_version`** — auto-filled from `molforge.__version__`.
+    - **`timestamp`** — ISO-8601 UTC, auto-filled.
+    - **`parameters`** — engine-specific arguments (must be
+      JSON-native; validated eagerly at construction so a wrapper
+      can't smuggle in a `Path` or NumPy array that crashes much
+      later at serialisation).
+    - **`inputs`** — identifiers of the input data (e.g.
+      `{"sequence": "MKTVRQ..."}`, `{"receptor": "/path/to.pdb"}`).
+    - **`parent`** — the provenance of the input this step
+      *consumed*. Recursively a `Provenance` or `None`. This is what
+      makes the system compositional: walking the parent chain
+      reconstructs the whole history.
+
+  Construction goes through `Provenance.from_engine(engine=...,
+  parameters=..., inputs=..., parent=...)` which auto-fills the two
+  version fields and the timestamp so wrappers don't have to think
+  about them. The dataclass is frozen — mutating an attached
+  provenance would corrupt the audit trail; use `.replace(**changes)`
+  to derive an amended copy.
+
+  Traversal helpers: `walk()` yields self then ancestors newest-first;
+  `chain()` returns the same list oldest-first (suitable for printing
+  as a left-to-right pipeline); `depth` is the step count.
+
+  Serialisation: `to_dict()` / `from_dict()` give a stable plain-dict
+  shape with parents nested recursively; `to_json()` / `from_json()`
+  are JSON convenience wrappers. The on-disk shape is part of the
+  stability commitment.
+
+  The new `metadata_keys.PROVENANCE = "provenance"` constant is the
+  documented key; `ProteinMetadata` TypedDict declares it. The
+  intended use is `protein.metadata[mk.PROVENANCE] = prov`.
+  **Wrappers are NOT updated in this commit** — that's deliberately
+  separate work. The existing ad-hoc `metadata["engine"]` keys
+  continue to work for the 1.x series; engines opt into the
+  `Provenance` system gradually.
+
+  *NOT persisted through PDB / mmCIF writers* — those preserve only
+  the six documented IO header keys (per the mmCIF audit in
+  `c3a012e`). Provenance is an in-memory concept; users wanting
+  persistence serialise via `to_json` to a sidecar file. This is a
+  documented limitation, not a bug. A future "molforge bundle"
+  format could carry provenance alongside structure data; out of
+  scope here.
+
+  33 new tests in `tests/unit/core/test_provenance.py` covering
+  construction (minimal, autofill, defensive copies, parent),
+  strict JSON-input validation, immutability (FrozenInstanceError +
+  `.replace`), traversal (walk / chain / depth), serialisation
+  (dict shape, JSON round-trip, missing-engine error, forward-
+  compatible deserialisation of older shapes), equality, and the
+  metadata-key integration. Module coverage 96.8%; the residual
+  two lines are a defensive `_molforge_version` exception fallback.
+
+- **mmCIF writer round-trip audit and fidelity fixes.** A systematic
+  audit of `write_cif_string` against every PDB fixture in the repo
+  surfaced five concrete fidelity bugs in the pre-audit writer; all
+  five are now fixed.
+    1. **`model_id == 0` was clobbered to 1.** The old writer used
+       `int(model_id) or 1`, which turned every single-model PDB's
+       `model_id=0` (the `read_pdb` convention for files without
+       MODEL records) into 1 on write. The reader's matching
+       `or 1` default reinforced the change — every PDB → CIF
+       round-trip silently lost the convention. Writer now emits
+       the value verbatim; reader's default flipped from 1 to 0.
+       *Affected every PDB fixture (19/19) before the fix.*
+    2. **Partial / non-integer charges were truncated to int.** The
+       old writer emitted `f"{int(charge):d}"`, turning typical
+       PDBQT / PQR partial charges like `-0.297` into `0` and
+       `-1.5` into `-1`. Writer now emits `f"{charge:.4f}"` (4
+       decimal places preserves enough precision for typical
+       force-field partial charges); zero still emits the `?`
+       sentinel so "no charge information" round-trips cleanly.
+    3. **`metadata['classification']` and `metadata['deposition_date']`
+       not emitted at all.** Both PDB HEADER fields were captured
+       by `read_pdb` and dropped by `write_cif`. Writer now emits
+       `_struct_keywords.text` for classification and
+       `_pdbx_database_status.recvd_initial_deposition_date` for
+       the deposition date; reader picks them up symmetrically.
+    4. **`_entry.id` and `data_<id>` block name could disagree.**
+       The old writer used `protein.name` for the block name but
+       `metadata[pdb_id]` for `_entry.id`. When those differed, the
+       reader's `_entry.id` won and silently rewrote both fields on
+       round-trip (e.g. dipeptide.pdb's `name='dipeptide'` became
+       `'TEST'` because the HEADER's PDB id was `TEST`). The fix
+       uses one chosen identifier — preferring `metadata[pdb_id]`,
+       falling back to `protein.name`, then `"molforge"` — for both.
+       Identifiers with embedded whitespace (which `read_pdb`
+       tolerates from malformed HEADER lines) are now quoted in
+       `_entry.id` even though the block name has to substitute
+       underscores, so `pdb_id` whitespace survives round-trip.
+       When no `pdb_id` exists at all, the writer emits the
+       `_entry.id .` mmCIF sentinel and the reader knows to leave
+       `metadata[pdb_id]` absent rather than manufacturing one from
+       the block name.
+    5. **`serial == 0` was clobbered to `i+1`.** Latent twin of #1;
+       no fixture triggered it but the bug was there. Same fix
+       pattern: only synthesize a default when `serial <= 0`.
+  38 new tests in `tests/unit/io/test_mmcif.py` codify each fix as
+  a regression guard. The `TestFixtureSweep` parametrized test
+  iterates every PDB fixture in the repo and asserts that
+  coordinates, residue/chain/atom-name fields, residue_id, model_id,
+  serial, insertion_code, altloc, record_type, entity_type, and the
+  six tracked metadata keys all survive a PDB → CIF → in-memory
+  round-trip. Three classes — `TestEntryIdAndBlockNameConsistency`,
+  `TestAltlocRoundTrip`, and `TestFixtureSweep` — explicitly
+  document the two structural mmCIF limitations: (a) `Protein.name`
+  is recovered from `metadata[pdb_id]` on round-trip because mmCIF
+  carries only one identifier slot, and (b) altloc round-trip
+  requires the caller to pass `altloc="all"` (the default strategy
+  collapses to highest-occupancy and drops the label). Module
+  coverage at 82.9%; the residual misses are defensive error
+  branches in the tokenizer and reader.
+- **Trajectory I/O: `read_trajectory`, `iter_trajectory`,
+  `write_trajectory`.** `Trajectory` was previously in-memory only —
+  any real MD trajectory bigger than RAM had no way into molforge.
+  This commit adds binary-trajectory I/O wrapping mdtraj, exposed
+  from `molforge.io`. Supported formats are everything mdtraj
+  handles: `.xtc` (GROMACS lossy, the common case), `.trr` (GROMACS
+  lossless), `.dcd` (CHARMM / NAMD / OpenMM), `.nc` / `.netcdf`
+  (AMBER), `.h5` / `.h5md` (HDF5-based), and multi-MODEL PDB. Three
+  functions: `read_trajectory(path, topology=..., stride=1,
+  atom_indices=None)` loads a whole file into a
+  `molforge.md.Trajectory` (use when it fits in memory);
+  `iter_trajectory(path, topology=..., chunk_size=100, stride=1,
+  atom_indices=None)` yields chunks of frames as `Trajectory` objects
+  with bounded memory; `write_trajectory(trajectory, path)` writes
+  out, format inferred from the extension. Coordinates are converted
+  nm ↔ Å automatically (molforge convention is Å throughout; mdtraj's
+  is nm), times in picoseconds either side. The `topology` argument
+  is required for binary formats that don't embed it (XTC, TRR, DCD,
+  NetCDF); it accepts either a `molforge.core.Protein` (reused
+  directly — no PDB round-trip when the caller passes a Protein in)
+  or a path to a PDB. PDB-format trajectories can pass
+  `topology=None`. The `atom_indices` parameter slices both the
+  coordinate array AND the returned topology, so callers analyzing
+  a subset (e.g. backbone atoms only) get a self-consistent
+  Trajectory rather than coords-and-topology mismatched. Lazy mdtraj
+  import: importing `molforge.io` does not import mdtraj; only the
+  trajectory functions do, and they raise
+  `MDEngineNotInstalledError` with install instructions when mdtraj
+  is absent. NOT wired into `load()` / `save()`: trajectories return
+  a different type than the dispatcher's `Protein` / `list[Protein]`
+  contract, and the topology argument is something the dispatcher
+  has no way to supply. Kept as dedicated entry points. 21 new tests
+  in `tests/unit/io/test_trajectory.py` covering reading from PDB,
+  the Å unit conversion, Protein-topology reuse identity, path-string
+  topology, no-topology PDB, atom-indices subset (including the
+  metadata-preserving Protein-slice path), stride, time-array
+  carry-through, the "source: mdtraj" metadata marker, the streaming
+  chunk count (3+3+3+1 from 10 frames), chunk validation, the
+  stride-plus-chunking compose case, the DCD / XTC / PDB write paths
+  (XTC round-trip with the documented 0.001-nm precision), and the
+  missing-mdtraj error path; mdtraj-using tests are
+  `pytest.importorskip` gated. The new module is at high coverage
+  (the few uncovered branches are unreachable error-handling
+  fallbacks). `pdbfixer.*` was added to mypy's missing-stubs override
+  list when `molforge.prep` shipped; no new mypy override is needed
+  here since mdtraj is already there.
+- **New subpackage: `molforge.prep` for MD-system preparation.** A
+  raw PDB from AlphaFold, RoseTTAFold, the RCSB, or a docking engine
+  almost always needs the same clean-up before MD: drop
+  crystallographic clutter (waters, buffer salts, sometimes the
+  ligand), rebuild missing heavy atoms, cap free termini with ACE /
+  NME, and add explicit hydrogens at the right pH. The new
+  `molforge.prep` subpackage exposes one composable function per
+  step plus a convenience pipeline:
+    - `remove_heterogens(protein)` — pure-Python residue-name filter.
+      By default drops waters, ions, ligands, and everything outside
+      the 20 canonical amino acids + standard nucleotides. `keep_water`
+      / `keep_ions` / `keep_ligands` toggles plus an explicit `keep`
+      allow-list for cofactors. Recognises multiple water aliases
+      (HOH, WAT, H2O, SOL, TIP*) and the common monatomic ions.
+    - `fix_missing_atoms(protein)` — wraps PDBFixer's rotamer-library
+      rebuild for incomplete side chains. `fix_missing_residues=False`
+      by default (de-novo loop modelling is risky);
+      `replace_nonstandard=True` by default (MSE → MET, etc.).
+    - `add_caps(protein)` — wraps PDBFixer to add ACE / NME caps at
+      free termini of every protein chain. Multi-chain aware;
+      non-protein chains (ligands, DNA) skipped. Either cap can be
+      disabled with an empty string.
+    - `add_hydrogens(protein, pH=7.4)` — wraps OpenMM
+      `Modeller.addHydrogens` for pH-aware protonation. Idempotent on
+      already-protonated input. The `force_field` kwarg accepts both
+      registered aliases (`"amber14"`, `"charmm36"`) and bare XML
+      filenames.
+    - `prepare_for_md(protein)` — convenience entry point that chains
+      the four steps with sensible defaults for an
+      AlphaFold-PDB-to-OpenMM workflow. Each step's options are
+      forwarded; individual steps can be turned off
+      (`add_caps_to_termini=False`, `add_explicit_hydrogens=False`).
+
+## [v0.3.0] 2026-06-22
+
 ### Added
 - **`molforge.io.read_pqr` / `write_pqr` are implemented.** PQR
   (PDB2PQR / APBS) was a committed import path but a

{molforge-0.3.0 → molforge-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: molforge
-Version: 0.3.0
+Version: 0.4.0
 Summary: A unified Python library for structural bioinformatics, MD, protein engineering, and ML.
 Project-URL: Homepage, https://github.com/DoctorDean/molforge
 Project-URL: Documentation, https://doctordean.github.io/molforge/
@@ -50,6 +50,7 @@ Requires-Dist: biopython>=1.83; extra == 'all'
 Requires-Dist: biotite>=0.40; extra == 'all'
 Requires-Dist: mdtraj>=1.10; extra == 'all'
 Requires-Dist: openmm>=8.1; (platform_system != 'Windows') and extra == 'all'
+Requires-Dist: pdbfixer>=1.9; (platform_system != 'Windows') and extra == 'all'
 Requires-Dist: rdkit>=2023.9; extra == 'all'
 Requires-Dist: scipy>=1.11; extra == 'all'
 Requires-Dist: torch>=2.1; extra == 'all'
@@ -83,6 +84,9 @@ Requires-Dist: openmm>=8.1; (platform_system != 'Windows') and extra == 'md'
 Provides-Extra: ml
 Requires-Dist: torch>=2.1; extra == 'ml'
 Requires-Dist: transformers>=4.40; extra == 'ml'
+Provides-Extra: prep
+Requires-Dist: openmm>=8.1; (platform_system != 'Windows') and extra == 'prep'
+Requires-Dist: pdbfixer>=1.9; (platform_system != 'Windows') and extra == 'prep'
 Provides-Extra: sequence
 Requires-Dist: biopython>=1.83; extra == 'sequence'
 Provides-Extra: structure
@@ -146,6 +150,9 @@ pip install "molforge[ml]"
 # with MD support (openmm, mdtraj)
 pip install "molforge[md]"
 
+# with structure prep for MD (pdbfixer + openmm)
+pip install "molforge[prep]"
+
 # with docking (rdkit for small molecules)
 pip install "molforge[docking]"
 
@@ -221,7 +228,7 @@ molforge/
 │   ├── plugins/              # Plugin registry and entry-point discovery
 │   ├── metrics/              # TM-score, lDDT, GDT-TS, docking metrics
 │   └── wrappers/             # Thin interfaces to external engines
-│       ├── folding/          # AlphaFold, ESMFold, Boltz, Rosetta
+│       ├── folding/          # AlphaFold, ESMFold, Boltz, RoseTTAFold
 │       ├── docking/          # AutoDock Vina, DiffDock
 │       └── md/               # OpenMM, GROMACS
 ├── tests/                    # pytest suite (909 passing + skips)

{molforge-0.3.0 → molforge-0.4.0}/README.md

@@ -53,6 +53,9 @@ pip install "molforge[ml]"
 # with MD support (openmm, mdtraj)
 pip install "molforge[md]"
 
+# with structure prep for MD (pdbfixer + openmm)
+pip install "molforge[prep]"
+
 # with docking (rdkit for small molecules)
 pip install "molforge[docking]"
 
@@ -128,7 +131,7 @@ molforge/
 │   ├── plugins/              # Plugin registry and entry-point discovery
 │   ├── metrics/              # TM-score, lDDT, GDT-TS, docking metrics
 │   └── wrappers/             # Thin interfaces to external engines
-│       ├── folding/          # AlphaFold, ESMFold, Boltz, Rosetta
+│       ├── folding/          # AlphaFold, ESMFold, Boltz, RoseTTAFold
 │       ├── docking/          # AutoDock Vina, DiffDock
 │       └── md/               # OpenMM, GROMACS
 ├── tests/                    # pytest suite (909 passing + skips)

{molforge-0.3.0 → molforge-0.4.0}/pyproject.toml

@@ -58,6 +58,10 @@ md = [
     "mdtraj>=1.10",
     "openmm>=8.1; platform_system != 'Windows'",
 ]
+prep = [
+    "openmm>=8.1; platform_system != 'Windows'",
+    "pdbfixer>=1.9; platform_system != 'Windows'",
+]
 docking = [
     "rdkit>=2023.9",
 ]
@@ -70,7 +74,7 @@ io = [
     "biotite>=0.40",
 ]
 all = [
-    "molforge[structure,sequence,md,docking,ml,io]",
+    "molforge[structure,sequence,md,prep,docking,ml,io]",
 ]
 dev = [
     "pytest>=7.4",
@@ -229,6 +233,7 @@ module = [
     "mdtraj.*",
     "meeko.*",
     "openmm.*",
+    "pdbfixer.*",
     "rdkit.*",
     "torch.*",
     "transformers.*",

{molforge-0.3.0 → molforge-0.4.0}/src/molforge/__init__.py

@@ -13,5 +13,5 @@ orchestration layer, and no required entry point. Import what you need.
 
 from __future__ import annotations
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 __all__ = ["__version__"]

{molforge-0.3.0 → molforge-0.4.0}/src/molforge/core/__init__.py

@@ -37,6 +37,7 @@ from molforge.core.constants import (
 )
 from molforge.core.metadata_keys import ProteinMetadata
 from molforge.core.protein import Protein
+from molforge.core.provenance import Provenance
 from molforge.core.residue import Residue
 
 __all__ = [  # noqa: RUF022 — grouped by concept, not alphabetical
@@ -56,6 +57,9 @@ __all__ = [  # noqa: RUF022 — grouped by concept, not alphabetical
     # Metadata vocabulary (string constants live in
     # molforge.core.metadata_keys; the TypedDict is re-exported here)
     "ProteinMetadata",
+    # Provenance — first-class "what produced this output" record;
+    # stored under metadata[PROVENANCE] (see metadata_keys.PROVENANCE).
+    "Provenance",
     # Constants & helpers
     "THREE_TO_ONE",
     "ONE_TO_THREE",

{molforge-0.3.0 → molforge-0.4.0}/src/molforge/core/metadata_keys.py

@@ -64,6 +64,23 @@ EXPERIMENTAL_METHOD = "experimental_method"
 RESOLUTION = "resolution"
 """Resolution in Angstrom (float). Absent for non-diffraction structures."""
 
+# ----------------------------------------------------------------------
+# Provenance
+# ----------------------------------------------------------------------
+
+PROVENANCE = "provenance"
+"""First-class provenance record (:class:`molforge.core.Provenance`).
+
+The canonical key for "what produced this output." Carries engine
+name, version, parameters, inputs, and a recursive parent pointer to
+the upstream step's provenance. See :mod:`molforge.core.provenance`
+for construction helpers and the data shape.
+
+This is the documented replacement for the older ad-hoc
+``metadata["engine"]`` / ``metadata["source_args"]`` keys. Both
+continue to work for backwards compatibility; new code should write a
+:class:`Provenance` to this key instead."""
+
 # ----------------------------------------------------------------------
 # Uniform folding-engine keys (every folding wrapper sets these)
 # ----------------------------------------------------------------------
@@ -166,6 +183,13 @@ class ProteinMetadata(TypedDict, total=False):
     experimental_method: str
     resolution: float
 
+    # Provenance — first-class record of what produced this output.
+    # The value type is molforge.core.Provenance; declared here as
+    # ``Any`` to avoid a runtime circular import (the dataclass lives
+    # in molforge.core.provenance which imports nothing from this
+    # module).
+    provenance: Any
+
     # Uniform folding-engine keys.
     engine: str
     source_sequence: str
@@ -203,6 +227,7 @@ DOCUMENTED_KEYS: frozenset[str] = frozenset(
         DEPOSITION_DATE,
         EXPERIMENTAL_METHOD,
         RESOLUTION,
+        PROVENANCE,
         ENGINE,
         SOURCE_SEQUENCE,
         CONFIDENCE_PER_RESIDUE,
@@ -240,6 +265,8 @@ __all__ = [
     "DEPOSITION_DATE",
     "EXPERIMENTAL_METHOD",
     "RESOLUTION",
+    # Provenance
+    "PROVENANCE",
     # Uniform folding-engine keys
     "ENGINE",
     "SOURCE_SEQUENCE",