Boltz Protein Design

Target Exploration — pre-design scouting

Read this when the user opts into the target-exploration pass from boltz-protein-design. It selects different generations configs with respect to the target before committing compute to a full design run, then hands back a chosen configuration (crop + optional binding site) and a recommended num_proteins for the full run. If the user already knows their target, site, and crop, do not run this — go straight back to authoring the full payload.

These framing axes apply to every binder modality — peptide, miniprotein, nanobody, and antibody. The axes frame the target, so they are independent of what kind of binder you design.

Contents

• Mental model: a grid we sample, not a full grid

• Bundled scripts and dependency probe

• Indexing contract (read before cropping)

• Step 0 — what is the binder for?

• Step 1 — trim unresolved N/C termini (always)

• Step 2 — choose which axes to scout

• Step 3 — scout: 50 designs per config

• Step 4 — pick the winning config by max binding_confidence

• Step 5 — size and submit the full run

• Step 6 — post-run yield readout

Mental model

The exploration procedure is best thought of a set of axes that can be varied in the input configuration to the generation endpoint that modify the underlying models view of the target. Each axis changes which target residues the model sees and whether or not we condition on a specified binding site. This process should be conducted as an interactive discussion with the user, who may have their own domain knowledge or preferences about how to design binders against a target.

Don't start by immediately using the full Cartesian product of the axes, as this will cause a combinatorial blowup of screening runs. For categorial axes, the entire axis should be explored in one set of exploration runs, for example, every domain should be designed against unless the user actively modifies this. For multi-valued axes like crop radius, only select a couple of values (not all five) to avoid combinatorial blowup, unless the user actively requests it. Before any exploration, the irrelevant residues at the termini should be trimmed. Scouting runs ask for 50 designs, and the best configuration is ultimately selected for the full size design run.

The axes:

Why bother: unmodeled terminal residues add floppy overhang that hurts designs; binders frequently dock off-site and crop/epitope indices are easy to misread, so testing a different configurations cheaply reveals which one yields good binders before spending on a large run.

Bundled scripts and dependency probe

The geometry/analysis scripts live in scripts/ next to this skill and need Python 3.9 or newer with gemmi and numpy. Probe the active interpreter first; only install if it fails — many users already have a suitable env.

# Probe (run from the skill directory; adjust the path to scripts/ as needed)
python3 -c "import gemmi, numpy" && echo DEPS_OK

If that prints DEPS_OK, run the scripts with python3 directly. If it errors, explain that the next command downloads and installs the exact gemmi and numpy versions pinned in requirements.txt from PyPI, then obtain the user's explicit approval before the network install. After approval, install them into a throwaway venv and use that interpreter:

python3 -m venv /tmp/boltz-explore-venv
/tmp/boltz-explore-venv/bin/pip install -r scripts/requirements.txt
# then call /tmp/boltz-explore-venv/bin/python instead of python3 below

Indexing contract

Every script emits and consumes 0-based API residue indices — the same indices crop_residues, epitope_residues, and flexible_residues use in the payload. The mapping is API index = canonical label_seq_id − 1. The scripts read label_seq from the CIF (not author numbering) so crop lists drop straight into the payload with no offset arithmetic — do not reintroduce auth-number offsets. When in doubt, spot-check one or two mapped indices against the target sequence before submitting; viz confirmation is deferred to a later skill, so this sanity check is your guardrail.

Step 0 — what is the binder for?

The user has engaged exploration, so first briefly establish what they want the binder to do — block a specific interaction/function, serve as a research or diagnostic tool, or just be any tractable binder against the target. This is a quick discussion (they may have domain knowledge about the target or other priors), and it shapes the whole pass: which sites/domains are worth scouting, whether to specify a site, and how to weigh the winner later (a highly designable but off-purpose site may not be what they want). Carry that goal through to the winner discussion.

Step 1 — trim unresolved N/C termini (always)

Never include leading or trailing residues that are unresolved in the structure — drop any unmodeled residues at each end so the crop starts and ends at the first and last resolved residue. This applies to the baseline and to every crop variant below. (Internal unresolved residues — disordered loops — are handled separately in the disorder axis, not here.)

Determine the bounds by reading the CIF: the crop starts at the first resolved label_seq and ends at the last resolved label_seq. Express the kept range as 0-based API indices in crop_residues. For a large structure you may use scripts/terminus.py <target.cif> --chain A to print the first/last resolved API index, but reading the CIF directly is fine.

Step 2 — choose which axes to scout

Cover each axis that applies — don't pre-judge which configuration will win. The only places to hold back: sample ~2 crop radii rather than all five, and don't multiply axes together into the full cross-product. Otherwise explore each axis fully — e.g. every domain, and with/without the site. This is an interactive discussion with the user. Sensible defaults:

1. Baseline — full target, termini trimmed, design spec as given.

2. Disorder cutout — if the target has internal disordered/loopy regions, add a configuration that crops them away:

   Copy

   # predicted target (pLDDT in the B-factor column) — default mode:
   python3 scripts/detect_disorder.py <target.cif> --chain A --min-loop 10
   # experimental target (real B-factors): high B = mobile
   python3 scripts/detect_disorder.py <target.cif> --chain A --mode bfactor

   It flags internal low-confidence/high-mobility runs longer than --min-loop (default 10) and prints the kept crop_residues (0-based) with those runs removed; terminal runs are left to terminus trimming. This is the weakest axis — it is a confidence/mobility heuristic, not a true disorder detector — so treat the suggestion as a hint and confirm it looks reasonable.

3. Binding-site crop radius — if a binding site is known, crop to residues within a radius of the site (all-atom). Scout a couple of radii rather than all five:

   Copy

   python3 scripts/crop_radius.py <target.cif> --chain A \
     --site 42,43,44 --radii 15,25,35

   --site takes 0-based API indices. For each radius it prints the kept crop_residues. Run each radius twice as separate configs: once with the site in epitope_residues, once without — specifying the site is not always better, so let the scout decide.

4. Domain — if there is no known site and the target is multi-domain, scout every annotated domain in parallel, each isolated as its own target config (50 designs). Do not pre-pick the "known functional" domain or scout just a couple, and do not let a whole-ectodomain scan stand in for this — a big multi-domain crop buries each domain's signal, so domains must be compared head-to-head in isolation. Fetch domain boundaries online (CATH / Pfam / InterPro / UniProt by id). If none are found, skip this axis unless the user asks.

5. Scan — only if the target is > 300 residues and the binding site is unknown. See scan below.

Cover each applicable axis, but don't multiply axes into the full cross-product. Each config is 50 designs, but cost depends on the combined target+binder length and can differ per config as the crop changes size — estimate-cost each config, sum the totals, and apply the spending gate (main skill) before submitting the batch.

scan

For a large target (> 300 residues) with an unknown binding site, discover where binders naturally dock:

On a multi-domain target the scan is complementary to the per-domain sweep, not a replacement: it shows where binders dock across the whole ectodomain, but designability is still compared by scouting each domain in isolation (axis 4). Run both — don't let the scan stand in for the per-domain comparison.

1. Submit one 100-design run with no epitope_residues (termini trimmed). The scan uses 100 (not the 50 of a normal scout) because its job is to find where binders dock and cluster those footprints reliably — too few designs gives noisy clusters. A no-site full-target run is also the unbiased baseline, so let this run serve both roles rather than paying for a separate 50-design baseline.

2. After download, cluster the top designs' contact footprints into candidate sites:

   Copy

   python3 scripts/scan_sites.py <run-dir> --target-chain A --binder-chain B \
     --top 20 --cutoff 6 --jaccard 0.25

   It computes each top design's all-atom footprint on --target-chain (default A) using only the generated binder chains selected by repeatable --binder-chain flags, clusters footprints by single-linkage at Jaccard > 0.25, and prints a consensus site (0-based API indices) per cluster — the residues contacted by ≥2 designs in the cluster. Read the generated binder entity's chain_ids from a result record and pass each ID separately. If the structure has exactly one non-target chain, the script can infer it when the flag is omitted; it fails closed when multiple non-target chains are ambiguous so native target chains are never silently treated as binder.

3. For each discovered site, scout two configs in parallel: (a) site specified + target cropped to ~35 Å around it, and (b) the same crop without the site specified. Feed each consensus site back through crop_radius.py.

Step 3 — scout: 50 designs per config

Each chosen config is a normal protein:design submission with num_proteins: 50 and that config's crop_residues (and epitope_residues when the config specifies the site). Author each payload, estimate-cost, confirm the summed cost, then submit and download per the main skill's Command Pattern. Give each scout run a descriptive name, e.g. scout-<target>-<axis>-<variant> (scout-PD1-r25-site, scout-PD1-r25-nosite, scout-PD1-disorder, scout-PD1-baseline), so the configs live together and are easy to compare.

Exploration spends in separate phases — round-1 scouts, the scan, the post-scan scouts, the full run. Apply the main skill's spending gate per phase: an outlined plan or an earlier phase's approval is not authorization for the next.

Launch the scout configs in parallel — do not finish one before starting the next. Submit each (start), then immediately background its download-results (per the main skill's Command Pattern) so every config runs on Boltz at the same time, and do not block waiting on any of them.

The only ordering constraint is the scan: configs derived from scan_sites.py need the 100-design scan run's results first. So launch every independent config up front together — baseline, disorder cutout, radius crops, and the scan run itself — and once the scan downloads, launch its per-site configs in parallel too. Never run scouts one at a time.

Step 4 — pick the winning config

Once the scout runs finish, score each config and choose the configuration to scale up. The selection metric is the maximum binding_confidence across the 50 designs in that config — the best single design a configuration can produce is the signal that the configuration is promising.

python3 scripts/analyze_results.py <scout-run-dir>      # one per config

For each config it prints: max binding_confidence, the 10th-highest binding_confidence, and the fraction of designs with bc > 0.01 and > 0.05. Compare configs by max bc; report the others as supporting context. The winning config's crop (and site, if it had one) becomes the config for the full run.

binding_confidence is a soft signal, not a pass/fail score — there is no cutoff to gate on. Read it qualitatively and bring the judgement to the user. A near-zero max bc is a weak configuration: iterate with the user or pull in more domain knowledge the user has. A clearly strong score is a good candidate to scale. In between is a real judgement call requiring user input — often worth a shot, especially if it's the best configuration you found and the site fits what the user wants — so lay out the trade-off rather than deciding for them.

Compare configs relative to each other (the best configuration vs. the rest), not against any fixed mark. Whatever the numbers, scaling is a collaborative call: recommend a direction and let the user steer.

Max binding_confidence is purely related to binding: where the model most easily gets a binder to stick, may not be where the user wants one to stick. Which site matters depends on why they want a binder (to block a specific interaction/function, a research or diagnostic tool, or just any tractable binder against the target). When configs hit different sites and the most designable one isn't clearly the right one, treat the pick as a discussion: lay out which site each config hits and its yield, confirm what the binder needs to do, and let the user's goal drive the choice — they know their biology. Don't crown a site on max bc alone.

If every config lands weak, say so honestly — but don't unilaterally call the target off. Like the site choice, binder modality (peptide / miniprotein / nanobody / antibody) is a discussion the user drives, not a switch you make yourself: suggest one if you have a view, but the call is theirs. Lay out what you found and the choices — try a different site or modality, scale anyway, or stop — and let the user steer.

Step 5 — size and submit the full run

Carry the winning config's crop_residues/epitope_residues into a full-run payload, then size it per the main skill's Run sizing (tiers as counts; estimate-cost the chosen tier — don't extrapolate across tiers) and apply the spending gate before start. Then submit and download per the main skill.

Step 6 — post-run yield readout

After the full run downloads, give the standard yield readout with the same script:

python3 scripts/analyze_results.py <full-run-dir>

Report: max binding_confidence, 10th-highest binding_confidence, and the fraction of designs with bc > 0.01 and > 0.05. These are the numbers a designer expects after every run. Then rank and present top designs per the main skill's Outputs section. (Histograms and structure visualization are intentionally out of scope here — a later visualization skill will add them.)