ProVADA

Generative steering to adapt proteins beyond native biological contexts

Preprint · Renin example

Xiaowei Zhang^1,†,, Wenhui Sophia Lu^2,†, Ben Viggiano^3,4,†, Kevin Reynolds⁵, Sophia Burick⁶, Elena Sotillo^5,7, Haoyu Dai⁸, Geonhu Lee⁸, Zixuan Liu¹, Nuoya Yang⁹, Luis S. Mille-Fragoso^1,16, Euan Ashley^3,10,11, Bingfei Yu^9,12,13, Crystal L. Mackall^5,7,10,14,15, Wing Hung Wong^2,3,16,, Xiaojing J. Gao^8,16,*

_Affiliations

_{¹ Department of Bioengineering, Stanford University, Stanford, USA.
² Department of Statistics, Stanford University, Stanford, USA.
³ Department of Biomedical Data Science, Stanford University, Stanford, USA.
⁴ Department of Computer Science, Stanford University, Stanford, USA.
⁵ Stanford Center for Cancer Cell Therapy, Stanford Cancer Institute, Stanford University, Stanford, USA.
⁶ Biophysics Program, Stanford University, Stanford, USA.
⁷ Weill West Coast Cancer Hub, Stanford, USA.
⁸ Department of Chemical Engineering, Stanford University, Stanford, USA.
⁹ Department of Immunology and Immune Therapeutics, Keck School of Medicine, University of Southern California, Los Angeles, USA.
¹⁰ Department of Medicine, Stanford University, Stanford, USA.
¹¹ Center for Undiagnosed Diseases, Stanford University, Stanford, USA.
¹² Norris Comprehensive Cancer Center, University of Southern California, Los Angeles, USA.
¹³ Alfred E. Mann Department of Biomedical Engineering, University of Southern California, Los Angeles, USA.
¹⁴ Department of Pediatrics, Stanford University, Stanford, USA.
¹⁵ Parker Institute for Cancer Immunotherapy, San Francisco, USA.
¹⁶ Stanford Bio-X, Stanford University, Stanford, USA.}

_{^† These authors contributed equally to this work.
^* Corresponding authors: xjgao@stanford.edu (X.J.G.), whwong@stanford.edu (W.H.W.), zhangxw@stanford.edu (X.Z.)}

 

This repository contains the official implementation of ProVADA (Protein Variant Adaptation), a test-time framework for adapting existing proteins to new biological contexts. Starting from a reference sequence, ProVADA steers a pretrained protein generator toward desired properties while preserving fold and native functionality.

Publications

• Pre-Print: Zhang, Lu, Viggiano et al. Generative steering to adapt proteins beyond native biological contexts. bioRxiv (2026). doi:10.1101/2025.07.11.664238

What is ProVADA?

At its core, ProVADA uses an iterative, population-based sampling algorithm called MADA (Mixture-Adaptation Directed Annealing) to explore the protein sequence space. At each iteration, promising sequences are selected through a downsampling and upsampling process, partially masked, and then re-completed to generate new proposals. These proposals are accepted or rejected based on a fitness score, guiding the population toward the desired properties.

See the sampler documentation for sampling policies, fitness options, and the metrics a run logs.

_{An illustrated example of the MADA algorithm utilizing ProteinMPNN as a generator.}

Set up

We have created a start up script that installs all dependencies and sets up the conda environment provada-env. Please use the following commands to create and activate the environment:

bash create_env.sh
conda activate provada-env

Example

We have provided example inputs for the experiments in the preprint under the inputs directory. Each has its own README describing the target, the files and what the configuration optimizes.

Renin localization: inputs/renin

Adapt a secreted protease to the reducing cytosol.

python run_provada.py --config inputs/renin/renin_localization_mpnn.yaml

FMC63 deimmunization: inputs/fmc63

Lower predicted MHC class I presentation of the anti-CD19 CAR binder.

python run_provada.py --config inputs/fmc63/fmc63_deimmune_mpnn.yaml

SunTag scFv deimmunization: inputs/scfvgcn4

The same objective for the second scFv, excluding new cysteines.

python run_provada.py --config inputs/scfvgcn4/scfvgcn4_deimmunize_mpnn.yaml

Both deimmunization examples predict epitopes with netMHCpan, which is license-gated and has to be installed once before they will run.

Repository Structure

provada-dev/
├── provada/                    # Main package source code
│   ├── components/            # Core components: Evaluators, Generators
│   │   ├── README.md          # Component system overview
│   │   ├── EVALUATORS.md      # Guide to creating custom scoring functions
│   │   ├── GENERATORS.md      # Guide to creating custom sequence generators
│   │   ├── evaluator.py       # Evaluator base class and built-in evaluators
│   │   └── generator.py       # Generator base class and built-in generators
│   ├── sampler/               # Sampling algorithms (MADA, Rejection, etc.)
│   ├── sequences/             # Sequence processing and pairwise metrics
│   ├── tools/                 # Model toolkits, each run in an isolated environment
│   ├── utils/                 # Utilities (logging, config, registry, etc.)
│   ├── base_variant.py        # Base variant class for starting protein
│   ├── config.py              # Typed configuration schema
│   ├── paths.py               # Path configuration
│   └── README.md              # Package-level documentation
├── inputs/                    # Input files and configurations
│   └── renin/                 # Example: renin localization experiment
├── tests/                     # Test suite
├── results/                   # Output directory for experimental results
├── logs/                      # Application logs
├── wandb/                     # Weights & Biases experiment tracking
├── run_provada.py             # Main entry point for running experiments
├── run_multiple.py            # Run multiple experiments in parallel (multi-GPU)
└── conftest.py                # Pytest configuration

Core Components

ProVADA's modular design is built around two extensible component types:

• Evaluators - Score protein sequences based on desired properties (localization, stability, etc.)
• Generators - Generate new sequences by filling masked positions (ESM3, ProteinMPNN, etc.)

See the Components README for detailed guides on creating custom evaluators and generators. In addition, our repository builds on the open-source infrastructure of the proto-tools project. See the proto-tools documentation for more information on how our model deployments work.

Tests

To run tests to ensure all functionality works, use the following command:

pytest -sv