README.md

---
title: Proteoform Analyzer
emoji: 🧬
colorFrom: indigo
colorTo: green
sdk: gradio
sdk_version: 5.39.0
python_version: "3.11"
app_file: app.py
pinned: false
license: mit
suggested_hardware: zero-a10g
short_description: An AI-powered tool to analyze proteoform effects.
---

# Proteoform Analyzer

An AI-assisted tool to analyze the effects of single-point mutations,
post-translational modifications (PTMs), and their pairwise combinations
(proteoforms) on proteins of arbitrary oligomeric state (monomers, dimers,
tetramers, hexamers, …).

## Running on this Space (ZeroGPU)

This Space uses **ZeroGPU**: a GPU is attached only for the duration of the
in-process model calls (ESM2 sequence embedding and the ESM2 zero-shot ddG
scorer), which are wrapped with `@spaces.GPU` in `app.py`.

**What runs here out of the box (CPU/GPU, no extra setup):**

- Sequence retrieval, mutation & proteoform enumeration
- ESM2 embeddings + UMAP variant map (GPU-accelerated)
- ESM2 zero-shot ddG stability scores (GPU-accelerated)
- Protein-contact-network (PCN) centralities & communities
- TM-score comparison, impact scoring, and all tables / interactive plots
- 3D structure viewer, including docked receptor+ligand and antibody complexes
  when those result files are present

**What needs extra configuration (degrades cleanly with a message otherwise):**

- **Boltz-2 folding & docking** — set a Space secret `BOLTZ_API_KEY` (and add
  `boltz-api` to `requirements.txt`) to use the hosted Boltz API. Without a key,
  mutant/proteoform structures fall back to side-chain grafting onto the WT
  backbone (TM-score == 1.0 by construction; the app shows a prominent banner
  explaining this).
- **AutoDock Vina docking**, **Molecular Dynamics**, **DiffSBDD / GNN ligand
  design**, and **RFAntibody antibody design** need additional native binaries
  and/or heavy Python wheels that are not installed on the default Space build.

See **DEPLOY_HF_ZEROGPU.md** in this repo for the full deployment guide and the
"what runs where" matrix, and **CHANGES_zerogpu.md** for the list of changes
made to enable Spaces deployment.

## Local use

```bash
pip install -r requirements.txt          # lean Space deps, or:
pip install -r proteoform_analyzer/requirements.txt   # full local deps
python -m proteoform_analyzer.gui         # Gradio GUI
python -m proteoform_analyzer.cli --help  # command-line interface
```