PATROL

Pareto-aware Antibody Tuning Reinforcement Optimization Loop — a multi-objective Bayesian active-learning pipeline for antibody CDR design.

PATROL alternates between

1. an AbLang2 + LoRA sequence generator trained with GRPO under Dirichlet-sampled scalarized rewards,
2. a Gaussian-process surrogate over an antibody-LM embedding,
3. a greedy multi-objective acquisition (greedy hypervolume or augmented Tchebycheff) that selects which candidates to send to the affinity oracle,
4. a pluggable affinity oracle — either an in-process mock, or a file-watcher CSV protocol that lets any external compute (Rosetta FlexddG, FoldX, RDKit-based scoring, wet-lab queue, …) drive the loop.

The core pipeline is oracle-agnostic. A reference Rosetta FlexddG client is provided under examples/rosetta_flexddg/.

Installation

uv sync

To use the AntiFold generator or the antifold_nll developability metric, install AntiFold separately into the same environment (it pins biopython==1.83 so it can't be a managed dependency):

uv pip install antifold

PATROL is uv-managed. Python ≥ 3.11 is required. No conda or pixi.

Quickstart

Smoke-test the install with the in-process mock oracle:

uv run python run.py examples/1N8Z/config_mock.yaml

The pipeline writes per-cycle TSVs into results/1N8Z_mock/cycle_*.tsv.

Running with a real oracle

config_tchebycheff.yaml selects the default recipe (AbLang2 + GRPO generator, GPR(AbLang2) surrogate, Tchebycheff-greedy acquisition, CSV-file oracle):

# Terminal 1 — the optimizer
uv run python run.py examples/1N8Z/config_tchebycheff.yaml

# Terminal 2 — the affinity worker (Rosetta FlexddG)
export ROSETTA_BIN=/path/to/rosetta_scripts.linuxgccrelease
uv run python examples/rosetta_flexddg/run_flexddg_csv_client.py \
    --queue-dir results/1N8Z_tchebycheff/oracle_queue \
    --rosetta-bin "$ROSETTA_BIN" \
    --backrub-dir examples/1N8Z/data/backrub_1N8Z

Terminal 1 writes request_<cycle>.csv into the queue directory and blocks until terminal 2 produces a matching result_<cycle>.csv. See examples/rosetta_flexddg/README.md for the wire-format and a worked end-to-end recipe.

Configuration

PATROL is driven entirely by a YAML config. Override fields from the command line with --set:

uv run python run.py examples/1N8Z/config_tchebycheff.yaml \
    --set max_cycles=5 --set acquisition.batch_size=20

The full schema is documented in patrol/config.py (Pydantic models). Two example configs are shipped:

File	Generator	Surrogate	Acquisition	Oracle
examples/1N8Z/config_mock.yaml	naive	GPR(BLOSUM)	tchebycheff_greedy	mock
examples/1N8Z/config_tchebycheff.yaml	AbLang2 + GRPO	GPR(AbLang2)	tchebycheff_greedy	csv

Plugging in a new oracle

Implement patrol.oracle.base.AbstractOracle.evaluate() and select it via OracleConfig. For external compute that runs in a separate process or on a remote queue, use CSVFileOracle and have the worker watch the queue directory.

License

MIT. See LICENSE. Third-party attributions are in NOTICE.