Peptide Visual Lab

PVL is the only peptide-prediction tool that puts every analysis in one dashboard, overlays predictions on the AlphaFold structure, and turns each analysis into a citable URL. The competition is single-algorithm CLI tools that emit static PNGs.

PVL is built for interactivity — every part of the pipeline is measured and tuned to disappear behind the result.

Measured 2026-06-22 on a fresh DESY VM (Hetzner CX33-class, 4 vCPU, container-bound). Per-stage timings are available via PVL_PERF_LOGS=1; see docs/internal/PERF_TRACE_RECIPE_2026_06_21.md.

Quick Analyze — paste a single sequence, see results in seconds.	Results Overview — classification landscape, click any region to filter.
Smart Candidate Ranking — adjustable metric weights + presets.	2D Backbone — color-coded residues from AlphaFold PDB.
Correlation Matrix — pairwise Pearson correlations with rotated headers + diverging palette.

flowchart TB
    A["👤 Researcher<br/>(Browser · Claude Desktop · Cursor · Jupyter)"] --> B
    M["🤖 LLM Agent<br/>(MCP-aware client)"] -. "Phase G1<br/>(planned v0.2)" .-> Mcp
    Mcp["🛰️ MCP Server<br/>(Python SDK)"] --> B
    B["⚛️ React + Vite + Mol*<br/>(hover-everywhere drill-down)"] -- "REST<br/>(Pydantic v2 strict)" --> C
    C["🐍 FastAPI Backend"] --> D["📦 Predictor Pipeline"]
    D --> E1["TANGO<br/>(subprocess)"]
    D --> E2["S4PRED<br/>(BiLSTM)"]
    D --> E3["FF-Helix<br/>(pure Python)"]
    D --> E4["Biochem<br/>(vectorized)"]
    C --> F1["UniProt API"]
    C --> F2["AlphaFold DB"]
    C --> G["📊 Sentry<br/>(release-tagged + rich context)"]

    classDef planned stroke-dasharray: 5 5,opacity:0.7
    class M,Mcp planned

Architectural decisions logged in docs/active/DECISIONS.md. Internal platform vision in docs/internal/TECH_PLATFORM_VISION.md.

git clone https://github.com/az-said/peptide_prediction.git
cd peptide_prediction
cp backend/.env.example backend/.env
make docker-up

Open http://localhost:3000. Done. Your data never leaves your machine.

Without S4PRED or TANGO, PVL still computes FF-Helix %, charge, hydrophobicity, μH, biochem properties, and the full classification pipeline.

Developing locally? See docs/active/HANDOFF.md §2 — Day-1 setup for the full venv + frontend + backend dev-server walkthrough.

PVL exposes an MCP server so any MCP-aware LLM client (Claude Desktop, Cursor, Continue, Cline, Windsurf) can call PVL natively — paste a UniProt accession, ask for amyloid candidates, and get back a structured analysis with a permalink you can cite.

1. Install pvl-mcp. Until the PyPI release ships, install from source:

   # from a clone of this repo
   cd mcp_server && pip install -e .
   # (post-PyPI: pip install pvl-mcp)

2. Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

   {
     "mcpServers": {
       "pvl": {
         "command": "python",
         "args": ["-m", "pvl_mcp"],
         "env": { "PVL_API_URL": "http://localhost:8000" }
       }
     }
   }

   Point PVL_API_URL at your own PVL backend (a hosted instance, your VPS, or a local uvicorn api.main:app --port 8000).

3. Restart Claude Desktop. Try these prompts:

   "Use PVL to look up its version."

   "Use PVL to analyze the sequence GIGAVLKVLTTGLPALISWIKRKRQQ and tell me whether it is FF-Helix."

   "Use PVL to search UniProt for amyloid peptides from S. aureus, length 10–50, then rank the top 5 by FF-Helix score."

The MCP server exposes the same prediction pipeline used by the web UI — every result comes back with PVL's exact category definitions (Helix / FF-Helix / SSW / FF-SSW) so the LLM can't hallucinate a Chou-Fasman propensity or confuse aggregation with fibril formation.

See docs/active/MCP_RUNBOOK.md for full configuration, the tool reference, Cursor / Continue setup, and troubleshooting.

flowchart LR
    A["📝 Paste a sequence<br/>or upload CSV/FASTA"] --> B["🔍 PVL runs<br/>TANGO · S4PRED · FF-Helix · biochem"]
    B --> C["📊 Interactive dashboard<br/>(classifications · distributions · drill-down)"]
    C --> D["🔗 Copy permalink<br/>or export figure pack"]
    D --> E["📄 Cite in your paper<br/>(Zenodo DOI · paste URL)"]

• Identify amyloid candidates in a UniProt query (e.g., S. aureus reference proteome length 10-50)
• Compare wild-type vs mutant peptide cohorts side-by-side with overlay distributions
• Generate a paper figure pack — multi-panel SVG ready for a Nature supplement
• Automate analysis from Claude Desktop (Phase G1, MCP server in v0.2)
• Find peptides similar to a reference via vector embedding search (Phase 2 v0.2)

FastAPI auto-generates OpenAPI documentation at runtime. Once the backend is running:

• Interactive docs: http://localhost:8000/api/docs
• OpenAPI JSON: http://localhost:8000/api/openapi.json
• ReDoc view: http://localhost:8000/api/redoc

Selected endpoints (full list in docs/active/CONTRACTS.md):

All request schemas use Pydantic v2 with extra="forbid" — unknown fields fail loudly with 422 (per ADR-002).

The doc tree splits into three buckets per the project's clean-push policy: active (publishable architecture + scientific reference), internal (process docs kept in repo for the why-trail), and archive (frozen historical artifacts).

make test          # Backend (pytest) — 463 deterministic, no-network tests
cd ui && npx vitest run   # Frontend (vitest) — 424 component tests
make lint          # Linters (ruff + ESLint)
make typecheck     # Type checks (mypy + tsc)
make ci            # Full pipeline

Total: 887 tests, all green. Tests are deterministic and run without network access.

peptide_prediction/
├── backend/                  # FastAPI Python backend
│   ├── api/routes/           # Route definitions
│   ├── services/             # Business logic
│   ├── schemas/              # Pydantic v2 models (extra="forbid")
│   ├── auxiliary.py          # FF-Helix + 4-category classification
│   ├── tango.py · s4pred.py  # External predictor wrappers
│   └── tests/                # 463 pytest tests
├── ui/                       # React + TypeScript frontend
│   ├── src/components/       # ~120 components incl. Mol3DViewer, SetDiagram
│   ├── src/components/drilldown/  # Universal drill-down system
│   ├── src/components/hover/      # Universal hover system
│   ├── src/lib/              # metricRegistry, permalink, sentryContext
│   ├── src/stores/           # Zustand: dataset, threshold, hover, drilldown
│   └── src/pages/            # Index, Results, PeptideDetail, QuickAnalyze
├── pvl-cli/                  # `pvl analyze` CLI (scaffolded — Wave 2)
├── pvl-py/                   # `import pvl` Python package (scaffolded — Wave 2)
├── docker/                   # Multi-stage Dockerfiles + 4 compose files
├── docs/active/              # Living documentation (24 docs)
└── docs/images/              # README screenshots

PVL is currently v0.3.0 pre-release. The pipeline implements Dr. Peleg Ragonis-Bachar's 4-category classification algorithm from Ragonis-Bachar et al. 2022 (Biomacromolecules). Her monthly scientific review is in progress; the Zenodo DOI mints on release tag.

If you use PVL in your research, please cite both the software and the underlying algorithm:

@software{pvl_2026,
  author    = {Ragonis-Bachar, Peleg and Azaizah, Said and Golubev, Aleksandr and Landau, Meytal},
  title     = {Peptide Visual Lab (PVL)},
  version   = {0.3.0},
  year      = {2026},
  url       = {https://github.com/az-said/peptide_prediction},
  doi       = {10.5281/zenodo.PENDING},
  license   = {MIT}
}

@article{ragonis_bachar_2022,
  author  = {Ragonis-Bachar, Peleg and Rayan, Bader and Barnea, Eilon and Engelberg, Yizhaq and Upcher, Alexander and Landau, Meytal},
  title   = {Natural Antimicrobial Peptides Self-assemble as α/β Chameleon Amyloids},
  journal = {Biomacromolecules},
  year    = {2022},
  volume  = {23},
  number  = {9},
  pages   = {3713--3727},
  doi     = {10.1021/acs.biomac.2c00582}
}

The Zenodo DOI is auto-assigned on each GitHub release; the badge above updates once v0.3.0 ships.

PVL also exposes a per-analysis citation hook: every analysis URL is copyable + citable via the in-app Reproducibility Ribbon. Paste a permalink in your paper to give readers the exact same view you analyzed.

See CITATION.cff for machine-readable citation metadata.

Author order on the software citation reflects scientific contribution. The corresponding author for the published paper will be Prof. Meytal Landau.

PVL stands on the shoulders of these tools and groups. Cite them where appropriate.

• Ragonis-Bachar et al. 2022 — the 4-category classification (Helix · FF-Helix · SSW · FF-SSW) implemented in this tool. Biomacromolecules 24, 413–425.
• TANGO — Fernandez-Escamilla et al., Nat Biotechnol 22, 1302–1306 (2004)
• S4PRED — Moffat & Jones, Bioinformatics 37, 3744–3751 (2021), doi:10.1093/bioinformatics/btab491
• Mol* — RCSB PDB + EBI + ETH consortium
• AlphaFold DB — Jumper et al. (2021); Varadi et al. (2024)
• DESY / CSSB — Prof. Meytal Landau lab; Dr. Aleksandr Golubev

MIT. Maintained part-time by Said with support from Peleg and Alex. See CONTRIBUTING.md for what part-time means in practice (TL;DR: 1–4 week response times during academic terms; bigger releases batched in summer breaks).