structure-prediction-factory

name

structure-prediction-factory

description

Run reproducible structure-prediction workflows across AlphaFold3, Protenix, OpenFold3, and Boltz with a single Docker CLI and traceable run metadata. Use when backend-native inputs are already prepared (for example via af3-json-factory or af3-structure-json plus af3-json-converter), and you need multi-backend orchestration, dry-run command validation, or consistent run artifacts for scientific analysis.

Structure Prediction Factory

Overview

Run one command interface for four structure-prediction backends. Standardize run layout, logging, and reproducibility metadata.

This skill only executes prediction containers. It does not convert input formats. Run commands from repository root and prefer .venv/bin/python.

Quick Start

1. Set backend images and required paths.
   • export STRUCTPRED_IMAGE_ALPHAFOLD3=alphafold3:latest-migration
   • export STRUCTPRED_AF3_MODEL_DIR=/path/to/alphafold3_checkpoints
   • export STRUCTPRED_IMAGE_PROTENIX=protenix:runtime
   • export STRUCTPRED_PROTENIX_ROOT_DIR=/path/to/protenix_data
   • export STRUCTPRED_PROTENIX_CHECKPOINT_DIR=/path/to/protenix_checkpoints
   • export STRUCTPRED_IMAGE_OPENFOLD3=...
   • export STRUCTPRED_IMAGE_BOLTZ=...
   • Ensure required host paths above already exist as directories.
2. Prepare inputs before running this skill:
   • Build AF3 JSON with skills/af3-json-factory or skills/af3-structure-json.
   • Convert AF3 JSON to backend-native input with skills/af3-json-converter when backend is protenix, openfold3, or boltz.
3. Validate command assembly first.
   • .venv/bin/python skills/structure-prediction-factory/scripts/structpred.py predict --backend openfold3 --input <input.json> --dry-run
4. Run prediction.
   • .venv/bin/python skills/structure-prediction-factory/scripts/structpred.py predict --backend openfold3 --input <input.json> --out runs

Input Rules

Provide backend-native input only:

• alphafold3: AF3 JSON
• protenix: Protenix list JSON
• openfold3: OpenFold3 query JSON
• boltz: Boltz YAML

Fail early on malformed input or incompatible backend/input pairs.

Research Workflow

1. Pin image tags or digests before running large batches.
2. Run --dry-run and inspect meta.json command assembly.
3. Execute full runs only after dry-run command is correct.
4. Archive run directories as immutable experiment records.

Use meta.json fields for provenance:

• tool_version
• created_at_utc
• input_sha256
• source_input_kind
• prepared_input_kind
• docker_cmd

Output Contract

Each run creates:

• input/: backend-mounted prepared input (and original input copy only when non-redundant)
• output/: backend outputs
• logs/: container stdout/stderr logs
• meta.json: reproducibility metadata

Override Controls

• Override image per run with --image.
• Override backend command with --backend-cmd when container CLI versions differ. When --backend-cmd is set, the command is executed via bash -lc inside the container.
• For AlphaFold3, set STRUCTPRED_AF3_DB_DIR when using --backend-cmd with a data pipeline command that references /mnt/db.
• For Protenix, configure via env vars: STRUCTPRED_PROTENIX_ROOT_DIR, STRUCTPRED_PROTENIX_CHECKPOINT_DIR, and optionally STRUCTPRED_PROTENIX_CUTLASS_PATH.
• Use backend-specific flags for Protenix, OpenFold3, and Boltz through CLI options.
• --dry-run creates the full run directory (input, output, logs, meta.json) and prepares all inputs, but skips Docker execution. Inspect meta.json and the assembled docker command before committing to a full run. Remove the run directory manually if not needed.

Read backend details in references/backend-notes.md.

Auxiliary File Handling

When af3-json-converter materializes MSA, template, or userCCD files alongside the converted input, those files are referenced by absolute host paths inside the JSON/YAML. Since Docker only mounts run.input_dir at /mnt/input, these files must be collected and paths rewritten.

Each backend's prepare_inputs() automatically:

1. Parses the input file and discovers external file references (MSA paths, template CIF, CCD files).
2. Copies referenced files into run.input_dir/data/.
3. Rewrites paths in the input file to container mount points (/mnt/input/data/...).
4. Writes the processed input to the run directory.
5. For alphafold3, normalizes compatibility defaults before write:
   • version defaults to 3 (and downgrades >3 to 3)
   • modelSeeds defaults to [1] when missing/invalid
   • protein templates defaults to [] when absent/null

The original unmodified input is preserved as user_input.* only when it differs from the prepared input. If user_input.* and prepared input are equivalent, user_input.* is removed to avoid redundant files.

For Protenix specifically:

• relative pairedMsaPath/unpairedMsaPath are resolved against the input JSON directory;
• absolute or stale MSA paths that cannot be materialized are dropped (with warning), so runtime falls back to MSA re-search instead of carrying broken host-only paths into container runs.

Extend Backends

1. Implement runner protocol in scripts/struct_predictor/backends/base.py.
2. Implement prepare_inputs(...) to parse the backend-native input, relocate external file references into run.input_dir/data/ using utils.paths.relocate_file(), and write the rewritten input. Do not add cross-format conversion logic.
3. Add docker command assembly in docker_command(...). Pass default commands as direct args (no shell wrapping). Only use bash -lc when backend_cmd override is provided.
4. Register runner in scripts/struct_predictor/registry.py.
5. Validate with at least one --dry-run invocation.

Resources

• scripts/structpred.py: CLI entry script
• scripts/struct_predictor/: runners and runtime utilities
• references/backend-notes.md: backend command and env details
• assets/examples/af3_input.json: minimal AF3 example