🧬 Venom-to-Drug Hallucinator

De Novo Therapeutic Peptide Design — NaV1.7 Pain-Channel Blockers

Generative AI pipeline that hallucinates novel venom-mimetic peptides, fully offline on a consumer CPU.

---

What This Is

Animal venoms (tarantula ProTx-II, centipede Ssm6a, cone-snail μ-conotoxins) contain peptides that selectively block the NaV1.7 sodium channel — a validated, non-opioid analgesic target. This project uses generative protein-design models to invent entirely new peptides with the same pain-blocking geometry:

NaV1.7 target ─▶ RFdiffusion ─▶ ProteinMPNN ─▶ ESMFold ─▶ Top-N candidates ─▶ Dashboard
  (binding site)   (backbones)    (sequences)   (verify)     (ranked)         (3D explore)

Every inference step runs offline on CPU (no NVIDIA GPU required).

---

Status

Phase	Scope	State
0	Environment & scaffolding	✅ Complete
1	Data acquisition & target prep	✅ Complete
2	Backbone generation (RFdiffusion)	✅ Operational (parallel + streaming)
3	Sequence design (ProteinMPNN)	✅ Operational (amino-acid bias)
4	Structure verification (ESMFold + metrics)	✅ Operational (TM-score, pLDDT, RMSD, interface contacts)
5	Interactive dashboard (Streamlit)	✅ Operational (3D viewer + metrics panel)

End-to-end validated: Orchestrator folded ProTx-II (30 aa, 6 Cys) on CPU → pLDDT 89.9, TM 0.625, RMSD 1.24 Å, composite 0.609.

---

Disk layout: Code lives on the Git partition. All data, model weights, HF/torch caches, and pipeline outputs live under data_root to keep the code partition lean. Configure in config.yaml or via VENOM_DATA_ROOT in .env.

---

Quick Start

Prerequisites

• Python 3.11 — system Python 3.14 is not yet supported by the ML stack (torch, dgl, transformers).
• A .venv created with Python 3.11.

1. Bootstrap the environment

# Create the venv (one-time)
python3.11 -m venv .venv
source .venv/bin/activate

# Install in stages (core + data + viz + dev tools)
bash setup.sh

# Add ML stack (torch CPU, ESMFold, ProteinMPNN, tmtools)
bash setup.sh --ml

# Add dashboard dependencies (Streamlit + stmol)
bash setup.sh --app

# Or install everything at once
bash setup.sh --all

2. Configure paths (optional)

cp .env.example .env
# Edit data_root, cache dirs, DGLBACKEND if needed
# Defaults work for the reference hardware

3. Download data & prepare target

source .venv/bin/activate

# Download NaV1.7 target (7W9M), reference toxins, ToxProt sequences
python data/download_targets.py
python data/download_references.py
python data/download_toxprot.py

4. Run the pipeline

Two orchestration modes are available:

Option A: Batch Pipeline (all-at-once)

Generates all backbones → all sequences → all folds → scores → leaderboard.

# Full pipeline (Phases 2→3→4)
python pipeline/run_full_pipeline.py

# Skip backbone generation (reuse existing backbones)
python pipeline/run_full_pipeline.py --skip-backbones

# Skip sequence design (reuse existing sequences)
python pipeline/run_full_pipeline.py --skip-sequences

# Start from pre-existing sequences (Phase 4 only)
python pipeline/run_full_pipeline.py --from-sequences path/to/top_sequences.json

# Force regeneration (ignore cached outputs)
python pipeline/run_full_pipeline.py --force

# Dry-run (print RFdiffusion commands without executing)
python pipeline/run_full_pipeline.py --dry-run

# Skip reference toxin TM-score comparison
python pipeline/run_full_pipeline.py --no-references

Batch pipeline CLI flags:

Flag	Effect
--skip-backbones	Use existing backbone PDBs; skip RFdiffusion
--skip-sequences	Use existing top_sequences.json; skip ProteinMPNN
--from-sequences FILE	Start at Phase 4 with a pre-built sequences file
--no-references	Skip toxin TM-score comparison in Phase 4
--dry-run	Print RFdiffusion commands; don't execute
--force	Regenerate outputs even if they already exist

Option B: Streaming Pipeline (continuous)

Processes each design through the full pipeline (Phase 2→3→4) as soon as its backbone is generated. Runs indefinitely until target_successes passing designs are found, or max_attempts is exhausted. ESMFold stays loaded throughout (~8.4 GB) to amortize load cost.

# Default: find 5 successes, max 1000 attempts
python pipeline/streaming_pipeline.py

# Custom targets
python pipeline/streaming_pipeline.py --target-successes 10 --max-attempts 500

# Limit concurrent RFdiffusion workers (for RAM management)
python pipeline/streaming_pipeline.py --workers 2

# Skip reference toxin comparison
python pipeline/streaming_pipeline.py --no-references

Streaming pipeline CLI flags:

Flag	Effect
--target-successes N	Stop after N designs pass all success criteria (default: 5)
--max-attempts N	Upper bound on backbone designs to try (default: 1000)
--workers N	Concurrent RFdiffusion workers (default: min(config, 4))
--no-references	Skip toxin TM-score comparison

Features:

• Streaming results — see scores as designs arrive.
• Cross-run continuity — persistent design tracker prevents file name collisions.
• Graceful shutdown — Ctrl+C saves progress; next run resumes numbering.

RAM budget (32 GB machine):

Component	Footprint
ESMFold (kept hot)	~8.4 GB
RFdiffusion (per worker)	~1.5 GB
ProteinMPNN	~0.3 GB
System / overhead	~4 GB
Safe max workers	4 (concurrent with ESMFold)

5. Explore results in the dashboard

# Install dashboard deps if not already
bash setup.sh --app

# Launch
streamlit run app/streamlit_app.py

The dashboard provides:

• 3D molecular viewer — target channel (orange), designed peptide (green), reference toxin (blue).
• Metrics panel — pLDDT, TM-score, RMSD, interface contacts, H-bonds, composite score.
• Sequence viewer — amino acid composition breakdown with cysteine highlighting.
• Pipeline flow — visual indicator of pipeline phases and status.

---

Project Layout

venom_to_drug/
├── venom/              # Shared core: config.py (Settings singleton), logging, async HTTP client
├── data/               # Phase 1 download scripts (target, references, ToxProt)
├── pipeline/           # Phases 2-4 + orchestrators
│   ├── run_full_pipeline.py          # Batch mode orchestrator
│   ├── streaming_pipeline.py         # Streaming mode orchestrator
│   ├── backbone_generation.py        # RFdiffusion contig builder + subprocess runner
│   ├── parallel_backbone_generation.py  # Multi-worker async backbone generation
│   ├── sequence_design.py            # ProteinMPNN subprocess wrapper
│   ├── aa_bias.py                    # Amino-acid composition bias for ProteinMPNN
│   ├── structure_verification.py     # ESMFold folding + alignment + clash filter
│   ├── scoring.py                    # Composite scoring + success criteria
│   ├── target_preparation.py         # Binding-site extraction (3-mode selection)
│   └── design_tracker.py             # Persistent design numbering across runs
├── analysis/           # Pure helpers: structural_alignment, sequence_analysis, binding_analysis, visualization
├── models/             # Thin loaders: RFdiffusion / ProteinMPNN / ESMFold (weights → data_root)
├── app/                # Streamlit dashboard + state-agnostic UI components
│   ├── streamlit_app.py              # Main dashboard entry point
│   ├── components/                   # molecular_viewer, metrics_panel, sequence_viewer, pipeline_flow
│   ├── data_access.py                # Presentation-layer data loading
│   └── assets/styles.css             # Dark theme tokens
├── tests/              # 88 tests (pytest); markers: @slow, @integration, @network
├── docs/               # Spec, PhD guide, knowledge_graph.md (living architecture map)
├── config.yaml         # Central configuration (all paths derived from data_root)
├── setup.sh            # One-command bootstrap (staged: --ml, --app, --all)
├── pyproject.toml      # Dependencies, linting (ruff/black), pytest config
└── requirements.txt    # Frozen lock file

---

Configuration

All configuration lives in config.yaml with machine-specific overrides in .env (12-factor pattern). Key sections:

Section	Purpose
data_root	Root for all data, weights, caches (keep off Git partition)
target	PDB ID, chain IDs, binding site residue range, reference toxin
references	Known NaV1.7-blocking venom peptides (ProTx-II, HwTx-IV, Ssm6a)
rfdiffusion	Backbone generation: design count, binder length, noise, workers, checkpoint
streaming	Streaming pipeline: target successes, max attempts, worker count
proteinmpnn	Sequence design: sampling temp, cysteine filters, AA bias, sequence count
esmfold	Verification: model ID, max seq length, success thresholds (TM, pLDDT, RMSD)
scoring	Composite score weights (TM 40%, pLDDT 30%, inv_RMSD 20%, contacts 10%)

Environment variables (VENOM_* prefix) override any YAML value.

---

Testing

source .venv/bin/activate

# Run full test suite (88 tests)
pytest

# Verbose with coverage
pytest -v --cov=venom --cov=pipeline --cov=analysis --cov=app

# Skip slow tests (ESMFold/RFdiffusion inference)
pytest -m "not slow"

# Run only integration tests
pytest -m integration

Test markers:

• @pytest.mark.slow — heavy model inference; excluded from CI.
• @pytest.mark.integration — cross-module tests.
• @pytest.mark.network — requires real network access; opt-in only.

---

ML Stack

All models run on CPU with no GPU drivers required:

Model	Version	Size	Purpose
RFdiffusion	1.1.0	~1.5 GB per instance	Backbone structure diffusion
ProteinMPNN	—	~0.3 GB	Inverse folding (sequence design)
ESMFold	v1 (facebook)	~8.4 GB	Structure prediction + validation
PyTorch	2.12.0+cpu	—	Runtime

Additional dependencies: dgl 1.1.3, hydra-core 1.3, SE3Transformer, e3nn, transformers, biotite, tmtools.

Note: DGLBACKEND=pytorch must be set in the environment (included in .env).

---

Key Design Decisions

• No GPU required — every model runs on CPU; optimized for a 32 GB laptop.
• Parallel backbone generation — num_workers concurrent RFdiffusion subprocesses via asyncio, each gets OMP_NUM_THREADS = total_cores / num_workers. 7 workers achieves ~5-8x speedup over serial.
• Amino-acid bias — ProteinMPNN logits are biased (+1.5 Cys, -1.0 Leu) to encourage disulfide-rich, venom-like sequences instead of hydrophobic-dominated helical sequences.
• 3-mode binding site selection — explicit residues (most deterministic), toxin contact extraction, or CIF entity auto-detect. Fails loudly if ambiguous.
• Post-alignment clash filter — rejects designs where the peptide overlaps with the target (min all-atom distance < 2.0 Å).
• No sequence deduplication — different backbones mapping to the same sequence can produce different binding poses. Backbone geometry determines binding, not sequence alone.
• Stateless design numbering — DesignTracker persists next_design_num across runs (atomic JSON writes) to prevent PDB file collisions.

---

Limitations (Scientific Honesty)

This pipeline produces computational hypotheses only. Predicted binding and stability metrics are not experimental validation:

• ESMFold accuracy on small disulfide peptides is limited — treat pLDDT/TM/RMSD as hypotheses, not measurements.
• No molecular dynamics — steric clashes are filtered post-hoc, but no energy minimization is performed.
• No explicit solvent — binding energetics are approximated via contact counting, not ΔΔG.
• Disulfide enforcement is filter-based — disulfide bonds are encouraged via AA bias, not covalently enforced.
• Real drug candidates require in-vitro binding assays and patch-clamp electrophysiology. Treat outputs as prioritized leads, not validated drugs.

---

License & Commercial Use

This project is dual-licensed to support both the open-source community and sustainable development.

1. Open Source / Non-Commercial Use: Licensed under the GNU AGPLv3. It is free to use, modify, and distribute for personal, academic, or open-source projects, provided that you strictly comply with the terms of the AGPLv3 (which includes a provision that any network service using this code must also open-source its own codebase).
2. Commercial License: If you intend to use this software for commercial purposes (e.g., proprietary drug discovery, corporate R&D, or paid SaaS) without being subject to the AGPLv3's copyleft requirements, a separate Commercial License is required.

Please reach out to me directly to discuss commercial licensing and arrange payment.