foldreport 0.1.0__tar.gz

foldreport-0.1.0/CLAUDE.md

@@ -0,0 +1,35 @@
+# CLAUDE.md
+
+Guidance for working in this repository.
+
+## Project
+
+**FoldReport** — point the tool at a folder of structure predictions (ColabFold,
+AlphaFold 3 Server, Boltz, OpenFold3) and get a single self-contained HTML report
+that ranks all predictions by confidence and lets you explore each one (interactive
+PAE, per-residue pLDDT, interface metrics) without installing anything else or
+opening a notebook.
+
+The full specification lives in [PLAN.md](PLAN.md).
+
+## Language policy
+
+**All code, comments, docstrings, identifiers, commit messages, documentation, and
+user-facing strings MUST be written in English.** This applies to everything in the
+repository regardless of the language used in conversation or in PLAN.md (which is in
+Spanish). Do not introduce non-English text into the codebase.
+
+## Architecture
+
+- The heart of the project is the internal representation in `foldreport/models.py`.
+  Every parser produces `list[Prediction]`; nothing downstream knows the original
+  format. Adding a tool means writing a parser, not touching the rest.
+- Missing metrics are `None`, never invented. The report renders "N/A".
+- Format detection is automatic via each parser's `can_handle()`.
+
+## Dev workflow
+
+- Use the project virtualenv at `.venv`.
+- Install in editable mode: `.venv\Scripts\python.exe -m pip install -e ".[dev]"`
+- Run tests: `.venv\Scripts\python.exe -m pytest`
+- Keep dependencies minimal — one-command install is core to adoption.

foldreport-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergio Gracia
+
+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.

foldreport-0.1.0/MANIFEST.in

@@ -0,0 +1,23 @@
+# Source distribution contents.
+# The wheel's runtime data files are declared via [tool.setuptools.package-data]
+# in pyproject.toml; this file controls what extra files ship in the sdist.
+
+include README.md
+include LICENSE
+include CLAUDE.md
+include PLAN.md
+
+# Bundled report assets (also required at runtime).
+include foldreport/report/template.html
+include foldreport/report/3Dmol-min.js
+
+# Tests and their fixtures, so the sdist is self-checking.
+recursive-include tests *.py
+recursive-include tests/data *
+
+# Keep build noise out of the sdist.
+global-exclude __pycache__ *.py[cod]
+prune .github
+prune .claude
+prune examples
+prune .venv

foldreport-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: foldreport
+Version: 0.1.0
+Summary: Unify structure-prediction outputs (ColabFold, AlphaFold 3 Server, Boltz) into a single self-contained HTML report ranked by confidence.
+Author: Sergio Gracia
+License: MIT
+Project-URL: Homepage, https://github.com/sergio-gracia/foldreport
+Project-URL: Issues, https://github.com/sergio-gracia/foldreport/issues
+Keywords: alphafold,colabfold,boltz,protein-structure,plddt,pae,bioinformatics
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Requires-Dist: matplotlib>=3.6
+Requires-Dist: gemmi>=0.6
+Requires-Dist: click>=8.1
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# FoldReport
+
+**Point it at a folder of structure predictions and get one self-contained HTML report
+that ranks them all by confidence.**
+
+### ▶ [Try the live demo report →](https://sergio-gracia.github.io/foldreport/)
+
+See exactly what you get before installing anything: the same complex predicted by all
+four supported tools (eight pooled predictions), ranked in one page. Click a row to open
+its detail card — interactive 3D viewer colored by pLDDT, per-residue pLDDT plot, PAE
+heatmap, and interface metrics. It is the exact file `foldreport` writes, served as-is.
+
+FoldReport reads the outputs of modern structure-prediction tools — **ColabFold**,
+the **AlphaFold 3 Server**, **Boltz**, and **OpenFold3** — as well as entries from the
+**AlphaFold Protein Structure Database**, and unifies them into a single navigable
+`.html` file: a confidence-ranked table on top (filterable by tool,
+name, and confidence), and a detail card per prediction with an embedded 3D viewer
+(colored by pLDDT), a per-residue pLDDT plot, an interactive PAE heatmap, and interface
+metrics (pTM, ipTM, …).
+
+The report is **one file**. No server, no notebook, no internet connection, and no
+adjacent assets — open it in any browser and share it as a single attachment.
+
+## Why
+
+Running AlphaFold is solved. The bottleneck moved *downstream*: you end up with dozens
+or hundreds of output folders, in slightly different formats, and have to decide *what
+to look at*. FoldReport answers "300 outputs from 3 tools — which ones matter?" in one
+command.
+
+## Install
+
+```bash
+pip install foldreport
+```
+
+Or from a checkout:
+
+```bash
+pip install .
+```
+
+## Quick start (copy-paste)
+
+A ready-to-run example dataset ships in the repo: the same complex predicted by all
+four supported tools (two models each, eight pooled predictions), one folder per tool.
+
+```bash
+foldreport examples/demo/colabfold examples/demo/af3_server examples/demo/boltz examples/demo/openfold3 -o report.html
+```
+
+Open `report.html` in your browser. That's it.
+
+Point it at a single run the same way — the format is autodetected:
+
+```bash
+foldreport path/to/colabfold_run -o report.html
+```
+
+Pool several runs (even from different tools) into one ranked report:
+
+```bash
+foldreport run_colabfold/ run_af3/ run_boltz/ run_openfold3/ -o combined.html
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `-o, --output` | Path of the HTML report to write (default `foldreport.html`). |
+| `-t, --title` | Title shown at the top of the report. |
+| `--csv` | Also write the ranked metrics table as CSV. |
+| `-V, --version` | Print version. |
+
+## Supported tools
+
+| Tool | Detected from | pLDDT | PAE | pTM / ipTM |
+|------|---------------|:-----:|:---:|:----------:|
+| ColabFold | `*_scores_rank_*.json` + `*_rank_*.pdb` | ✓ | ✓ | ✓ |
+| AlphaFold 3 Server | `*_summary_confidences_*.json` + `*_full_data_*.json` | ✓ | ✓ | ✓ |
+| Boltz | `confidence_*_model_*.json` + `*.npz` | ✓ | ✓ | ✓ |
+| OpenFold3 | `seed-*_sample-*/` + `*_confidences.json` + `*_summary_confidences.json` | ✓ | ✓ | ✓ |
+| AlphaFold DB | `AF-<ACC>-F*-model_v*.cif` + `*_predicted_aligned_error_v*.json` | ✓ | ✓ | — |
+
+Metrics a tool does not provide are shown as **N/A** — never fabricated.
+
+## How it works
+
+Every parser converts a tool's on-disk output into a common internal representation
+(`foldreport/models.py`). Nothing downstream — metrics, figures, report — knows the
+original format, so adding a tool means writing one parser, not touching the rest.
+Format detection is automatic; you never declare which tool produced a folder.
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/Scripts/python -m pip install -e ".[dev]"   # Windows
+.venv/bin/python    -m pip install -e ".[dev]"     # macOS/Linux
+.venv/Scripts/python -m pytest                      # run tests
+```
+
+The test fixtures are synthetic but faithful to each tool's real file layout, names,
+and JSON keys; regenerate them with `python tests/make_fixtures.py`. Regenerate the
+example dataset with `python examples/make_demo.py`.
+
+### Try it on real biological data
+
+To validate the pipeline on genuine predictions, download a small set of real proteins
+from the [AlphaFold Protein Structure Database](https://alphafold.ebi.ac.uk):
+
+```bash
+python examples/fetch_afdb.py                      # default set: INS, UBC, LYZ, HBA1
+python examples/fetch_afdb.py P01308 P0CG48 P00698 # or any UniProt accessions
+```
+
+This writes the real structures + PAE into `examples/afdb_demo/` and builds
+`examples/afdb_report.html`. It is the only network-touching part of the project and is
+fully opt-in — the test suite never hits the network.
+
+## Scope
+
+FoldReport processes *existing* predictions only. It does not run inference (no GPU, no
+model), predict mutation effects, or edit structures. The deliverable is a CLI plus a
+static HTML file — no backend, database, or accounts.
+
+## License
+
+MIT.

foldreport-0.1.0/PLAN.md

@@ -0,0 +1,209 @@
+# FoldReport — Especificación de proyecto
+
+> Brief para construir el proyecto con Claude Code. Pásale este fichero como contexto
+> inicial. Cada fase tiene criterios de aceptación claros; trabájalas en orden y no
+> empieces una hasta que la anterior pase sus criterios.
+
+---
+
+## 1. Visión en una frase
+
+Apuntas la herramienta a una carpeta de predicciones de estructura —vengan de **ColabFold**,
+del **AlphaFold 3 Server**, de **Boltz** o de **OpenFold3**— y obtienes un **único informe HTML
+autocontenido** que rankea todas las predicciones por confianza y deja explorar cada una
+(PAE interactivo, pLDDT por residuo, métricas de interfaz) sin instalar nada más ni abrir un notebook.
+
+**La cuña que nadie cubre:** multi-herramienta + por lotes + informe navegable en un solo archivo.
+Mantén esta frase como filtro: si una feature no sirve a "unificar salidas de varias
+herramientas en un informe compartible", probablemente sobra para el MVP.
+
+---
+
+## 2. El problema (por qué existe esto)
+
+- Ejecutar AlphaFold ya está resuelto (ColabFold, el AF3 Server). El cuello de botella se movió
+  al **después**: tienes decenas o cientos de carpetas de salida y necesitas decidir *qué mirar*.
+- Cada herramienta moderna escupe formatos y métricas ligeramente distintos (pLDDT, PAE, pTM,
+  ipTM, mpDockQ) con estructuras de carpeta diferentes. Comparar entre ellas hoy es manual.
+- Las herramientas existentes cubren piezas sueltas: hacen figuras de una predicción cada vez,
+  o requieren un visor pesado, o solo entienden un formato. Ninguna resuelve
+  "300 salidas de 3 herramientas, decididme cuáles importan".
+
+## 3. Usuario objetivo
+
+Biólogo estructural / bioinformático que ya tiene salidas de predicción y necesita triarlas e
+interpretarlas rápido. Asume que sabe qué es pLDDT y PAE pero no quiere escribir scripts de
+parsing cada vez.
+
+---
+
+## 4. Alcance del MVP
+
+### DENTRO (v0.1 – v1.0)
+- Ingesta de una carpeta (o varias) con predicciones.
+- Parseo robusto de **ColabFold** primero; **AF3 Server** y **Boltz** después.
+- Normalización a una representación interna común (ver §6).
+- Tabla de métricas ordenable/filtrable: una fila por predicción/modelo.
+- Figuras de calidad de publicación: PAE y pLDDT por residuo.
+- Informe HTML **autocontenido** (un solo .html, sin dependencias externas en runtime) con
+  visor 3D embebido y ranking por confianza.
+- CLI de un comando: `foldreport <carpeta> -o informe.html`.
+
+### FUERA (explícitamente, para no dispersarse)
+- Ejecutar AlphaFold / inferencia (cero GPU, cero modelo). Solo se procesan salidas existentes.
+- Predicción de efecto de mutaciones / variantes.
+- Edición o reparación de estructuras.
+- Backend con servidor, base de datos o cuentas de usuario. El entregable es CLI + HTML estático.
+- Soporte de formatos legacy raros. Empieza por lo que la comunidad usa hoy.
+
+---
+
+## 5. Stack técnico
+
+- **Lenguaje:** Python 3.10+.
+- **Parsing estructura (mmCIF/PDB):** `gemmi` (preferido) o `biotite`.
+- **Datos/tablas:** `pandas`.
+- **Figuras estáticas:** `matplotlib`.
+- **Visor 3D embebido en navegador (sin servidor):** `py3Dmol` o Mol*.
+- **CLI:** `click` o `typer`.
+- **Empaquetado:** `pyproject.toml`, instalable con `pip install .`. Objetivo: `pip install foldreport`.
+- **Tests:** `pytest`.
+
+Mantén las dependencias mínimas. Cada dependencia nueva es fricción de instalación, y la
+instalación de un comando es clave para la adopción.
+
+---
+
+## 6. Diseño de la representación interna (el corazón del proyecto)
+
+El error más caro sería acoplar el código a un formato concreto. Define **primero** una capa
+intermedia limpia y haz que cada parser produzca exactamente esto. Así añadir una herramienta
+nueva es escribir un parser, no tocar el resto.
+
+Estructuras sugeridas (ajústalas, pero respeta el principio):
+
+```python
+@dataclass
+class Prediction:
+    name: str                      # identificador legible
+    source_tool: str               # "colabfold" | "af3_server" | "boltz" | ...
+    structure_path: Path           # ruta al .cif/.pdb
+    chains: list[Chain]
+    plddt: list[float]             # por residuo, orden canónico
+    pae: np.ndarray | None         # matriz NxN o None si no hay
+    metrics: PredictionMetrics
+    raw_files: dict[str, Path]     # trazabilidad de dónde salió cada cosa
+
+@dataclass
+class PredictionMetrics:
+    mean_plddt: float
+    ptm: float | None
+    iptm: float | None
+    mpdockq: float | None
+    n_chains: int
+    n_residues: int
+    # rellena None lo que la herramienta no provea; el informe debe tolerar huecos
+
+# Contrato de parser: Path de carpeta -> list[Prediction]
+class Parser(Protocol):
+    def can_handle(self, path: Path) -> bool: ...
+    def parse(self, path: Path) -> list[Prediction]: ...
+```
+
+Principios:
+- Todo parser devuelve `list[Prediction]`. Nada aguas abajo conoce el formato original.
+- Las métricas ausentes son `None`, nunca inventadas. El informe muestra "N/A".
+- Detección automática de formato vía `can_handle()`; el usuario no debería tener que declararlo.
+
+---
+
+## 7. Estructura de ficheros sugerida
+
+```
+foldreport/
+├── pyproject.toml
+├── README.md
+├── foldreport/
+│   ├── __init__.py
+│   ├── cli.py
+│   ├── models.py            # dataclasses de §6
+│   ├── parsers/
+│   │   ├── __init__.py      # registro + autodetección
+│   │   ├── base.py          # Protocol/ABC del parser
+│   │   ├── colabfold.py
+│   │   ├── af3_server.py
+│   │   └── boltz.py
+│   ├── metrics.py           # cálculo/normalización de métricas
+│   ├── figures.py           # PAE, pLDDT (matplotlib)
+│   └── report/
+│       ├── builder.py       # ensambla el HTML
+│       └── template.html    # plantilla autocontenida
+├── tests/
+│   ├── data/                # fixtures mínimas reales de cada herramienta
+│   └── test_*.py
+└── examples/
+    └── demo/                # carpeta de ejemplo lista para `foldreport examples/demo`
+```
+
+---
+
+## 8. Hoja de ruta por fases (con criterios de aceptación)
+
+### Fase 1 — Parser ColabFold sólido (semanas 1–2)
+- Implementa `models.py` y el `Parser` base.
+- Implementa el parser de ColabFold completo.
+- **Aceptación:** dada una carpeta real de ColabFold, `parse()` devuelve `Prediction`s con
+  estructura, pLDDT, PAE y métricas correctas. Test con fixture real en `tests/data/`.
+
+### Fase 2 — Figuras y tabla de métricas (semanas 3–4)
+- `figures.py`: gráfico de PAE y de pLDDT por residuo, calidad de publicación.
+- `metrics.py`: tabla normalizada (pandas) ordenable por cualquier métrica.
+- **Aceptación:** desde una lista de `Prediction` se generan los PNG/figuras y un DataFrame
+  con una fila por predicción. Huecos como `None` se manejan sin romper.
+
+### Fase 3 — Informe HTML autocontenido (semanas 5–6)
+- Visor 3D embebido (py3Dmol/Mol*) coloreado por pLDDT.
+- Plantilla que junta: tabla rankeada arriba, detalle por predicción debajo.
+- **Aceptación:** `foldreport <carpeta> -o informe.html` produce **un solo .html** que abre en
+  el navegador sin conexión y sin ficheros adyacentes, con ranking por confianza funcional.
+
+### Fase 4 — Segundo y tercer formato + pulido (semanas 7–8)
+- Añade parser de AF3 Server (y Boltz si da tiempo). Esto valida que la abstracción de §6 aguanta.
+- README con ejemplo reproducible copy-paste, datos de prueba en el repo, `pip install` de un comando.
+- **Aceptación:** la misma orden funciona sobre carpetas de ≥2 herramientas distintas sin cambios,
+  produciendo informes equivalentes. Un usuario nuevo logra un informe en <5 min desde el README.
+
+---
+
+## 9. Qué hace que se adopte (prioridad nº1 del autor)
+
+Lo que separa la herramienta que la gente usa de la que muere en GitHub casi nunca es el código:
+
+1. **Instalación de un comando** (`pip install foldreport`).
+2. **README con un ejemplo que funciona copiando y pegando**, con datos incluidos en el repo.
+3. **Resolver UN caso de uso del todo** antes que cinco a medias.
+4. Coste de probar ≈ cero: apuntar a una carpeta y obtener algo útil en segundos.
+5. Cuando esté maduro: preprint corto en bioRxiv y difusión donde está la comunidad estructural.
+
+Regla de oro de scope: ante cualquier feature nueva, pregúntate si sirve a la frase de §1.
+Si no, va al backlog, no al MVP.
+
+---
+
+## 10. Riesgo conocido
+
+El espacio de análisis post-AlphaFold tiene varios actores (herramientas que hacen figuras de PAE,
+visores de una predicción, plugins de visores pesados). Si esto es "una más que dibuja PAE", se
+pierde. La defensa es la cuña: **unificar salidas de varias herramientas en un informe que se
+comparte como un solo archivo.** Esa combinación es lo que hoy no existe.
+
+---
+
+## 11. Primeras instrucciones para Claude Code
+
+1. Crea el esqueleto del repo según §7 con `pyproject.toml` instalable.
+2. Implementa `models.py` (§6) y `parsers/base.py` con el contrato `Parser`.
+3. Implementa `parsers/colabfold.py` y un test con una fixture mínima en `tests/data/colabfold/`.
+   (Si no tienes una salida real a mano, genera una fixture sintética fiel al formato real de
+   ColabFold y deja un TODO para sustituirla por una real.)
+4. No avances a figuras hasta que el parser pase su test.

foldreport-0.1.0/README.md

@@ -0,0 +1,129 @@
+# FoldReport
+
+**Point it at a folder of structure predictions and get one self-contained HTML report
+that ranks them all by confidence.**
+
+### ▶ [Try the live demo report →](https://sergio-gracia.github.io/foldreport/)
+
+See exactly what you get before installing anything: the same complex predicted by all
+four supported tools (eight pooled predictions), ranked in one page. Click a row to open
+its detail card — interactive 3D viewer colored by pLDDT, per-residue pLDDT plot, PAE
+heatmap, and interface metrics. It is the exact file `foldreport` writes, served as-is.
+
+FoldReport reads the outputs of modern structure-prediction tools — **ColabFold**,
+the **AlphaFold 3 Server**, **Boltz**, and **OpenFold3** — as well as entries from the
+**AlphaFold Protein Structure Database**, and unifies them into a single navigable
+`.html` file: a confidence-ranked table on top (filterable by tool,
+name, and confidence), and a detail card per prediction with an embedded 3D viewer
+(colored by pLDDT), a per-residue pLDDT plot, an interactive PAE heatmap, and interface
+metrics (pTM, ipTM, …).
+
+The report is **one file**. No server, no notebook, no internet connection, and no
+adjacent assets — open it in any browser and share it as a single attachment.
+
+## Why
+
+Running AlphaFold is solved. The bottleneck moved *downstream*: you end up with dozens
+or hundreds of output folders, in slightly different formats, and have to decide *what
+to look at*. FoldReport answers "300 outputs from 3 tools — which ones matter?" in one
+command.
+
+## Install
+
+```bash
+pip install foldreport
+```
+
+Or from a checkout:
+
+```bash
+pip install .
+```
+
+## Quick start (copy-paste)
+
+A ready-to-run example dataset ships in the repo: the same complex predicted by all
+four supported tools (two models each, eight pooled predictions), one folder per tool.
+
+```bash
+foldreport examples/demo/colabfold examples/demo/af3_server examples/demo/boltz examples/demo/openfold3 -o report.html
+```
+
+Open `report.html` in your browser. That's it.
+
+Point it at a single run the same way — the format is autodetected:
+
+```bash
+foldreport path/to/colabfold_run -o report.html
+```
+
+Pool several runs (even from different tools) into one ranked report:
+
+```bash
+foldreport run_colabfold/ run_af3/ run_boltz/ run_openfold3/ -o combined.html
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `-o, --output` | Path of the HTML report to write (default `foldreport.html`). |
+| `-t, --title` | Title shown at the top of the report. |
+| `--csv` | Also write the ranked metrics table as CSV. |
+| `-V, --version` | Print version. |
+
+## Supported tools
+
+| Tool | Detected from | pLDDT | PAE | pTM / ipTM |
+|------|---------------|:-----:|:---:|:----------:|
+| ColabFold | `*_scores_rank_*.json` + `*_rank_*.pdb` | ✓ | ✓ | ✓ |
+| AlphaFold 3 Server | `*_summary_confidences_*.json` + `*_full_data_*.json` | ✓ | ✓ | ✓ |
+| Boltz | `confidence_*_model_*.json` + `*.npz` | ✓ | ✓ | ✓ |
+| OpenFold3 | `seed-*_sample-*/` + `*_confidences.json` + `*_summary_confidences.json` | ✓ | ✓ | ✓ |
+| AlphaFold DB | `AF-<ACC>-F*-model_v*.cif` + `*_predicted_aligned_error_v*.json` | ✓ | ✓ | — |
+
+Metrics a tool does not provide are shown as **N/A** — never fabricated.
+
+## How it works
+
+Every parser converts a tool's on-disk output into a common internal representation
+(`foldreport/models.py`). Nothing downstream — metrics, figures, report — knows the
+original format, so adding a tool means writing one parser, not touching the rest.
+Format detection is automatic; you never declare which tool produced a folder.
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/Scripts/python -m pip install -e ".[dev]"   # Windows
+.venv/bin/python    -m pip install -e ".[dev]"     # macOS/Linux
+.venv/Scripts/python -m pytest                      # run tests
+```
+
+The test fixtures are synthetic but faithful to each tool's real file layout, names,
+and JSON keys; regenerate them with `python tests/make_fixtures.py`. Regenerate the
+example dataset with `python examples/make_demo.py`.
+
+### Try it on real biological data
+
+To validate the pipeline on genuine predictions, download a small set of real proteins
+from the [AlphaFold Protein Structure Database](https://alphafold.ebi.ac.uk):
+
+```bash
+python examples/fetch_afdb.py                      # default set: INS, UBC, LYZ, HBA1
+python examples/fetch_afdb.py P01308 P0CG48 P00698 # or any UniProt accessions
+```
+
+This writes the real structures + PAE into `examples/afdb_demo/` and builds
+`examples/afdb_report.html`. It is the only network-touching part of the project and is
+fully opt-in — the test suite never hits the network.
+
+## Scope
+
+FoldReport processes *existing* predictions only. It does not run inference (no GPU, no
+model), predict mutation effects, or edit structures. The deliverable is a CLI plus a
+static HTML file — no backend, database, or accounts.
+
+## License
+
+MIT.

foldreport-0.1.0/foldreport/__init__.py

@@ -0,0 +1,16 @@
+"""FoldReport — unify structure-prediction outputs into a single HTML report."""
+
+from foldreport.models import (
+    Chain,
+    Prediction,
+    PredictionMetrics,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Chain",
+    "Prediction",
+    "PredictionMetrics",
+    "__version__",
+]

foldreport-0.1.0/foldreport/cli.py

@@ -0,0 +1,78 @@
+"""Command-line interface: ``foldreport <folder> [...] -o report.html``.
+
+Point it at one or more folders of predictions. Each folder's format is autodetected;
+all predictions are pooled, ranked by confidence, and written to a single HTML file.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from foldreport import __version__
+from foldreport.metrics import ranked_dataframe
+from foldreport.parsers import detect_parser, parse_folder
+from foldreport.report import build_report
+
+
+@click.command(context_settings={"help_option_names": ["-h", "--help"]})
+@click.argument(
+    "folders",
+    nargs=-1,
+    required=True,
+    type=click.Path(exists=True, file_okay=False, dir_okay=True, path_type=Path),
+)
+@click.option(
+    "-o",
+    "--output",
+    type=click.Path(dir_okay=False, path_type=Path),
+    default=Path("foldreport.html"),
+    show_default=True,
+    help="Path of the self-contained HTML report to write.",
+)
+@click.option(
+    "-t",
+    "--title",
+    default="FoldReport",
+    show_default=True,
+    help="Title shown at the top of the report.",
+)
+@click.option(
+    "--csv",
+    type=click.Path(dir_okay=False, path_type=Path),
+    default=None,
+    help="Also write the ranked metrics table to this CSV path.",
+)
+@click.version_option(__version__, "-V", "--version", prog_name="foldreport")
+def main(folders: tuple[Path, ...], output: Path, title: str, csv: Path | None) -> None:
+    """Build a single HTML report from prediction FOLDERS.
+
+    Supported tools (autodetected): ColabFold, AlphaFold 3 Server, Boltz, OpenFold3,
+    and AlphaFold DB downloads.
+    """
+    predictions = []
+    for folder in folders:
+        parser = detect_parser(folder)
+        if parser is None:
+            click.echo(f"  ! Skipping {folder}: no supported format detected.", err=True)
+            continue
+        found = parse_folder(folder)
+        click.echo(f"  + {folder}: {len(found)} prediction(s) via '{parser.name}'.")
+        predictions.extend(found)
+
+    if not predictions:
+        click.echo("No predictions found in the given folder(s).", err=True)
+        sys.exit(1)
+
+    if csv is not None:
+        ranked_dataframe(predictions).to_csv(csv, index=False)
+        click.echo(f"  > Metrics table: {csv}")
+
+    out_path = build_report(predictions, output, title=title)
+    click.echo(f"  > Report ({len(predictions)} predictions): {out_path}")
+
+
+if __name__ == "__main__":
+    main()