molforge 0.0.1__tar.gz

molforge-0.0.1/.gitignore

@@ -0,0 +1,74 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg
+*.egg-info/
+dist/
+build/
+develop-eggs/
+downloads/
+eggs/
+.eggs/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+MANIFEST
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Testing / coverage
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+htmlcov/
+
+# Type checkers
+.mypy_cache/
+.pytype/
+.pyre/
+.ruff_cache/
+
+# Jupyter
+.ipynb_checkpoints
+*.ipynb_checkpoints/
+
+# Editors / OS
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# Docs build output
+docs/_build/
+docs/site/
+site/
+
+# Data files (keep small fixtures only; ignore bulk data)
+data/*
+!data/.gitkeep
+!data/README.md
+
+# Project-specific
+*.log
+*.tmp

molforge-0.0.1/CHANGELOG.md

@@ -0,0 +1,240 @@
+# Changelog
+
+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
+- **`molforge.structure.dssp`: Kabsch-Sander secondary-structure assignment.**
+  - Pure-NumPy implementation of the canonical DSSP algorithm
+    (Kabsch & Sander 1983) with no external dependencies — no DSSP
+    binary required, no Biopython, no mkdssp install.
+  - Returns both the full 8-state DSSP alphabet (`H` α-helix,
+    `G` 3-10 helix, `I` π-helix, `E` β-strand, `B` β-bridge,
+    `T` turn, `S` bend, `-` coil) and the 3-state collapse
+    (`H` / `E` / `C`) via :func:`dssp_3state`.
+  - Geometric backbone amide-H placement (no need for explicit H atoms
+    in input), Kabsch-Sander electrostatic H-bond energy model, both
+    parallel and antiparallel β-bridge detection.
+  - Non-protein residues (water, ligands, ions) and residues with
+    incomplete backbones get `-` rather than crashing.
+  - Result dict also exposes the full ``(n_res, n_res)`` H-bond energy
+    matrix for downstream analyses (custom topology metrics, contact-
+    map enrichment, etc.).
+  - Replaces the previous stub that raised `NotImplementedError`.
+- New test fixture `tests/fixtures/pdb/helix.pdb` — an idealized
+  15-residue poly-alanine α-helix built from canonical (φ, ψ) values
+  via NeRF placement. Produces the expected DSSP `CHHHHHHHHHHHHHC`
+  pattern.
+- 12 unit tests covering empty / tiny inputs, helix recognition (≥7 of
+  the middle 9 residues classified as H), 3-state collapse, alphabet
+  validity, residue labels, H-bond matrix shape, and graceful handling
+  of non-protein residues.
+- **`molforge.wrappers.docking.Vina`: second fully-implemented engine wrapper.**
+  - Wraps AutoDock Vina via the
+    [`vina`](https://pypi.org/project/vina/) PyPI package, which bundles
+    the Vina binary so no manual install is required.
+  - Configurable scoring function (`vina` or `vinardo`), seed, CPU
+    thread count, and verbosity.
+  - Takes either a prepared `.pdbqt` file path or (eventually) a
+    `Protein` plus charges; the receptor / ligand preparation path for
+    `Protein` and `.pdb` / `.sdf` inputs raises a clear
+    `NotImplementedError` pointing users at meeko / AutoDockTools.
+  - Search box specified by `center` and `box_size` in Å.
+  - Multi-pose PDBQT output parsed back into `DockingResult` / `Pose`
+    objects with score (kcal/mol), RMSD lower/upper bounds vs the
+    best pose, rank, and the ligand atoms as a `Protein`.
+- **`molforge.docking`: completed ABC and result types.**
+  - `Pose` and `DockingResult` dataclasses with `best`, `top_n`,
+    iteration, and length helpers — replacing the previous stub classes
+    that raised `NotImplementedError` on construction.
+  - `DockingEngine` ABC with the formal `dock` contract; mirrors
+    `FoldingEngine` for API consistency across wrapper categories.
+  - `DockingEngineNotInstalledError` for missing-dependency error paths.
+- 28 unit tests (1 marked `@pytest.mark.slow` for the real engine):
+  construction is dependency-free, lazy import behavior, materialization
+  helpers (path passthrough plus clear errors for unsupported inputs),
+  and exhaustive PDBQT output parsing (multi-MODEL, single-pose-no-MODEL,
+  score/RMSD extraction, best-first sorting, rank reassignment, empty
+  input).
+- **`molforge.sequence`: sequence operations subpackage.**
+  - **Pairwise alignment** (`align`, `needleman_wunsch`, `smith_waterman`,
+    `Alignment`, `identity`): pure-NumPy Needleman-Wunsch (global) and
+    Smith-Waterman (local) with affine gap penalties, BLOSUM62 / PAM250
+    substitution matrices, and a `format()` method for human-readable
+    alignment blocks. No external dependencies (no Biopython, no
+    parasail) so it works in the minimal install.
+  - **Substitution matrices** (`BLOSUM62`, `PAM250`, `get_matrix`,
+    `available_matrices`): hardcoded as NumPy arrays from the NCBI BLAST
+    distribution. No runtime data-file dependency.
+  - **Mutations** (`Mutation`, `parse_mutations`, `apply_mutation`,
+    `apply_mutations`, `mutate_protein`): protein-engineering notation
+    (`A123V`, `A123V/T56K`, chain-prefixed `H:K42N`) with parsing,
+    sequence-level application, and `Protein`-level application that
+    updates the canonical `AtomArray` (sequence-only — atoms stay put;
+    side-chain rebuilding is a job for Rosetta or OpenMM).
+  - **Composition / properties** (`composition`, `length`,
+    `molecular_weight`, `gravy`, `aromaticity`): the everyday sequence
+    stats — per-residue counts/fractions, monoisotopic MW with
+    terminal water, Kyte-Doolittle GRAVY score, aromatic fraction.
+- 65 unit tests covering alignment correctness (identity, gaps, full and
+  local coverage), matrix lookup and symmetry, mutation parsing
+  (including chain prefix and multi-mutant syntax), `Protein` mutation
+  with original-unchanged semantics, and all composition helpers.
+- **`molforge.structure`: structural analysis subpackage.**
+  - **Superposition** (`superpose`, `kabsch_rmsd`, `SuperpositionResult`):
+    Kabsch / Umeyama optimal rigid-body alignment via SVD with proper-
+    rotation guarantee (no reflections), optional per-point weights for
+    masking outliers, returns rotation + translation + aligned coords +
+    RMSD.
+  - **RMSD** (`rmsd`, `rmsd_raw`, `rmsd_per_residue`): structure-to-
+    structure RMSD with five atom-subset selectors (``ca``, ``backbone``,
+    ``backbone_o``, ``all_heavy``, ``all``), optional alignment, and
+    per-residue breakdown for localizing structural differences.
+  - **Contacts** (`contact_map`, `distance_map`, `residue_contacts`):
+    binary contact maps at configurable cutoff, continuous distance
+    maps, and all-atom inter-residue contact listings with chain-pair
+    filtering for interface analysis.
+  - **Geometry** (`centroid`, `center_of_mass`, `radius_of_gyration`,
+    `bounding_box`, `translate`, `rotate`, `center_at_origin`): bulk
+    geometric properties (mass-weighted or geometric) and in-place
+    coordinate transforms that mutate the canonical `AtomArray` directly.
+  - Stubs (still `NotImplementedError`): `sasa`, `dssp`.
+- 43 unit tests covering superposition correctness (identity, translation,
+  rotation, noisy alignment, proper-rotation guarantee, weighted),
+  RMSD computations across atom subsets, contact / distance map
+  symmetry and chain filtering, and all geometry operations.
+
+- **`molforge.io.read_cif` / `write_cif`: mmCIF / PDBx implementation.**
+  - Full read/write of the ``_atom_site`` loop, the only mmCIF block
+    that holds atomic coordinate data.
+  - Hand-written tokenizer handles quoted strings, comments,
+    semicolon-bounded multi-line text fields, and the ``.``/``?`` sentinel
+    values for missing/unknown.
+  - Header metadata extracted: ``_entry.id``, ``_struct.title``,
+    ``_exptl.method``, ``_refine.ls_d_res_high``.
+  - Preference for ``auth_*`` columns (matching PDB conventions) with
+    fallback to ``label_*``, so PDB↔mmCIF round-trips preserve
+    author-assigned chain IDs and residue numbers.
+  - Reuses the same altloc resolution strategies and entity-type
+    classification as the PDB parser for behavioural consistency.
+  - ``CIFParseError`` and ``CIFWriteError`` for typed error handling.
+  - Wired into the top-level :func:`load` / :func:`save` dispatcher so
+    ``.cif`` and ``.mmcif`` extensions just work.
+- 27 unit tests covering the tokenizer, parsing, write, round-trip
+  (CIF→CIF and PDB→CIF→Protein), dispatch, and error paths.
+- **`molforge.wrappers.folding.ESMFold`: first fully-implemented engine wrapper.**
+  - Wraps Meta AI's ``facebook/esmfold_v1`` via HuggingFace
+    ``transformers``. Single-sequence folding (no MSA needed), fast,
+    GPU-friendly.
+  - Lazy import of ``torch`` and ``transformers`` keeps ``import
+    molforge`` cheap; missing-dependency errors point users at the
+    correct ``pip install 'molforge[ml]'`` extra.
+  - Configurable device (``cuda``/``cpu``/``mps``/auto), chunk size for
+    long-sequence memory management, and dtype (``float32``/``float16``).
+  - pLDDT exposed uniformly: per-atom in
+    ``metadata["confidence_per_atom"]``, per-residue in
+    ``metadata["confidence_per_residue"]``, scalar mean in
+    ``metadata["mean_confidence"]``.
+- **`FoldingEngine` ABC**: full contract definition with ``predict`` (abstract),
+  ``predict_many`` (overridable batch), and a uniform per-residue
+  confidence convention so downstream code reads engine output the same
+  way regardless of which engine produced it.
+- **`FoldingEngineNotInstalledError`**: dedicated exception type for missing
+  heavy dependencies, with actionable error messages.
+- 17 unit tests covering construction, lazy loading, sequence
+  validation, missing-dependency error paths, and post-processing
+  (PDB-to-Protein conversion with confidence metadata). The end-to-end
+  fold test is marked ``@pytest.mark.slow`` and skipped unless ``torch``
+  is installed.
+
+### Changed
+- **Project renamed from `biocore` to `molforge`** (PyPI name collision; the
+  `biocore` GitHub organization is a separate, established scientific
+  Python community). Import path is now `molforge`.
+- README rewritten around the cross-tool workflow thesis: molforge is
+  positioned as connective tissue between docking, MD, folding, design,
+  and experimental tools, rather than primarily as a data-representation
+  library.
+
+### Added
+- **`molforge.io`: file I/O subsystem.**
+  - **PDB reader and writer** (`read_pdb`, `write_pdb`, plus their
+    `*_string` variants). Handles the full wwPDB v3.30 column layout,
+    HEADER/TITLE/EXPDTA/REMARK 2 metadata, NMR multi-model files,
+    alternate locations (with three resolution strategies:
+    `highest_occupancy`, `first`, `all`, or a specific altloc id),
+    insertion codes, gzipped input/output, hydrogen filtering, and
+    automatic entity-type classification (protein / dna / rna / water /
+    ion / ligand) per residue.
+  - **FASTA reader and writer** (`read_fasta`, `write_fasta`, `*_string`
+    variants) with `FastaRecord` dataclass. Tolerant of multi-line
+    sequences, embedded digits, comments, and blank lines.
+  - **AlphaFold helpers** (`load_alphafold`, `is_alphafold_pdb`). Lifts
+    pLDDT out of the B-factor column into `protein.metadata["plddt"]`
+    (per atom), `protein.metadata["plddt_per_residue"]`, and
+    `protein.metadata["mean_plddt"]`. B-factor column preserved for
+    downstream-tool compatibility.
+  - **Top-level `load()`, `save()`, `fetch()`** dispatch by file
+    extension or explicit `format=` keyword. `fetch()` is stubbed
+    pending an HTTP utility.
+  - Format stubs (raising `NotImplementedError` with clear pointers):
+    `mmcif`, `pdbqt`, `pqr`, `sdf`, `mol2`. The API surface is committed
+    so user code targeting these formats won't break when
+    implementations land.
+  - `PDBParseError`, `PDBWriteError` for typed error handling.
+- 73 unit tests covering PDB parsing, writing, round-trip correctness on
+  real fixtures (dipeptide, NMR ensemble, altloc, insertion-coded),
+  FASTA edge cases (multiline, digits, comments, malformed input),
+  AlphaFold detection and pLDDT extraction, and dispatch behavior.
+- `ACKNOWLEDGEMENTS.md` crediting Protkit, Biotite, Biopython,
+  BioPandas, MDAnalysis, OpenMM, RDKit, and the file-format
+  specifications we implement.
+- **`molforge.core`: full implementation of the canonical data model.**
+  - `AtomArray`: flat, NumPy-backed source of truth with 15 typed fields
+    (coords, element, atom_name, residue_name, residue_id, insertion_code,
+    chain_id, b_factor, occupancy, charge, serial, record_type, entity_type,
+    altloc, model_id). Supports construction from a dict of arrays, boolean
+    selection (`select`, `where`), slicing, fancy indexing, and concatenation
+    (`append`). Lazily-computed and cached residue / chain boundary indices
+    (`residue_starts`, `chain_starts`) with explicit invalidation.
+  - `Atom`, `Residue`, `Chain`, `Protein`: lightweight hierarchical *views*
+    that hold a reference to a shared `AtomArray` plus an index range.
+    Mutations on the hierarchical side write through to the array, so the
+    two views never go out of sync.
+  - `Protein.select(**filters)`, `protein_only()`, `remove_water()` for
+    common substructure operations.
+  - First-class support for heterogeneous content: HETATM records,
+    ligands, waters, and ions are represented in the same array via
+    `record_type` and `entity_type` fields.
+  - Insertion codes, alternate locations (altloc), and multi-model
+    (NMR / trajectory) structures are modeled from day one.
+  - Constants module with three-letter ↔ one-letter mappings for the 20
+    canonical amino acids, common non-canonical residues (MSE, SEC,
+    phospho-S/T/Y, force-field-specific His variants), DNA / RNA
+    nucleotides, waters, and ions. Helper functions `three_to_one`,
+    `is_standard_amino_acid`, `is_water`, `is_ion`.
+- 74 unit tests covering `AtomArray`, hierarchical views, constants, and
+  cross-cutting hierarchical ↔ linear consistency invariants.
+- Initial repository skeleton with src-layout package structure.
+- Hierarchical data model stubs for `Protein`, `Chain`, `Residue`, `Atom`.
+- Linear / array view stubs (`AtomArray`) alongside hierarchical views.
+- Top-level subpackages: `core`, `sequence`, `structure`, `md`, `docking`,
+  `ml`, `io`, `plugins`, `metrics`.
+- Wrapper interface stubs for folding (AlphaFold/ColabFold, ESMFold, Boltz),
+  docking (AutoDock Vina, DiffDock), and MD (OpenMM, GROMACS).
+- Plugin registry stub with entry-point discovery.
+- `pyproject.toml` with PEP 621 metadata, extras (`structure`, `sequence`,
+  `md`, `docking`, `ml`, `io`, `all`, `dev`, `docs`), and tool config for
+  ruff, mypy, pytest, and coverage.
+- GitHub Actions workflows for CI (lint, type-check, tests on Python 3.10-3.12),
+  documentation build, and release-to-PyPI on tag.
+- Issue templates (bug, feature, question) and PR template.
+- `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, `CODEDoctorDeanS`.
+- Walkthrough notebook stubs for sequences, structures, MD, and docking.
+- Pinned requirements files per extra under `requirements/`.
+
+[Unreleased]: https://github.com/DoctorDean/molforge/compare/HEAD...HEAD

molforge-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dean Sherry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

molforge-0.0.1/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: molforge
+Version: 0.0.1
+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://molforge.readthedocs.io
+Project-URL: Repository, https://github.com/DoctorDean/molforge
+Project-URL: Issues, https://github.com/DoctorDean/molforge/issues
+Project-URL: Changelog, https://github.com/DoctorDean/molforge/blob/main/CHANGELOG.md
+Author: Dean Sherry
+License: MIT License
+        
+        Copyright (c) 2026 Dean Sherry
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: bioinformatics,computational-biology,docking,machine-learning,molecular-dynamics,protein-engineering,structural-biology
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+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: typing-extensions>=4.7
+Provides-Extra: all
+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: rdkit>=2023.9; extra == 'all'
+Requires-Dist: scipy>=1.11; extra == 'all'
+Requires-Dist: torch>=2.1; extra == 'all'
+Requires-Dist: transformers>=4.40; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: hypothesis>=6.92; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pre-commit>=3.6; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.5; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: twine>=4.0; extra == 'dev'
+Provides-Extra: docking
+Requires-Dist: rdkit>=2023.9; extra == 'docking'
+Provides-Extra: docs
+Requires-Dist: mkdocs-jupyter>=0.24; extra == 'docs'
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
+Provides-Extra: io
+Requires-Dist: biopython>=1.83; extra == 'io'
+Requires-Dist: biotite>=0.40; extra == 'io'
+Provides-Extra: md
+Requires-Dist: mdtraj>=1.10; extra == 'md'
+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: sequence
+Requires-Dist: biopython>=1.83; extra == 'sequence'
+Provides-Extra: structure
+Requires-Dist: biopython>=1.83; extra == 'structure'
+Requires-Dist: biotite>=0.40; extra == 'structure'
+Requires-Dist: scipy>=1.11; extra == 'structure'
+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/)
+[![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 Logo](molforge.png)
+
+> **A forge for protein workflows.** One Python script, every tool in your stack: docking, MD, folding, antibody and nanobody engineering, de novo design — without the format-conversion tax.
+
+`molforge` is an open-source Python library that lets you compose protein workflows across the tools you already use. Bring your structures and sequences in, plug in your engines of choice (Vina, OpenMM, ESMFold, AlphaFold, RFdiffusion, ProteinMPNN, your own model), and walk out with a coherent pipeline instead of five incompatible Python environments and a graveyard of conversion scripts.
+
+---
+
+## Why molforge exists
+
+Modern protein work is multi-tool by nature. A real antibody-design loop might fold a sequence with ESMFold, identify CDR loops with anarci, score binding with FoldX, dock against a target with AutoDock Vina, relax with OpenMM, then evaluate with Rosetta. **Each of those tools speaks its own dialect**: different file formats, different atom-naming conventions, different ideas of what "the structure" is. Most of an engineer's day disappears into glue code.
+
+`molforge` is the connective tissue. It provides:
+
+- A **canonical, NumPy-backed data model** that's cheap to convert in and out of — so every engine in your pipeline reads from and writes to the same representation.
+- **Thin wrappers** around the engines you already trust, with consistent interfaces (so swapping ESMFold for AlphaFold is one line, not a refactor).
+- **First-class IO** for the messy reality of structural-bio files: PDB, mmCIF, FASTA, PDBQT, PQR, SDF, MOL2, and AlphaFold predictions with pLDDT.
+- A **plugin registry** so the next docking engine, folding model, or scoring function can slot into your pipeline without forking molforge.
+
+Built as a library, not a framework: there's no orchestrator, no DAG runtime, no decorators you have to import to make things work. Use whatever workflow tool you like — Snakemake, Nextflow, Prefect, a shell script — molforge is just imports.
+
+## Design principles
+
+1. **Workflows over silos.** Every design decision is judged by "does this make it easier to chain N tools together?"
+2. **Wrappers, not reimplementations.** We don't rebuild OpenMM or AutoDock. We give them a shared vocabulary.
+3. **One data model, two views.** Hierarchical (`protein.chains["A"].residues[42]`) for biology, linear (`protein.atom_array.coords`) for ML — same data, no conversion.
+4. **Heterogeneous content is first-class.** Antibodies have glycans. Drug targets have ligands and ions. Membrane proteins have lipids. The data model handles all of it without an awkward special case for "non-protein."
+5. **Typed, tested, documented.** Strict mypy, ruff-clean, >90% coverage target.
+
+## Installation
+
+```bash
+# minimal core (data model + sequence + basic IO)
+pip install molforge
+
+# with structure analysis (RMSD, SASA, contacts)
+pip install "molforge[structure]"
+
+# with ML wrappers (torch, transformers, esm)
+pip install "molforge[ml]"
+
+# with MD support (openmm, mdtraj)
+pip install "molforge[md]"
+
+# with docking (rdkit for small molecules)
+pip install "molforge[docking]"
+
+# everything
+pip install "molforge[all]"
+
+# development
+git clone https://github.com/DoctorDean/molforge.git
+cd molforge
+pip install -e ".[dev,all]"
+```
+
+## Quickstart
+
+The smallest end-to-end example that shows the cross-tool point:
+
+```python
+import molforge as mf
+from molforge.wrappers.folding import ESMFold
+from molforge.wrappers.docking import Vina
+from molforge.wrappers.md import OpenMM
+
+# 1. Fold a sequence
+folded = ESMFold().predict("MKTVRQERLKSIVRILERSKEPVSGAQLAEELSVS...")
+
+# 2. Save as PDB, save as mmCIF, hand to anything
+mf.save(folded, "candidate.pdb")
+mf.save(folded, "candidate.cif")
+
+# 3. Dock a ligand against it (Vina-prepared PDBQT files)
+result = Vina().dock(
+    receptor="receptor.pdbqt",
+    ligand="ligand.pdbqt",
+    center=(10.0, 5.0, -2.0),
+    box_size=(20.0, 20.0, 20.0),
+)
+top_pose = result.best
+
+# 4. Drop into MD for relaxation
+trajectory = OpenMM().simulate(top_pose.complex, steps=10_000)
+
+# 5. Inspect — hierarchical or linear, your call
+print(folded.sequence)                            # one-letter per chain
+print(folded.atom_array.coords.shape)             # (N, 3) NumPy array
+ca = folded.chains["A"].residues[42].atoms["CA"]  # specific atom
+```
+
+Notice what *isn't* there: file-format conversions, atom-name remapping, hand-rolled PDB parsers, custom data classes per engine. molforge does that work so your script reads like the science you're actually doing.
+
+## Repository structure
+
+```
+molforge/
+├── src/molforge/             # Library source (src-layout)
+│   ├── core/                 # Hierarchical + linear data model
+│   ├── sequence/             # Sequence operations, alignment, mutations
+│   ├── structure/            # RMSD, SASA, contacts, geometry
+│   ├── md/                   # MD trajectories and analysis
+│   ├── docking/              # Docking abstractions and pose handling
+│   ├── ml/                   # ML utilities, featurizers, tensor views
+│   ├── io/                   # PDB, mmCIF, FASTA, PDBQT, PQR, SDF, MOL2
+│   ├── 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
+│       ├── docking/          # AutoDock Vina, DiffDock
+│       └── md/               # OpenMM, GROMACS
+├── tests/                    # pytest suite (unit + integration)
+├── docs/                     # Architecture docs and reference
+├── notebooks/                # Walkthroughs and worked examples
+├── plugins/                  # Example external plugins
+├── pyproject.toml            # Build config, deps, tool config
+└── ACKNOWLEDGEMENTS.md       # Prior art and intellectual debts
+```
+
+A deeper architecture walkthrough is in [`docs/architecture/overview.md`](docs/architecture/overview.md).
+
+## Status
+
+molforge is **pre-1.0** and under active development. What's working today:
+
+- **Core data model** — `Protein` / `Chain` / `Residue` / `Atom` over a canonical NumPy-backed `AtomArray`, with first-class heterogeneous content (ligands, water, ions, modified residues).
+- **File I/O** — full read/write for **PDB** (with NMR ensembles, altlocs, insertion codes) and **mmCIF** (the modern format for large structures); **FASTA** sequence I/O; **AlphaFold** loader that surfaces pLDDT as a first-class field. PDBQT, PQR, SDF, MOL2 are stubbed with committed APIs.
+- **Sequence operations** — pairwise **alignment** (Needleman-Wunsch / Smith-Waterman with BLOSUM62 / PAM250), point **mutations** with protein-engineering notation (`A123V`, `A123V/T56K`, `H:K42N`), composition and property helpers (MW, GRAVY, aromaticity).
+- **Structural analysis** — Kabsch/Umeyama **superposition**, **RMSD** (whole-structure and per-residue, multiple atom subsets), **contact and distance maps**, **radius of gyration**, **centroid / center of mass**, in-place **translate / rotate**, **DSSP** secondary-structure assignment (8-state and 3-state, no external binary).
+- **Two engine wrappers working end-to-end** — **ESMFold** (sequence → folded `Protein`, `pip install 'molforge[ml]'`) and **AutoDock Vina** (receptor + ligand → ranked docking poses, `pip install vina meeko`). The wrapper pattern is now validated across both folding and docking categories; the rest follow the same template.
+
+Coming next: SASA, backbone dihedrals (φ/ψ/ω), `meeko`-based receptor/ligand prep for Vina, additional engine wrappers (AlphaFold, OpenMM). See [`CHANGELOG.md`](CHANGELOG.md) for the full picture.
+
+## Acknowledgements
+
+molforge is inspired by [Protkit](https://github.com/silicogenesis/protkit) (SilicoGenesis), which pioneered the idea of a unified, hierarchical representation for protein structures in Python. molforge extends that direction toward cross-tool, cross-format workflows and a different internal architecture (NumPy-backed linear store, hierarchical views as accessors). See [`ACKNOWLEDGEMENTS.md`](ACKNOWLEDGEMENTS.md) for the longer list of projects we've learned from.
+
+## Contributing
+
+We welcome contributions. See [`CONTRIBUTING.md`](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md) before opening an issue or PR.
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).
+
+## Citation
+
+If you use `molforge` in academic work, please cite us (BibTeX coming with the first tagged release).