README.md

metadata

title: FlowProt
sdk: docker
app_port: 7860
license: mit

FlowProt Hugging Face Space (Docker MVP)

Live Space: alibtsd/FlowProt

This repository is wired for a remote-first Hugging Face Space deployment for FlowProt. The Space exposes the following inference modes:

• unconditional generation (enabled)
• classifier-guided generation (enabled when a classifier checkpoint is configured)
• conditional generation (feature-flagged via app.enable_conditional, disabled by default)

Workflow

The UI is organised into four tabs that follow the design lifecycle:

1. Generate - choose a mode, length, number of samples, seed, and sampling timesteps, then run inference. Classifier and conditional controls appear only for the relevant mode.
2. View - inspect generated backbones in interactive Mol* 3D, step through the generation trajectory, and overlay aligned backbone vs ESMFold comparisons.
3. Analyze - run ProteinMPNN + ESMFold self-consistency, browse metrics and leaderboards, and export filtered results.
4. Advanced - reload recent runs, manage the saved demo example, and view diagnostics/health.

A status badge at the top reports whether the model is loaded, whether self-consistency tooling is available, and the active device. A "Load demo example" button gives first-time visitors a one-click result.

Architecture

• app.py: Gradio UI only (request handling + user-visible errors + health display)
• inference.py: preprocessing/prediction/postprocessing orchestration
• model_loader.py: env-driven artifact resolution + model loading with defensive logging
• config.yaml: runtime defaults for UI limits and sampling parameters

Viewer Experience

• Mol* is the primary viewer for generated structures.
• The sample selector (View tab) shows the first selected sample in 3D; all selected samples feed self-consistency. A live label clarifies the current selection.
• Trajectory playback: step through, or play back, the backbone (bb_traj) or denoised (x0_traj) trajectory of the selected sample with a built-in frame slider.
• The viewer supports an aligned compare flow: pick a generated backbone and a folded sample from self-consistency, then load an aligned overlay in the same Mol* panel. Clicking a row in the Analyze metrics table loads the overlay automatically.
• Viewer rendering is iframe-isolated to avoid Gradio layout conflicts.

Inference Controls

• Optional per-run seed override is available in the UI for reproducible sampling (inference.seed remains the fallback default).
• The number of sampling timesteps is adjustable per run (more steps trade speed for quality).
• Generated sample.pdb files are always returned in the main output panel.
• Optional trajectory downloads can be enabled from the UI to expose traj and x0_traj artifacts.
• A run can be bundled into a single downloadable .zip from the Generate tab.

Conditional Generation (feature-flagged)

When app.enable_conditional: true, the Generate tab exposes a conditional workflow:

• Upload a reference PDB (chain A) to define fixed backbone positions.
• Specify fixed residues as ranges/indices (for example 10-40,55,60-62); leaving it empty fixes all residues.
• Optionally apply classifier guidance during conditional sampling.

Protein length is taken from the uploaded reference structure. Enable this flag only after validating end-to-end with a real checkpoint and reference structure.

Run History

Each successful run is recorded in space_outputs/run_history.json (mode, seed, sample count, timesteps, sample paths). The Advanced tab lets you reload a recent run's samples and any saved self-consistency results without re-running inference.

Self-Consistency Metrics

The UI includes a self-consistency action that runs:

1. ProteinMPNN sequence design on a generated sample PDB
2. optional ESMFold structure prediction for designed sequences
3. metric computation against the generated reference structure:
   • scTM
   • scRMSD

The self-consistency panel also includes:

• fixed plot axis ranges (not metric filtering):
  • scTM: [0, 1]
  • scRMSD: [0, 10]
  • ESMFold mean pLDDT: [0, 1]
• ranked leaderboards:
  • top-N by highest scTM
  • top-N by lowest scRMSD
• sample labels in tables/plots use descriptive run/length/sample names while canonical source paths stay in backend metadata.
• per-sequence table defaults to showing all evaluated rows; optional view filters can narrow by:
  • sample label (multi-select)
  • sample label text query
  • minimum scTM
  • maximum scRMSD
  • minimum ESMFold mean pLDDT

When multiple samples are selected in the sample selector, self-consistency runs for all selected samples and reports a single aggregated metrics view across those samples. A progress bar reports per-sample and per-sequence folding progress. Status logs include selected/processed sample counts, requested sequences per sample, folding mode, artifact counts, and a concise failed-sample preview when partial failures happen.

The scatter plots show per-point hover tooltips (sample label and metric values). The current (filtered) metrics view can be exported to CSV from the Analyze tab.

Artifacts are written per run under the selected sample directory in a timestamped self_consistency/ folder.

Saved Example Case

You can preserve a generated sample as a reusable demo case:

• Click Save selected sample as example to copy the selected sample directory into:
  • examples/flowprot_space_example/sample/
• If no sample is selected, the app falls back to the most recent generated sample under space_outputs/.
• The app also writes:
  • examples/flowprot_space_example/manifest.json
• Click Load saved example to view that sample in Mol* without running inference.
• If the example contains self_consistency/*/sc_results.csv, the app auto-loads the latest self-consistency summary/table/plots and leaderboards.

Model Artifact Configuration

Configure exactly one artifact source using environment variables:

1. Local checkpoint path:
   • FLOWPROT_CKPT_PATH=/path/to/model.ckpt
2. Local checkpoint directory:
   • FLOWPROT_CKPT_DIR=/path/to/ckpt_dir
   • optional: FLOWPROT_CKPT_FILENAME=epoch.ckpt (default)
3. Hugging Face Hub snapshot:
   • FLOWPROT_HF_REPO_ID=<org-or-user>/<repo>
   • FLOWPROT_CKPT_FILENAME=<relative/path/in/repo>.ckpt
   • optional: FLOWPROT_HF_REVISION=<branch-or-commit>
   • optional for private repos: HF_TOKEN=<token>

Optional overrides:

• FLOWPROT_CKPT_CONFIG_PATH=/path/to/config.yaml
• FLOWPROT_CKPT_CONFIG_FILENAME=config.yaml (default)
• FLOWPROT_APP_CONFIG=/app/config.yaml
• FLOWPROT_DEVICE=auto|cpu|cuda|cuda:0
• FLOWPROT_LOG_LEVEL=INFO|DEBUG|WARNING|ERROR
• FLOWPROT_PMPNN_DIR=/app/model/ProteinMPNN
• FLOWPROT_PMPNN_WEIGHTS_DIR=/app/model/ProteinMPNN/vanilla_model_weights
• FLOWPROT_PMPNN_MODEL_NAME=v_48_020
• FLOWPROT_SC_DEVICE=auto|cpu|cuda|cuda:0
• FLOWPROT_SC_SEED=123
• FLOWPROT_ESMFOLD_MODEL_ID=facebook/esmfold_v1
• FLOWPROT_VIEW_EXAMPLE_ON_STARTUP=true|false (default false)

Local Run (Import/UI only)

pip install -r requirements.txt
python app.py

If no checkpoint is configured, the UI still starts and shows model-load failures in the status panel.

For local checkpoint testing:

export FLOWPROT_CKPT_DIR=model/ckpt
export FLOWPROT_CKPT_FILENAME=epoch29.ckpt
python app.py

PowerShell equivalent:

$env:FLOWPROT_CKPT_DIR='model/ckpt'
$env:FLOWPROT_CKPT_FILENAME='epoch29.ckpt'
python app.py

Smoke Checks

Use smoke_checks.py to run explicit validation tiers:

python smoke_checks.py --tier import
python smoke_checks.py --tier handlers
python smoke_checks.py --tier model-load
python smoke_checks.py --tier inference --length 64 --num-samples 1

The handlers tier validates pure UI helper logic (seed parsing, fixed-residue parsing, self-consistency filtering, status badge) without requiring a model checkpoint.

Inference tier accepts optional reproducibility control:

python smoke_checks.py --tier inference --length 64 --num-samples 1 --seed 123

Validation Matrix (local vs remote)

• import: local-capable (no checkpoint required)
• handlers: local-capable (no checkpoint required)
• model-load: generally remote-target unless real artifacts are configured locally
• inference: remote-target for production confidence (GPU/artifact/runtime parity)

Validation Checklist (Local vs Hugging Face Space)

Use this checklist to separate what should pass locally vs what should be verified from Space logs/runtime:

1. Local import health
   • python smoke_checks.py --tier import
   • expected: app modules import cleanly in your local env with dependencies installed.
2. Local UI startup
   • python app.py
   • expected: Gradio launches; diagnostics panel is collapsed by default.
3. Model load and inference
   • local optional when real artifacts are available.
   • otherwise verify remotely in Space logs with configured artifacts/device.
4. Self-consistency flow
   • run from UI against one generated sample, confirm:
     • per-sequence table initially shows all rows
     • applying view filters narrows rows non-destructively
     • reset restores unfiltered view
5. Aligned compare viewer
   • after self-consistency produces folded structures, select backbone + folded row and click Load aligned compare view
   • expected: overlay loads in Mol* and compare status reports before/after RMSD.

Docker Space Startup

The Docker image starts with:

python app.py

Space health and model load status are visible in the Gradio UI.