feat: add structure viz

README.md

@@ -9,4 +9,52 @@ license: apache-2.0
 short_description: Ensemble generator for multi-domain proteins.
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# PepTron — Protein Ensemble Generator (Hugging Face Space)
+
+Generate **protein conformational ensembles** from an amino-acid sequence using PepTron, then explore the resulting multi-model PDB as an interactive trajectory in the browser. Check out the [paper](https://www.biorxiv.org/content/10.1101/2025.10.18.680935v2) to learn more about.
+
+This Space wraps the PepTron inference pipeline and returns a filtered ensemble PDB (when filtering succeeds), plus a 3Dmol.js-based viewer that treats multi-model PDBs as animation frames. Check out the [code](https://github.com/peptoneltd/peptron) to learn more about.
+
+## What this Space does
+
+- **Input:** a single protein sequence.  
+- **Output:** a multi-model PDB ensemble (downloadable) and an embedded 3D viewer with frame slider + play/pause.
+- **Visualization:** multi-model PDB files are loaded as frames using `viewer.addModelsAsFrames(...)`, which is the recommended 3Dmol.js pattern for trajectory-like files.
+
+## PepTron model & paper
+
+PepTron is a sequence-to-ensemble generative model designed to accurately represent protein ensembles with any level of disorder content.
+
+If you use this Space in academic work, please cite the preprint below.
+
+@article{peptone2025,
+title = {Advancing Protein Ensemble Predictions Across the Order-Disorder Continuum},
+author = {Invernizzi, Michele and Bottaro, Sandro and Streit, Julian O and Trentini, Bruno and Venanzi, Niccolo AE and Reidenbach, Danny and Lee, Youhan and Dallago, Christian and Sirelkhatim, Hassan and Jing, Bowen and Airoldi, Fabio and Lindorff-Larsen, Kresten and Fisicaro, Carlo and Tamiola, Kamil},
+year = 2025,
+journal = {bioRxiv},
+publisher = {Cold Spring Harbor Laboratory},
+doi = {10.1101/2025.10.18.680935},
+url = {https://www.biorxiv.org/content/10.1101/2025.10.18.680935v1}
+}
+
+
+Code: https://github.com/PeptoneLtd/PepTron
+
+## How to use
+
+1. Paste an amino-acid sequence in the **Sequence** box.
+2. Choose **Samples** (number of ensemble members to generate).
+3. Click **Generate** and wait for inference + conversion + filtering to complete.
+
+Tips:
+- If the viewer shows a single structure, the PDB may contain only one model; otherwise use the slider to step through frames and “Play” to animate.
+- Outputs are provided as a multi-model PDB so downstream tools can treat it like an ensemble/trajectory.
+
+## Implementation notes
+
+- This Space runs PepTron inference and then converts internal outputs to PDB ensembles before optionally filtering unphysical trajectories.
+- The embedded viewer uses 3Dmol.js and loads multi-model PDBs as frames via `addModelsAsFrames`, enabling smooth animation and frame indexing.
+
+## License & attribution
+
+PepTron and related assets are provided in the upstream repository; please follow the license terms and attribution guidelines from the PepTron project when reusing the model or code.