molforge 0.0.3__tar.gz → 0.2.0__tar.gz

{molforge-0.0.3 → molforge-0.2.0}/.gitignore

@@ -63,6 +63,11 @@ Thumbs.db
 docs/_build/
 docs/site/
 site/
+# Notebooks copied into docs/ at build time by docs/_hooks/copy_notebooks.py.
+# The canonical copies live in notebooks/; these staged copies are
+# regenerated on every build and must never be committed.
+docs/walkthroughs/*.ipynb
+docs/examples/*.ipynb
 
 # Data files (keep small fixtures only; ignore bulk data)
 data/*

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

@@ -5,8 +5,583 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- **ProteinMPNN wrapper test coverage raised from 69% to 96%.** The
+  two previously-untested seams of `wrappers.generative.proteinmpnn`
+  now have direct tests: `_parse_outputs` (FASTA-file discovery —
+  single file, multi-PDB stem matching, the `.fasta` extension, and
+  the no-output error path) and `_run_cli` (the subprocess-driving
+  seam, exercised with a mocked `subprocess.run` so neither
+  ProteinMPNN nor torch need be installed — covering command
+  assembly, `chains_to_design` / `fixed_positions` / `ca_only` /
+  `use_soluble_model` flag pass-through, the public `generate()`
+  entry point, and `CalledProcessError` → `RuntimeError` translation).
+  Edge-case tests for the `_parse_metadata` header parser (numeric vs.
+  string values, tokens without `=`) were also added. 12 new tests
+  (17 → 29 in the file).
+- **Performance benchmark suite (`tests/benchmarks/`).** Baseline
+  timings for the five structural-analysis functions most likely to
+  sit in a pipeline inner loop: RMSD (with and without Kabsch
+  superposition), DSSP, lDDT, distance/contact maps, and global /
+  local sequence alignment. 8 benchmarks total, run against a
+  synthetic 200-residue protein generated parametrically (an
+  idealized alpha-helix with valid per-residue backbone geometry —
+  reproducible, no large fixture files). Built on `pytest-benchmark`
+  (added to the `[dev]` extra). The benchmarks are marked
+  `benchmark` *and* `slow`, so a normal `pytest` run and the CI
+  `test` job (`-m "not slow"`) skip them; run them explicitly with
+  `pytest -m benchmark`. A new non-blocking CI `benchmark` job
+  exercises them on every push so a broken benchmark is caught,
+  while timing variance on shared runners never gates the build —
+  for real regression tracking, save a local baseline with
+  `pytest -m benchmark --benchmark-save=baseline` and compare. The
+  suite skips cleanly (rather than erroring) when `pytest-benchmark`
+  isn't installed.
+- **`io.fetch` is now implemented.** `molforge.io.fetch` — exported
+  but previously a `NotImplementedError` stub — now downloads
+  structures from the RCSB Protein Data Bank
+  (`source="rcsb"`, the default) or the AlphaFold Protein Structure
+  Database (`source="alphafold"`), in PDB or mmCIF format. It uses
+  only the standard library (`urllib`), so it adds no dependency.
+  Network and HTTP-404 failures surface as a clear `OSError` with
+  the failing URL; bad arguments raise `ValueError`. 7 new tests
+  (argument validation + mocked-network success and failure paths).
+  Surfaced by the API audit.
+- **`docs/architecture/api-stability.md` — API stability reference.**
+  New documentation page recording the pre-1.0 API audit: which
+  parts of the public surface are committed (semver-protected) vs.
+  tentative (may still change), the audit-driven changes, and the
+  contract for engine-private fields. Added to the docs nav under
+  Architecture.
+- **`molforge.core.metadata_keys` — documented vocabulary for
+  `Protein.metadata`.** `Protein.metadata` remains a free-form
+  `dict[str, Any]` (no breaking change), but the keys molforge's own
+  parsers and engine wrappers produce are now a documented, stable
+  contract. The new module provides string constants for every such
+  key (`ENGINE`, `MEAN_CONFIDENCE`, `PDB_ID`, `PAE_INTER`, ...), a
+  `ProteinMetadata` TypedDict (`total=False`) re-exported from
+  `molforge.core` for editor/mypy support, and a `DOCUMENTED_KEYS`
+  frozenset. Keys cover three groups: structural-IO header keys (PDB
+  / mmCIF parsers), uniform folding-engine keys (set by every folding
+  wrapper), and engine-specific folding keys. The PDB/mmCIF parsers
+  and all four folding wrappers now write metadata via these
+  constants, so a key typo is an import-time `NameError` rather than
+  a silently-missing key. Keys outside the documented vocabulary are
+  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
+  al. 2024, *Science* 384: eadl2528). Like Boltz, RFAA is driven via
+  subprocess — invocation is `python -m rf2aa.run_inference
+  --config-name <name>` from inside the cloned repo with a Hydra
+  config the wrapper writes to a temporary directory. Constructor
+  resolves the repo via explicit `repo_dir=` or the `RFAA_HOME`
+  environment variable; checks for both directory existence and an
+  `rf2aa/` subdirectory before invocation. Supports custom Python
+  executable (for callers whose conda env is separate from
+  molforge's), the `loader_params.MAXCYCLE` override RFAA recommends
+  for hard cases, custom job naming, and arbitrary Hydra-style
+  overrides via `extra_overrides=`. Output post-processing parses
+  the PDB (per-atom pLDDT in the B-factor column) plus the
+  `*_aux.pt` PyTorch confidence file when torch is importable —
+  torch tensors converted to NumPy on the way out. Surfaces the
+  uniform folding-engine metadata keys
+  (`confidence_per_residue`, `confidence_per_atom`,
+  `mean_confidence`) plus RFAA-specific tensors (`pae`, `pde`,
+  `mean_pae`, `pae_prot`, `pae_inter` — the last is RFAA's headline
+  metric, <10 = high-quality interface). Degrades gracefully when
+  torch isn't installed or the aux file is malformed: PDB-derived
+  confidence is still populated. v1 scope is single-chain protein
+  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:
+  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 +
+  confidence JSON sidecar. Supports both `boltz1` and `boltz2`
+  (default `boltz2`), MSA server toggling (`use_msa_server=True`
+  default; pass `False` for fast single-sequence inference),
+  configurable recycling steps, diffusion samples, sampling steps,
+  CPU/GPU routing via `--accelerator`, custom executable path, and
+  custom weights cache via `BOLTZ_CACHE`. Lazy CLI detection
+  (`shutil.which("boltz")`) — construction never touches the binary;
+  the first `predict()` call resolves it or raises a
+  `FoldingEngineNotInstalledError` with install hints. Output
+  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
+  + 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
+  collection, subprocess invocation (with mocked `subprocess.run`),
+  and CIF post-processing in isolation. Total test count: 784 → 830
+  passed + 9 skipped.
+- **`molforge.ensembles` — weighted statistics over pose ensembles.**
+  New top-level subpackage with seven public functions covering the
+  four standard analyses run against docking output:
+
+  - **Weighting:** `boltzmann_weights` (numerically-stable softmax
+    over scores, with physical defaults — kT at 298 K, 0.593 kcal/mol
+    — and a `lower_is_better` flag for ML confidence scores) and
+    `resample` (weighted bootstrap of pose objects, reproducible
+    with explicit `rng`).
+  - **Geometry:** `pairwise_rmsd` (N×N heavy-atom RMSD matrix over
+    ligand poses, vectorized in NumPy) and `pose_diversity` (summary
+    statistics over the upper triangle — min/max/mean/median/std —
+    for "did the docking actually explore?" diagnostics).
+  - **Clustering:** `pose_clusters` (hierarchical average-linkage
+    clustering at a user-specified RMSD cutoff, pure NumPy with no
+    scipy dependency; returns a `PoseClusteringResult` with cluster
+    labels, ordered `PoseCluster` objects with medoid index and
+    intra-cluster mean RMSD, and the underlying RMSD matrix).
+  - **Spatial:** `binding_site_density` (3D histogram of ligand
+    heavy-atom positions, auto-sized bounding box with configurable
+    padding or explicit `origin`/`shape` for comparative grids,
+    Boltzmann-weightable; returns a `DensityGrid` with a
+    `coordinate_of(ijk)` helper).
+  - **Consensus:** `consensus_pose` (medoid pick — returns one of
+    the input poses by reference — or weighted-mean synthesis —
+    returns a new `Pose` with averaged coords and weighted-average
+    score, marked in `metadata`).
+
+  Designed as a top-level subpackage (not under `docking`) because
+  the primitives generalize to MD trajectories and other structural
+  ensembles; v1 focuses on docking poses since that's the immediately
+  useful case. 1094 source lines across 5 modules, 120 new tests
+  across 5 test files. Total test count: 664 → 784 passed + 8 skipped.
+
+  Limitations documented in the module docstring and user guide:
+  pose RMSD is order-sensitive (upper-bound for symmetric ligands),
+  receptor is treated as fixed, and clustering is O(n³) and best
+  suited for ensembles of n ≲ 200 (single-docking-run sizes; MD-scale
+  ensembles would benefit from scipy's optimized linkage in a future
+  enhancement).
+- **Docs: ensembles user guide + API reference.** `docs/guide/ensembles.md`
+  walks through the canonical workflow (score → weights → diversity →
+  clusters → density → consensus); `docs/reference/ensembles.md`
+  renders the full API via mkdocstrings. Added to mkdocs nav.
+- **Notebook rendering via mkdocs-jupyter.** All six walkthrough
+  notebooks (`notebooks/walkthroughs/01_sequences.ipynb` through
+  `06_plugin_authoring.ipynb`) and all three example notebooks
+  (`cross_engine_validation`, `de_novo_design`, `end_to_end_design`)
+  now render as proper docs pages alongside the rest of the site.
+  Notebooks live at their canonical `notebooks/` location (where CI
+  executes them); they're symlinked into `docs/walkthroughs/` and
+  `docs/examples/` so mkdocs-jupyter can find them inside `docs_dir`
+  without duplicating files. `execute: false` in the plugin config —
+  the docs build never re-runs notebooks; it renders the pre-baked
+  outputs that are already committed to the repo (matching the CI
+  setup that catches notebook drift separately). A new
+  `docs/examples/index.md` landing page gives a 1-line summary of
+  each example. Total site size now ~7.6 MB across 24 pages; the
+  notebook pages average ~700 KB each (mkdocs-jupyter bundles
+  notebook CSS/JS per page). Build time ~6 s.
+- **Docs CI + GitHub Pages deployment.** `.github/workflows/docs.yml`
+  rewritten from the placeholder `echo` into a real two-job workflow:
+  `build` runs `mkdocs build --strict` on every push and PR (catches
+  broken nav links, unresolved cross-references, missing
+  mkdocstrings symbols), and `deploy` runs only on pushes to
+  `main`/`master`, using the modern `actions/deploy-pages@v4` flow
+  (no `gh-pages` orphan branch). The deploy job has `pages: write`
+  and `id-token: write` permissions, is gated behind a
+  `github-pages` environment, and uses a `pages` concurrency group
+  with `cancel-in-progress: false` so concurrent deploys queue
+  rather than thrash. CI install is just `pip install -e
+  ".[docs]" ruff` — molforge's lazy-import discipline means no
+  torch / scipy / openmm / biopython is needed at doc-build time,
+  which keeps the docs job under a minute. Verified locally by
+  building strictly in a fresh venv with only `[docs]` installed.
+- **API reference pages live, strict mkdocs build green.** Eleven
+  reference pages now render real API content via mkdocstrings, with
+  `molforge.wrappers` split into a router landing page plus four
+  per-subcategory pages (folding, docking, md, generative) — totalling
+  ~1.2 MB of rendered API HTML across 15 reference pages. `mkdocs
+  build --strict` is the local + CI check, with zero warnings.
+- **mkdocs site skeleton (`docs/`, `mkdocs.yml`).** First end-to-end
+  buildable docs site, replacing the half-finished biocore-era stub.
+  Material for MkDocs theme with light/dark toggle, indigo palette,
+  navigation tabs, edit-on-GitHub links, and snippets-driven content
+  reuse. `mkdocstrings[python]` wired up against `src/` with
+  Google-style docstring parsing, source-order member listing, and
+  underscore filtering. Site is organized into five top-level
+  sections — Getting started, User guide, Architecture, API
+  reference, Project — and `mkdocs build` runs in ~2 s producing
+  17 pages including 11 stubbed API-reference pages (one per
+  subpackage, each rendering the live `__all__`). API-reference
+  content fills out in the next commit; this commit lands the
+  structure, theme, configuration, and all hand-written guide
+  prose. Stale `docs/source/` directory removed.
+- **Realistic PDB fixtures + 29 new integration tests.**
+  Three new fixtures handcrafted from canonical bond lengths and
+  angles (Engh & Huber 1991) to exercise real-PDB code paths that
+  synthetic fixtures structurally can't:
+  - **`real_small_protein.pdb`** (193 atoms, 24 residues): mixed
+    helix/loop/strand topology with **all 20 standard amino acids
+    plus PRO**. Every residue carries its full canonical atom set,
+    so aromatic-ring parsing (PHE/TYR/TRP/HIS), branched side
+    chains (LEU/ILE/VAL), and the PRO ring-closure case all get
+    exercised. B-factors vary realistically (edges higher than
+    core, ~16-45 Ų). The helix is left-handed due to the NeRF
+    sign convention — documented honestly in a REMARK and in the
+    relevant test — which doesn't affect DSSP H-bond detection or
+    most other geometric analyses.
+  - **`real_with_altloc_sidechains.pdb`** (97 atoms, 12 residues):
+    same backbone as the first 12 residues of `real_small_protein`,
+    but with **A/B alternative conformations spanning the full
+    side chain** at LEU 2 (CB/CG/CD1/CD2) and SER 9 (CB/OG).
+    Occupancies 0.60/0.40. Replaces the prior 8-atom
+    `with_altloc.pdb` for any test that needs multi-atom altloc
+    context (the old one is kept for parser-level smoke tests).
+  - **`real_with_ligand_realistic.pdb`** (76 atoms, 13 residues
+    across 3 chains): 8-residue helix + a **benzene ligand** (BNZ,
+    6 aromatic carbons in a proper hexagonal ring at canonical 1.4 Å
+    spacing) + **a zinc ion** (ZN, properly classified as ion not
+    ligand thanks to the corrected element column) + **3
+    crystallographic waters** (HOH, classified as water). Replaces
+    `mini_with_ligand.pdb`'s fake imidazole + waters with proper
+    multi-chain hetero-atom chemistry.
+- 29 integration tests in `tests/integration/test_real_fixtures.py`
+  organized by code path (fixture loading, entity-type classification,
+  full side-chain atom counts, multi-atom alt-loc handling under all
+  four `altloc=` modes, write-then-read round-trip preservation,
+  structural-analysis algorithms exercised on the realistic protein,
+  ML featurization on full side chains, and sequence mutation through
+  `mutate_protein`). Each test class is named after the code path
+  it exercises rather than the fixture, so failures point at the
+  broken behavior rather than the test fixture.
+- Test coverage now stands at **664 passing + 8 correctly skipped**
+  (+29 from the new fixtures), with the integration suite growing
+  from 19 to 48 tests.
+- **[`notebooks/examples/cross_engine_validation.ipynb`](notebooks/examples/cross_engine_validation.ipynb)**:
+  20-cell worked example of the cross-validator consensus pattern.
+  Uses two deterministic synthetic validators (mimicking
+  ESMFold-like and AlphaFold-like output) to walk through:
+  single-validator `cross_validate`, the strict / permissive /
+  majority consensus modes, drilling into a borderline design to
+  see which validator disagreed, and ranking the survivors. End-
+  to-end executable without GPU; the validator stubs are designed
+  so the cross-architecture-disagreement pattern (one model
+  overconfident, one model rejecting) is clearly visible on a
+  single sample design.
+- Both this new notebook and the
+  [`05_ml_featurization`](notebooks/walkthroughs/05_ml_featurization.ipynb)
+  one are now in the CI's executable allowlist (so any drift
+  between the notebook outputs and library behavior breaks CI).
+- **CI now executes runnable notebooks.** A new `notebooks` job in
+  `.github/workflows/ci.yml` parse-validates every notebook in
+  `notebooks/` and executes the four that don't require external
+  engines (`01_sequences`, `02_structures`,
+  `05_ml_featurization`, `06_plugin_authoring`) top-to-bottom
+  against the freshly-installed library. Catches the class of bug
+  where a notebook's outputs go silently out of sync with the
+  library — if any cell raises, CI fails.
+- **`scripts/execute_notebooks.py`**: the underlying executor.
+  Usable locally as `python scripts/execute_notebooks.py` (or
+  `--check-only` for parse-only). Maintains explicit allowlists
+  for executable vs. parse-only notebooks; updating either list is
+  the only thing required when adding a new notebook.
+- `nbclient>=0.10` and `ipykernel>=6.29` added to the `[dev]`
+  extra so the script is runnable in any dev environment via
+  `pip install -e ".[dev]"`.
+- **`molforge.plugins.discover()` implemented.** Was previously
+  raising `NotImplementedError`; now walks Python entry points
+  under the `molforge.plugins` group via
+  `importlib.metadata.entry_points`. Each entry point's registration
+  function is called once. Broken plugins (failed import, register
+  function raises) are tolerated and silently skipped so one bad
+  plugin can't break every downstream user of molforge. Returns the
+  list of successfully-loaded entry-point names so callers can
+  introspect what's available. Companion `clear()` exported for
+  test isolation.
+- **[`notebooks/walkthroughs/06_plugin_authoring.ipynb`](notebooks/walkthroughs/06_plugin_authoring.ipynb)**:
+  the last walkthrough stub from the v0.0.1 skeleton is now live.
+  14-cell tour of the plugin registry: when to use it vs. direct
+  imports, how to register engines / parsers / scorers, the
+  inline-vs-entry-point distinction, and how the
+  `pyproject.toml` entry-point declaration translates into
+  auto-discovery. Includes a runnable `RandomFolder` toy engine,
+  a minimal `.xyz` parser, and a `hydrophobic_fraction` scorer
+  registered inline so the notebook executes end-to-end without
+  installing anything extra.
+- 11 new plugin-registry tests bringing total registry coverage
+  to 12: basic register / available / get round-trip, all three
+  kinds (engine / parser / scorer), `clear()` isolation, and
+  `discover()` against a mocked `importlib.metadata.entry_points`
+  covering the multi-plugin case, the broken-plugin tolerance, and
+  the empty-entry-points fallthrough.
+
+### Fixed
+- **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)
+  extracting a release tarball on Windows failed with "a required
+  privilege is not held by the client" because creating symlinks
+  needs a privilege normal accounts lack, and (2) the GitHub Pages
+  docs build failed in strict mode because `actions/checkout`
+  didn't preserve the links, leaving nine dangling `nav` references
+  (13 strict-mode warnings, non-zero exit). Replaced with a build
+  hook (`docs/_hooks/copy_notebooks.py`, registered via the
+  `hooks:` key in `mkdocs.yml`) that copies the notebooks from
+  `notebooks/` into `docs/` during `on_config`, before mkdocs's
+  file discovery runs so mkdocs-jupyter renders them normally. The
+  copies are git-ignored; the notebooks remain single-source in
+  `notebooks/`. No symlinks anywhere in the repo, and the tarball
+  extracts cleanly on every platform.
+- **`docs/guide/data-model.md` field names.** Two rows in the
+  `AtomArray` schema table used pre-rename names (`res_name`,
+  `res_id`); corrected to `residue_name`, `residue_id` to match
+  the actual public attributes. Discovered while writing ensemble
+  test fixtures.
+
+### Removed
+- **`tests/unit/core/test_core_types.py`.** A pre-existing fossil
+  from before the view-based data-model refactor: it imported from
+  `biocore.core` (the pre-rename namespace) and called constructors
+  like `Chain(chain_id="A")` and `Residue(name="ALA", seq_id=1)`
+  that no longer match the current view-based signatures (`Chain`,
+  `Residue`, and `Atom` are now views over an `AtomArray` and take
+  `(array, start, end)` not standalone keyword arguments). The
+  assertions it made were already fully covered by
+  `test_hierarchy.py` (260 lines, with dedicated `TestAtom`,
+  `TestResidue`, `TestChain`, `TestProtein`, and `TestConsistency`
+  classes) and `test_atom_array.py` (210 lines). Removing the
+  fossil unblocks the full test suite from running cleanly under
+  `pytest` (previously needed `--ignore` for that one file).
+  Headline test count unchanged: 664 + 8 skipped.
+
+## [v0.1.0] 2026-05-20 
+
+- **`molforge.validation`: cross-validation utilities for protein
+  design.** Captures the common pattern of "score designs across
+  multiple validators and combine results" that was previously
+  hand-rolled as list comprehensions in user code.
+  - **`Criterion`**: declarative success conditions (e.g.
+    `Criterion.gt("plddt", 80)`). Atomic comparisons via the six
+    standard operators (`gt` / `ge` / `lt` / `le` / `eq` / `ne`),
+    composable with the standard logical operators (`&` for AND,
+    `|` for OR, `~` for NOT) to express arbitrarily complex success
+    rules. Tracks which metrics it references via
+    `criterion.metric_names`, useful for upstream validation.
+  - **`CriteriaSet`**: a named collection of criteria evaluated
+    together, returning per-criterion pass/fail for diagnostics
+    rather than just an opaque boolean. Implicit AND across criteria.
+  - **`Verdict`**: per-design result combining metric values,
+    per-criterion results, an overall pass/fail, and a sortable
+    score. Exposes `failed_criteria` / `passed_criteria` properties
+    for inspection.
+  - **`cross_validate(designs, validators, criteria)`**: the
+    workhorse. Runs every design through every validator, namespaces
+    metrics by validator name (`"esmfold.plddt"` not just `"plddt"`),
+    applies criteria, returns ranked verdicts. Handles validator
+    exceptions gracefully (default: record in metadata + mark
+    failed; opt-in propagation via `on_error="raise"`).
+  - **`consensus(verdict_lists, mode=...)`**: merges verdict lists
+    across validators under a chosen rule (`"all"` / `"any"` /
+    `"majority"` / explicit `"threshold"` count). Joins by
+    `design_id`; metric values from every validator are preserved
+    in the merged `Verdict.values`; per-criterion pass/fail is
+    namespaced by validator to keep diagnostics distinguishable.
+  - **`rank_verdicts(verdicts, only_passed=..., by=...)`**: ranking
+    helper. Defaults to ascending score (lower-is-better); can
+    filter to only-passed; can sort by an arbitrary metric name
+    instead of the score.
+
+### Changed
+- **Docstring normalization for griffe.** Twelve docstrings across
+  `metrics/{dockq,gdt,lddt}`, `ml/{graph,structure_features}`,
+  `sequence/alignment`, `structure/{contacts,dihedrals,rmsd,sasa}`,
+  and `wrappers/folding/{alphafold,esmfold}` rewritten so each
+  parameter gets its own line in the `Args:` block (instead of
+  comma-grouping like `a, b: ...`), and continuation lines under
+  bullet points are re-indented to 8 spaces. No behavior or
+  signature changes; griffe was the only consumer mis-parsing them,
+  but the fix also makes the rendered tables clearer (each
+  parameter gets its own row). 664 + 8 skipped tests, unchanged.
+
+### Removed
+- **`tests/unit/core/test_core_types.py`.** A pre-existing fossil
+  from before the view-based data-model refactor: it imported from
+  `biocore.core` (the pre-rename namespace) and called constructors
+  like `Chain(chain_id="A")` and `Residue(name="ALA", seq_id=1)`
+  that no longer match the current view-based signatures (`Chain`,
+  `Residue`, and `Atom` are now views over an `AtomArray` and take
+  `(array, start, end)` not standalone keyword arguments). The
+  assertions it made were already fully covered by
+  `test_hierarchy.py` (260 lines, with dedicated `TestAtom`,
+  `TestResidue`, `TestChain`, `TestProtein`, and `TestConsistency`
+  classes) and `test_atom_array.py` (210 lines). Removing the
+  fossil unblocks the full test suite from running cleanly under
+  `pytest` (previously needed `--ignore` for that one file).
+  Headline test count unchanged: 664 + 8 skipped.
+
+## [v0.0.3] 2026-05-20 
 
-### [v0.0.3] 2026-05-20 
 - **De novo design notebook updated**: the `de_novo_design.ipynb`
   example now includes a section demonstrating the validation
   utilities — declarative `CriteriaSet`, `cross_validate` against a