molforge 0.2.0__tar.gz → 0.3.0__tar.gz

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

@@ -7,6 +7,249 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **`molforge.io.read_pqr` / `write_pqr` are implemented.** PQR
+  (PDB2PQR / APBS) was a committed import path but a
+  `NotImplementedError` stub; it now parses and writes PQR files,
+  completing the format-I/O backlog (SDF, MOL2, PDBQT, PQR all real).
+  PQR is a PDB-like format that appends per-atom partial charge and
+  atomic radius as whitespace-separated trailing fields. Unlike PDB
+  or PDBQT, PQR is **not** strictly fixed-column past the
+  coordinates — different generators (PDB2PQR, AMBER, CHARMM, APBS)
+  emit different widths. The reader handles all of them by parsing
+  columns 1-54 as fixed (the atom record through coordinates,
+  PDB-compatible) and whitespace-splitting the remainder for charge
+  and radius. Charges land on `AtomArray.charge`; radii land on
+  `protein.metadata["radii"]` as a per-atom list (no native
+  `radius` field on `AtomArray` — electrostatics is a small enough
+  slice of the surface that this didn't warrant a core-type change).
+  The writer is the symmetric operation: it calls `write_pdb_string`,
+  truncates each atom line at column 54, then appends
+  `charge radius`. When no radii are recorded in metadata, a default
+  1.5 Å is used (a reasonable middle-of-the-road heavy-atom radius
+  that lets a charge-only Protein still be written as PQR). 19 new
+  tests in `tests/unit/io/test_pqr.py` covering the charge/radius
+  extractor (clean tokens, trailing garbage, defaults), reading from
+  string and from disk, the dispatcher routes, two variant-width
+  tails seen in real-world PDB2PQR / AMBER output, the full
+  round-trip (coordinates, charges, radii), and the default-radius
+  writer path; `pqr.py` is at 92.0% coverage.
+  `test_dispatch.py`: the two stub-format tests (load and save) now
+  monkeypatch a synthetic planned format rather than depending on
+  any real format being unimplemented — the dispatcher's
+  planned-readers fallback machinery still exists for future use, so
+  the tests are still meaningful. The `_PLANNED_READERS` dict in
+  `dispatch.py` is now empty.
+- **`molforge.io.read_pdbqt` / `write_pdbqt` are implemented.** PDBQT
+  (AutoDock / Vina) was a committed import path but a
+  `NotImplementedError` stub; it now parses and writes PDBQT files.
+  PDBQT is a thin extension of PDB — columns 1-66 are PDB-compatible,
+  columns 71-76 hold the per-atom partial charge, and columns 78-79
+  hold the AutoDock atom type (`C`, `OA`, `HD`, `NA`, ...). The
+  reader reuses `molforge.io.read_pdb_string` for the heavy lifting
+  (atom-array construction, altloc handling, entity classification,
+  multi-MODEL parsing) and post-processes each atom line to pick up
+  the extra columns: charges are written to `AtomArray.charge`,
+  AutoDock types land on `protein.metadata["autodock_types"]` as a
+  per-atom list. `ROOT` / `BRANCH` / `TORSDOF` rotatable-bond markers
+  are read-tolerated (recognised and skipped — `AtomArray` doesn't
+  carry bond topology). The writer is the symmetric operation: it
+  calls `write_pdb_string`, then rewrites each `ATOM` / `HETATM` line
+  to append the charge and AutoDock-type columns; when no AutoDock
+  type is recorded in metadata, the element is used as a documented
+  best-effort fallback. Round-tripping preserves coordinates,
+  charges, and types. The Vina wrapper's pose parser is refactored to
+  go through `read_pdbqt_string` rather than its previous "truncate
+  every atom line to 66 columns and feed to the PDB reader" hack — so
+  per-atom charges now propagate to `Pose.ligand` instead of being
+  silently discarded. 23 new tests in `tests/unit/io/test_pdbqt.py`
+  covering the column extractors (charge and AutoDock type, including
+  the whitespace-split fallback), reading from string and from disk,
+  the dispatcher routes, the full round-trip (coordinates, charges,
+  types), the element-fallback writer path, multi-MODEL handling
+  (Vina pose output), and `ROOT` / `BRANCH` / `TORSDOF` tolerance;
+  `pdbqt.py` is at 93.8% coverage. The `test_dispatch.py` stub-format
+  tests are updated to use `.pqr` (the only remaining stub format).
+- **`molforge.io.read_mol2` / `write_mol2` are implemented.** MOL2
+  (Tripos) was a committed import path but a `NotImplementedError`
+  stub; it now parses and writes Tripos MOL2 files. Like the SDF
+  reader, `read_mol2` is multi-molecule by default and returns
+  `list[Protein]` (the format supports multi-molecule files via
+  repeated `@<TRIPOS>MOLECULE` markers, common in docking output
+  libraries). The reader populates coordinates, elements (extracted
+  from the prefix of the Tripos atom type — `C.ar` → `C`, `N.am` →
+  `N`, two-letter `Cl`/`Br` preserved), atom names, per-atom partial
+  charges from the atom line's last column, and substructure info
+  (residue id / name from the MOL2 `subst_id` / `subst_name`
+  columns). Short atom lines (optional trailing columns omitted) and
+  non-conforming writers that emit `***` for the subst_id or a
+  non-numeric charge are tolerated with silent fallbacks rather
+  than crashing the whole molecule. Bond orders, ring information,
+  stereochemistry, and the `@<TRIPOS>SUBSTRUCTURE` /
+  `@<TRIPOS>CRYSIN` / `@<TRIPOS>UNITY` sections are intentionally
+  dropped — those need a chemistry toolkit. The writer emits a
+  minimal, spec-conformant MOL2 with an empty `@<TRIPOS>BOND` section
+  (some downstream tools error without the tag). The MOLECULE header
+  declares the atom count; a mismatch between that and the ATOM
+  section raises a clear error. `read_mol2` is wired into
+  `molforge.io.load`. 34 new tests in `tests/unit/io/test_mol2.py`
+  covering single/multi-molecule reading, Tripos atom-type element
+  extraction, two-letter elements, partial charges, optional-column
+  fallbacks, blank-line tolerance, every error path, dispatcher
+  integration, and the full round-trip; mol2.py is at 94.4% coverage
+  (the residual misses are unreachable defensive branches).
+- **`molforge.io.read_sdf` / `write_sdf` are implemented.** SDF was a
+  committed import path but a `NotImplementedError` stub; it now
+  parses and writes V2000 SDF / MOL files. The reader is multi-
+  molecule by default, returning a `list[Protein]` (a single-molecule
+  `.mol` file still returns a one-element list, keeping the return
+  type uniform across callers). The atom block, title line, and the
+  ``> <Name>`` / value property block all round-trip; properties land
+  on `Protein.metadata["properties"]`. The implementation uses no
+  chemistry toolkit — the V2000 atom block has a fixed positional
+  layout that's enough for everything molforge does downstream
+  (coordinates, pose ranking, distance calculations). Bond orders,
+  aromaticity, and stereochemistry are intentionally dropped; users
+  who need them should call RDKit directly. V3000 files are detected
+  and raise a clear error pointing at conversion paths. `read_sdf` is
+  wired into `molforge.io.load`, so `load("foo.sdf")` works. The
+  DiffDock wrapper, which previously parsed SDF inline, now goes
+  through `molforge.io.sdf.read_sdf_string` — the inline
+  `_ligand_from_sdf` helper is removed (-1 duplicated parser).
+  `api-stability.md` is updated; MOL2, PDBQT, and PQR remain
+  tentative. 26 new tests in `tests/unit/io/test_sdf.py` covering
+  single/multi-molecule reading, the title and property block,
+  round-trip writing, dispatcher integration, and every error path;
+  the eight DiffDock tests that exercised the inline parser are
+  removed (now subsumed by the SDF tests).
+- **`GROMACS` is now a real MD engine.** `GROMACS`
+  (`molforge.wrappers.md`) was a coherent stub whose `prepare` /
+  `minimize` / `run` all raised `NotImplementedError`; it is now
+  fully implemented. [GROMACS](https://www.gromacs.org/) is a
+  command-line program (`gmx`), not a Python library, so the wrapper
+  drives it as a subprocess. One `prepare` / `minimize` / `run` cycle
+  maps onto the standard GROMACS workflow: `prepare` runs
+  `pdb2gmx` → `editconf` → (optionally) `solvate`; `minimize` writes
+  a steepest-descent `.mdp`, then `grompp` → `mdrun`; `run` writes a
+  production `.mdp`, runs `grompp` → `mdrun`, then reads the frames
+  back with `trjconv` and per-frame energies with `gmx energy`. All
+  state for a simulation lives in one run directory whose path is
+  carried on `Simulation.engine_handle` (and mirrored in
+  `metadata["run_dir"]`), so `minimize` and `run` continue from
+  whatever `prepare` produced. Trajectory frames are read back by
+  asking GROMACS itself (`gmx trjconv`) to convert its binary `.xtc`
+  to a multi-model PDB, which molforge's own PDB reader then parses —
+  the wrapper deliberately takes no dependency on a third-party
+  binary-trajectory library. Three small fixed-layout parsers
+  (`.gro` coordinates, multi-model PDB, `.xvg` columns) handle the
+  GROMACS outputs directly. `gmx` is resolved lazily via
+  `shutil.which`, so construction never touches the filesystem; a
+  clear `MDEngineNotInstalledError` (pointing at OpenMM) is raised
+  when it is absent. A constructor flag covers the water model, box
+  margin/type, and a `verbose` pass-through. 36 tests (a new
+  `test_gromacs.py`), covering construction and validation, `gmx`
+  resolution, the three parsers and their error paths, and the full
+  `prepare` / `minimize` / `run` pipeline driven by a mocked
+  `subprocess.run` that writes the files each `gmx` step would
+  produce; the wrapper module is at 94% coverage (the residual
+  misses are defensive `except` branches for corrupt output GROMACS
+  would never actually emit). The 6 obsolete `TestGROMACSStub` tests
+  are removed.
+- **`DiffDock` is now a real docking engine.** `DiffDock`
+  (`molforge.wrappers.docking`) was a coherent stub whose `dock()`
+  raised `NotImplementedError`; it is now fully implemented.
+  [DiffDock](https://github.com/gcorso/DiffDock) is a
+  diffusion-generative model for *blind* protein-ligand docking — it
+  needs no search box, sampling poses over the whole receptor and
+  ranking them with a learned confidence model. Like the
+  `RoseTTAFold` wrapper, DiffDock ships as a research repository
+  rather than a pip package, so the wrapper drives it as a
+  subprocess: it locates the cloned repo (`$DIFFDOCK_HOME` or an
+  explicit `repo_dir`), materializes the receptor to PDB, accepts the
+  ligand as a SMILES string or a path to an SDF/MOL2 file, runs
+  `python -m inference`, and parses the ranked
+  `rank{N}_confidence{C}.sdf` output into a `DockingResult`. DiffDock
+  reports a *confidence* (higher = better), the opposite of Vina's
+  affinity convention; the wrapper stores the raw value in
+  `Pose.metadata["confidence"]` and sets `Pose.score` to its
+  negation, so `score` ascending is best-first for every engine. SDF
+  poses are parsed by reading the V2000 atom block directly (molforge's
+  RDKit-backed SDF reader is still a stub, and the atom block —
+  3D coordinates plus element symbols — needs no chemistry toolkit).
+  A constructor flag covers `samples_per_complex`, `inference_steps`,
+  and `batch_size`. 30 tests (a new `test_diffdock.py`), covering
+  construction and validation, install resolution, SDF and
+  confidence-from-filename parsing, and the `_run_cli` subprocess seam
+  via a mocked `subprocess.run`; the wrapper module is at 100%
+  coverage. The 4 obsolete `TestDiffDockStub` tests are removed.
+- **OpenMM wrapper test coverage raised from 24% to 95%.** The
+  OpenMM tests previously gated every real path behind
+  `skipif(openmm installed)` — so `prepare` / `minimize` / `run`
+  were exercised by *nothing*: when openmm was absent they couldn't
+  run, and when present the negative-path tests skipped. The file is
+  restructured into a dependency-free half (construction, the
+  force-field registry, the missing-dependency errors) and a new
+  `TestRealOpenMM` class that runs `prepare` / `minimize` / `run`
+  end to end against a real OpenMM install — system building,
+  hydrogen addition, the minimizer, the integration loop, trajectory
+  assembly, and argument validation. A new chemically complete
+  heavy-atom fixture, `tests/fixtures/pdb/ala_tripeptide_heavy.pdb`
+  (ALA-ALA-ALA with all standard heavy atoms plus the C-terminal
+  OXT), gives the force field something it can template. The
+  real-engine tests are deliberately *not* marked `slow` — the
+  tripeptide is tiny and a 20-step run is sub-second — so they run
+  in the normal suite wherever openmm is installed, and skip cleanly
+  (9 skips) where it isn't. A new CI job, `md-openmm`, installs the
+  `[md]` extra and runs the MD wrapper tests on every push so
+  `TestRealOpenMM` is actually exercised.
+- **RFdiffusion wrapper test coverage raised from 84% to 99%.** The
+  `_run_cli` subprocess seam of `wrappers.generative.rfdiffusion` —
+  previously untested — now has direct tests via a mocked
+  `subprocess.run` (no RFdiffusion or torch needed): command and
+  Hydra-arg assembly, the `design_*.pdb` output-parsing path, the
+  no-output `RuntimeError`, `CalledProcessError` → `RuntimeError`
+  translation, the public `generate()` entry point, and
+  `contigs` / `symmetry` pass-through. 5 new tests (16 → 21 in the
+  file). Mirrors the ProteinMPNN coverage work from the previous
+  cycle.
+
+### Removed
+- **BREAKING `molforge.wrappers.folding.Rosetta` removed.** The `Rosetta`
+  name was a placeholder from the `0.0.x` series whose meaning was
+  ambiguous — it could read as PyRosetta (the classical
+  sequence-design library) or RoseTTAFold (the deep-learning
+  model). The real wrapper now lives at `RoseTTAFold`. `Rosetta`
+  had been kept this cycle as a `DeprecationWarning`-emitting alias,
+  but since it never appeared in a tagged release, carrying it —
+  and the day-one deprecation it implies — into the 1.0 stable
+  surface added nothing. It is removed outright: import
+  `RoseTTAFold` instead. A PyRosetta wrapper, if ever added, would
+  be a separate class (`PyRosetta`) in its own module, since
+  PyRosetta's surface is far wider than the `FoldingEngine`
+  contract. The 3 alias tests are removed (folding-engine count
+  unchanged: ESMFold, AlphaFold, Boltz, RoseTTAFold).
+
+ ### Fixed
++- **`OpenMM.prepare()` now adds missing hydrogens, so heavy-atom
+  structures are usable.** A force field needs explicit hydrogens,
+  but `prepare()` called `ForceField.createSystem()` directly on
+  whatever atoms the input had. Heavy-atom structures — the normal
+  output of every folding and docking engine, and what most PDB
+  files on disk contain — therefore failed with a cryptic
+  OpenMM "no template found for residue" error, making the wrapper
+  effectively unusable on exactly the structures molforge produces.
+  `prepare()` now runs `Modeller.addHydrogens()` before building the
+  system; the step is idempotent, so an already-protonated structure
+  is unaffected. Because adding hydrogens changes the atom count, the
+  molforge `Protein` attached to the returned `Simulation` is rebuilt
+  from the protonated structure, so its topology and the coordinate
+  array agree (previously a heavy-atom topology could be paired with
+  a protonated coordinate array). A new `add_hydrogens` constructor
+  flag (default `True`) lets callers who have pre-protonated their
+  structure opt out.
+
+## [v0.2.0] 2026-05-26 
+
 ### Added
 - **ProteinMPNN wrapper test coverage raised from 69% to 96%.** The
   two previously-untested seams of `wrappers.generative.proteinmpnn`
@@ -72,148 +315,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   still permitted but carry no cross-version stability guarantee. 15
   new tests, including consistency checks that the parsers only emit
   documented keys and that the TypedDict matches `DOCUMENTED_KEYS`.
-
-### Fixed
-- **`load_alphafold` now emits the uniform confidence metadata keys.**
-  `molforge.io.load_alphafold` previously wrote only AlphaFold-specific
-  keys (`plddt`, `plddt_per_residue`, `mean_plddt`, `source`), while
-  the AlphaFold *wrapper* wrote the cross-engine-uniform keys
-  (`confidence_per_atom`, `confidence_per_residue`, `mean_confidence`,
-  `engine`). Downstream code reading confidence uniformly across
-  engines silently missed AlphaFold structures loaded from disk.
-  `load_alphafold` now populates both sets (uniform keys preferred,
-  legacy keys retained for backward compatibility); the two carry
-  identical values. Surfaced by the API audit.
-- **`GROMACS` and `DiffDock` are now coherent stubs.** Both are
-  exported (committed import paths) but unimplemented. Previously
-  they were *incoherent*: `GROMACS` didn't implement its `MDEngine`
-  abstract methods at all, so `GROMACS()` failed with a cryptic
-  "Can't instantiate abstract class" `TypeError` rather than a
-  meaningful message; both engines' methods raised a bare
-  `NotImplementedError` with no text. They are now coherent stubs —
-  instantiable, satisfying their respective engine ABCs
-  (`MDEngine` / `DockingEngine`), with every method raising
-  `NotImplementedError` carrying a clear message that points at the
-  working alternative (`OpenMM` / `Vina`) and the tracking issue.
-  10 new tests. Surfaced by the API audit.
-- - **Lint drift from a Ruff version bump cleared; CI lint job green
-  again.** `.pre-commit-config.yaml` pinned `ruff-pre-commit` at
-  `v0.5.0`, but the `[dev]` extra installs `ruff>=0.5` unpinned, so
-  CI resolved a much newer Ruff (0.15.x) whose added rules flagged
-  33 pre-existing issues — meaning the CI `lint` job was effectively
-  red. All 33 are now resolved: a genuine dead variable in
-  `ensembles.clustering` removed, an unused `shutil` import dropped,
-  five `pytest.raises(match=...)` patterns with unescaped regex
-  metacharacters made explicit (raw strings / escaped dots), a
-  `zip()` given an explicit `strict=`, four nested `with` statements
-  collapsed, a `getattr()` call with a string literal in
-  `ensembles.weighting` replaced by a `cast`-backed direct attribute
-  access (dropping a now-misplaced `# noqa`), and a Ruff-version
-  formatting refresh applied across 24 files (cosmetic line-joining
-  only). Two intentional-notation cases
-  are configured rather than rewritten: `allowed-confusables`
-  permits `×`, `σ`, and `–` in docstrings (matrix dimensions, the
-  standard deviation, prose dashes), and `RUF022` is per-file-ignored
-  for the two modules whose `__all__` is deliberately grouped by
-  category with section comments. The `ruff` and `mypy` pre-commit
-  pins are bumped to the versions CI resolves, so the two stay in
-  lock-step and this drift cannot silently recur. No source-behaviour
-  or test-count change (918 pass + 11 skipped, unchanged).
-
-### Changed
-- **BREAKING: `cross_validate` now defaults to `on_error="raise"`.**
-  Previously `cross_validate` defaulted to `on_error="record"` —
-  exceptions raised by individual validators were silently caught,
-  recorded in verdict metadata, and the verdict marked
-  `passed=False`. The problem: a validator that throws on every
-  design (a misconfigured engine, a missing dependency, a bad
-  input) produced a full list of `passed=False` verdicts that
-  *looked* like a real result, hiding the bug. The new default
-  fails loud. Code that genuinely wants a batch to survive
-  individual validator failures must now pass `on_error="record"`
-  explicitly. Flagged and resolved by the API audit.
-- **The entire `molforge` package is now `mypy --strict` clean.**
-  With `wrappers` and `plugins` brought up to strict, all 77 source
-  modules across every subpackage pass `mypy --strict` with zero
-  errors. The CI `typecheck` job is correspondingly simplified: the
-  previous two-step arrangement (a strict gate on the clean
-  subpackages plus a non-blocking informational full-tree run)
-  collapses to a single `mypy src` gate that fails the build on any
-  type error. The `tests/unit/test_typing.py` regression test is
-  likewise simplified to one whole-package check. 31 errors fixed in
-  this final tranche: 20 stale `# type: ignore` comments (made
-  redundant when the optional heavy dependencies were added to the
-  mypy `ignore_missing_imports` override), four deliberate engine-
-  method `# type: ignore[override]` annotations (the concrete
-  engine wrappers refine the permissive `**kwargs` signatures of
-  their `DockingEngine` / `MDEngine` / `GenerativeEngine` abstract
-  bases — an intentional, documented refinement that mypy's strict
-  Liskov check cannot model), `cast`s for the opaque
-  `Simulation.engine_handle` inside the OpenMM wrapper and for the
-  unstubbed-dependency return values, and `Vina.dock`'s receptor
-  narrowing switched from `hasattr` to `isinstance` (a more correct
-  check that mypy can also narrow on).
-- **`molforge.ml` is now `mypy --strict` clean.** The ML subpackage
-  (sequence/structure featurization, protein-language-model
-  embeddings) joins the strict gate — eight strict-clean
-  subpackages in total, 51 source files. Six errors fixed: the four
-  numpy-widening `no-any-return`s in `embeddings.py` (resolved with
-  `cast`s), and two real type bugs in `structure_features.py` —
-  `pair_distances` and `pair_distance_features` declared
-  `atom_choice: str` but pass it to `distance_map`, which requires
-  the `Literal["ca","cb","heavy","all"]` the docstrings already
-  specify, and a coordinate feature array silently upcast to
-  float64 by a division. The `torch` and `transformers` (and
-  `colabfold`, `meeko`, `vina`) optional heavy dependencies, which
-  ship no type stubs, are added to the mypy `ignore_missing_imports`
-  override alongside the existing `Bio` / `biotite` / `mdtraj` /
-  `openmm` / `rdkit` entries. CI strict gate and the
-  `tests/unit/test_typing.py` regression test updated; only
-  `plugins` and `wrappers` remain outside the gate.
-- **Six more subpackages are now `mypy --strict` clean.**
-  `molforge.io`, `molforge.sequence`, `molforge.structure`,
-  `molforge.metrics`, `molforge.ensembles`, and
-  `molforge.validation` now pass `mypy --strict` with zero errors,
-  joining `molforge.core` — seven strict-clean subpackages in total,
-  46 source files. The 12 errors fixed were mostly numpy operations
-  mypy widens to `Any` (resolved with explicit `cast`s that document
-  the known array dtype) and two stale `type: ignore` comments; two
-  were genuine annotation bugs — `_place_hydrogens` in `dssp.py` was
-  declared to return a single array but actually returns a
-  `(coords, mask)` tuple, and `_score` in `alignment.py` was
-  declared `NDArray[np.int_]` but builds an `int32` array (`np.int_`
-  is `int64` on 64-bit platforms). The CI strict gate now covers all
-  seven subpackages; the regression test
-  (`tests/unit/test_typing.py`, moved up from `tests/unit/core/` and
-  parametrized) checks each one in-suite. The remaining subpackages
-  (`ml`, `plugins`, `wrappers`) are still tracked by the
-  non-blocking informational `mypy src` CI step.
-- **`molforge.core` is now `mypy --strict` clean, and CI enforces
-  it.** The `core` subpackage — the data model the rest of the
-  library is built on — now passes `mypy --strict` with zero
-  errors (fixed: two missing `NDArray` type arguments in
-  `AtomArray`, an `Any`-return in `Atom.coord`, and an untyped
-  `Chain.__iter__` that was suppressed with a `type: ignore`). The
-  CI `typecheck` job now runs `mypy --strict src/molforge/core/`
-  as a hard gate, with a separate non-blocking full-tree `mypy src`
-  step that keeps the remaining (out-of-`core`) type errors visible
-  while they're worked through. A new `slow`-marked regression test
-  (`tests/unit/core/test_typing.py`) runs the strict check in-suite
-  so a `core` type regression is caught locally too.
-
-### Documented
-- **`Simulation.engine_handle` contract clarified.** The attribute
-  type (`object | None`) is correct — it really is an opaque,
-  engine-specific handle — but the contract was under-specified.
-  The docstring now states explicitly that `engine_handle` is
-  engine-private (callers must not inspect it or set it), is **not
-  serialized** (it typically wraps unpicklable C-extension state;
-  persistence layers must drop it and let the engine wrapper
-  rebuild it on resume), and carries **no semver guarantee**. For
-  inspectable per-simulation data, `Simulation.metadata` is the
-  supported field. No code change. Flagged by the API audit.
-
-### Added 
 - **RoseTTAFold All-Atom folding wrapper.** New file
   `src/molforge/wrappers/folding/rosettafold.py` implements a real
   wrapper around the Baker lab's RoseTTAFold-All-Atom (Krishna et
@@ -241,25 +342,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   prediction matching the rest of the folding wrappers; protein-
   ligand and covalent-modification co-folding (RFAA's headline
   capability) need a separate `predict_complex()` surface and
-  remain planned. 47 new tests (45 passing + 2 correctly skipped:
+  remain planned. 
+- 47 new tests (45 passing + 2 correctly skipped:
   one for the torch tensor conversion when torch isn't installed,
   one @slow end-to-end requiring `$RFAA_HOME`). Total test count:
   830 → 875 passed + 11 skipped.
-
-### Deprecated
-- **`molforge.wrappers.folding.Rosetta` is now a deprecated alias
-  for `RoseTTAFold`.** The original `rosetta.py` placeholder was
-  ambiguous about whether it referred to PyRosetta (the Baker lab's
-  classical sequence-design library) or RoseTTAFold (the deep-
-  learning model). The new real wrapper lives at
-  `RoseTTAFold` for clarity. `Rosetta` is retained as a thin
-  subclass that emits `DeprecationWarning` on construction so
-  existing imports / isinstance checks keep working through the
-  next minor release. A PyRosetta wrapper, if added, would live in
-  a separate module (`pyrosetta.py`) since PyRosetta's surface is
-  much wider than the `FoldingEngine` contract.
-
-### Added 
 - **Boltz / Boltz-2 folding wrapper.** Real implementation replacing
   the `boltz.py` stub. Drives the `boltz predict` CLI via subprocess
   against a temporary directory and parses the resulting mmCIF +
@@ -275,7 +362,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   metadata follows the uniform folding-engine convention
   (`confidence_per_residue`, `confidence_per_atom`, `mean_confidence`)
   and additionally surfaces Boltz-specific `ptm`, `iptm`, and
-  `confidence_score` from the JSON sidecar. 47 new tests (46 passing
+  `confidence_score` from the JSON sidecar. 
+- 47 new tests (46 passing
   + 1 correctly skipped @slow end-to-end), structured as a series of
   testable seams: construction, sequence validation, YAML input
   construction, command-line assembly, environment setup, output
@@ -477,6 +565,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   the empty-entry-points fallthrough.
 
 ### Fixed
+- **`load_alphafold` now emits the uniform confidence metadata keys.**
+  `molforge.io.load_alphafold` previously wrote only AlphaFold-specific
+  keys (`plddt`, `plddt_per_residue`, `mean_plddt`, `source`), while
+  the AlphaFold *wrapper* wrote the cross-engine-uniform keys
+  (`confidence_per_atom`, `confidence_per_residue`, `mean_confidence`,
+  `engine`). Downstream code reading confidence uniformly across
+  engines silently missed AlphaFold structures loaded from disk.
+  `load_alphafold` now populates both sets (uniform keys preferred,
+  legacy keys retained for backward compatibility); the two carry
+  identical values. Surfaced by the API audit.
+- **`GROMACS` and `DiffDock` are now coherent stubs.** Both are
+  exported (committed import paths) but unimplemented. Previously
+  they were *incoherent*: `GROMACS` didn't implement its `MDEngine`
+  abstract methods at all, so `GROMACS()` failed with a cryptic
+  "Can't instantiate abstract class" `TypeError` rather than a
+  meaningful message; both engines' methods raised a bare
+  `NotImplementedError` with no text. They are now coherent stubs —
+  instantiable, satisfying their respective engine ABCs
+  (`MDEngine` / `DockingEngine`), with every method raising
+  `NotImplementedError` carrying a clear message that points at the
+  working alternative (`OpenMM` / `Vina`) and the tracking issue.
+  10 new tests. Surfaced by the API audit.
+- - **Lint drift from a Ruff version bump cleared; CI lint job green
+  again.** `.pre-commit-config.yaml` pinned `ruff-pre-commit` at
+  `v0.5.0`, but the `[dev]` extra installs `ruff>=0.5` unpinned, so
+  CI resolved a much newer Ruff (0.15.x) whose added rules flagged
+  33 pre-existing issues — meaning the CI `lint` job was effectively
+  red. All 33 are now resolved: a genuine dead variable in
+  `ensembles.clustering` removed, an unused `shutil` import dropped,
+  five `pytest.raises(match=...)` patterns with unescaped regex
+  metacharacters made explicit (raw strings / escaped dots), a
+  `zip()` given an explicit `strict=`, four nested `with` statements
+  collapsed, a `getattr()` call with a string literal in
+  `ensembles.weighting` replaced by a `cast`-backed direct attribute
+  access (dropping a now-misplaced `# noqa`), and a Ruff-version
+  formatting refresh applied across 24 files (cosmetic line-joining
+  only). Two intentional-notation cases
+  are configured rather than rewritten: `allowed-confusables`
+  permits `×`, `σ`, and `–` in docstrings (matrix dimensions, the
+  standard deviation, prose dashes), and `RUF022` is per-file-ignored
+  for the two modules whose `__all__` is deliberately grouped by
+  category with section comments. The `ruff` and `mypy` pre-commit
+  pins are bumped to the versions CI resolves, so the two stay in
+  lock-step and this drift cannot silently recur. No source-behaviour
+  or test-count change (918 pass + 11 skipped, unchanged).
 - **Docs notebooks no longer use symlinks.** The walkthrough and
   example notebooks were previously symlinked from `docs/` into the
   canonical `notebooks/` directory. Symlinks broke two things: (1)
@@ -499,6 +632,112 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   the actual public attributes. Discovered while writing ensemble
   test fixtures.
 
+### Changed
+- **BREAKING: `cross_validate` now defaults to `on_error="raise"`.**
+  Previously `cross_validate` defaulted to `on_error="record"` —
+  exceptions raised by individual validators were silently caught,
+  recorded in verdict metadata, and the verdict marked
+  `passed=False`. The problem: a validator that throws on every
+  design (a misconfigured engine, a missing dependency, a bad
+  input) produced a full list of `passed=False` verdicts that
+  *looked* like a real result, hiding the bug. The new default
+  fails loud. Code that genuinely wants a batch to survive
+  individual validator failures must now pass `on_error="record"`
+  explicitly. Flagged and resolved by the API audit.
+- **The entire `molforge` package is now `mypy --strict` clean.**
+  With `wrappers` and `plugins` brought up to strict, all 77 source
+  modules across every subpackage pass `mypy --strict` with zero
+  errors. The CI `typecheck` job is correspondingly simplified: the
+  previous two-step arrangement (a strict gate on the clean
+  subpackages plus a non-blocking informational full-tree run)
+  collapses to a single `mypy src` gate that fails the build on any
+  type error. The `tests/unit/test_typing.py` regression test is
+  likewise simplified to one whole-package check. 31 errors fixed in
+  this final tranche: 20 stale `# type: ignore` comments (made
+  redundant when the optional heavy dependencies were added to the
+  mypy `ignore_missing_imports` override), four deliberate engine-
+  method `# type: ignore[override]` annotations (the concrete
+  engine wrappers refine the permissive `**kwargs` signatures of
+  their `DockingEngine` / `MDEngine` / `GenerativeEngine` abstract
+  bases — an intentional, documented refinement that mypy's strict
+  Liskov check cannot model), `cast`s for the opaque
+  `Simulation.engine_handle` inside the OpenMM wrapper and for the
+  unstubbed-dependency return values, and `Vina.dock`'s receptor
+  narrowing switched from `hasattr` to `isinstance` (a more correct
+  check that mypy can also narrow on).
+- **`molforge.ml` is now `mypy --strict` clean.** The ML subpackage
+  (sequence/structure featurization, protein-language-model
+  embeddings) joins the strict gate — eight strict-clean
+  subpackages in total, 51 source files. Six errors fixed: the four
+  numpy-widening `no-any-return`s in `embeddings.py` (resolved with
+  `cast`s), and two real type bugs in `structure_features.py` —
+  `pair_distances` and `pair_distance_features` declared
+  `atom_choice: str` but pass it to `distance_map`, which requires
+  the `Literal["ca","cb","heavy","all"]` the docstrings already
+  specify, and a coordinate feature array silently upcast to
+  float64 by a division. The `torch` and `transformers` (and
+  `colabfold`, `meeko`, `vina`) optional heavy dependencies, which
+  ship no type stubs, are added to the mypy `ignore_missing_imports`
+  override alongside the existing `Bio` / `biotite` / `mdtraj` /
+  `openmm` / `rdkit` entries. CI strict gate and the
+  `tests/unit/test_typing.py` regression test updated; only
+  `plugins` and `wrappers` remain outside the gate.
+- **Six more subpackages are now `mypy --strict` clean.**
+  `molforge.io`, `molforge.sequence`, `molforge.structure`,
+  `molforge.metrics`, `molforge.ensembles`, and
+  `molforge.validation` now pass `mypy --strict` with zero errors,
+  joining `molforge.core` — seven strict-clean subpackages in total,
+  46 source files. The 12 errors fixed were mostly numpy operations
+  mypy widens to `Any` (resolved with explicit `cast`s that document
+  the known array dtype) and two stale `type: ignore` comments; two
+  were genuine annotation bugs — `_place_hydrogens` in `dssp.py` was
+  declared to return a single array but actually returns a
+  `(coords, mask)` tuple, and `_score` in `alignment.py` was
+  declared `NDArray[np.int_]` but builds an `int32` array (`np.int_`
+  is `int64` on 64-bit platforms). The CI strict gate now covers all
+  seven subpackages; the regression test
+  (`tests/unit/test_typing.py`, moved up from `tests/unit/core/` and
+  parametrized) checks each one in-suite. The remaining subpackages
+  (`ml`, `plugins`, `wrappers`) are still tracked by the
+  non-blocking informational `mypy src` CI step.
+- **`molforge.core` is now `mypy --strict` clean, and CI enforces
+  it.** The `core` subpackage — the data model the rest of the
+  library is built on — now passes `mypy --strict` with zero
+  errors (fixed: two missing `NDArray` type arguments in
+  `AtomArray`, an `Any`-return in `Atom.coord`, and an untyped
+  `Chain.__iter__` that was suppressed with a `type: ignore`). The
+  CI `typecheck` job now runs `mypy --strict src/molforge/core/`
+  as a hard gate, with a separate non-blocking full-tree `mypy src`
+  step that keeps the remaining (out-of-`core`) type errors visible
+  while they're worked through. A new `slow`-marked regression test
+  (`tests/unit/core/test_typing.py`) runs the strict check in-suite
+  so a `core` type regression is caught locally too.
+
+### Documented
+- **`Simulation.engine_handle` contract clarified.** The attribute
+  type (`object | None`) is correct — it really is an opaque,
+  engine-specific handle — but the contract was under-specified.
+  The docstring now states explicitly that `engine_handle` is
+  engine-private (callers must not inspect it or set it), is **not
+  serialized** (it typically wraps unpicklable C-extension state;
+  persistence layers must drop it and let the engine wrapper
+  rebuild it on resume), and carries **no semver guarantee**. For
+  inspectable per-simulation data, `Simulation.metadata` is the
+  supported field. No code change. Flagged by the API audit.
+
+### Deprecated
+- **`molforge.wrappers.folding.Rosetta` is now a deprecated alias
+  for `RoseTTAFold`.** The original `rosetta.py` placeholder was
+  ambiguous about whether it referred to PyRosetta (the Baker lab's
+  classical sequence-design library) or RoseTTAFold (the deep-
+  learning model). The new real wrapper lives at
+  `RoseTTAFold` for clarity. `Rosetta` is retained as a thin
+  subclass that emits `DeprecationWarning` on construction so
+  existing imports / isinstance checks keep working through the
+  next minor release. A PyRosetta wrapper, if added, would live in
+  a separate module (`pyrosetta.py`) since PyRosetta's surface is
+  much wider than the `FoldingEngine` contract.
+
 ### Removed
 - **`tests/unit/core/test_core_types.py`.** A pre-existing fossil
   from before the view-based data-model refactor: it imported from

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: molforge
-Version: 0.2.0
+Version: 0.3.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/
@@ -43,7 +43,7 @@ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
 Classifier: Topic :: Scientific/Engineering :: Chemistry
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
-Requires-Dist: numpy>=1.24
+Requires-Dist: numpy>=2.2.6
 Requires-Dist: typing-extensions>=4.7
 Provides-Extra: all
 Requires-Dist: biopython>=1.83; extra == 'all'
@@ -94,7 +94,8 @@ Description-Content-Type: text/markdown
 # molforge
 
 [![CI](https://github.com/DoctorDean/molforge/actions/workflows/ci.yml/badge.svg)](https://github.com/DoctorDean/molforge/actions/workflows/ci.yml)
-[![PyPI version](https://img.shields.io/pypi/v/molforge.svg)](https://pypi.org/project/molforge/)
+[![PyPI version](https://img.shields.io/pypi/v/molforge.svg)](https://pypi.org/project/molforge/) 
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/molforge?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/molforge)
 [![Python versions](https://img.shields.io/pypi/pyversions/molforge.svg)](https://pypi.org/project/molforge/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)

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

@@ -1,7 +1,8 @@
 # molforge
 
 [![CI](https://github.com/DoctorDean/molforge/actions/workflows/ci.yml/badge.svg)](https://github.com/DoctorDean/molforge/actions/workflows/ci.yml)
-[![PyPI version](https://img.shields.io/pypi/v/molforge.svg)](https://pypi.org/project/molforge/)
+[![PyPI version](https://img.shields.io/pypi/v/molforge.svg)](https://pypi.org/project/molforge/) 
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/molforge?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/molforge)
 [![Python versions](https://img.shields.io/pypi/pyversions/molforge.svg)](https://pypi.org/project/molforge/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)

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

@@ -41,7 +41,7 @@ classifiers = [
 # Minimal runtime dependencies — keep this list small.
 # Heavy / optional deps go under [project.optional-dependencies].
 dependencies = [
-    "numpy>=1.24",
+    "numpy>=2.2.6",
     "typing-extensions>=4.7",
 ]
 

{molforge-0.2.0 → molforge-0.3.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.2.0"
+__version__ = "0.3.0"
 __all__ = ["__version__"]