af3-json-converter

name	af3-json-converter
description	Convert AlphaFold3 official inference JSON into Protenix, Boltz, or OpenFold3 inputs with schema validation. Use when an existing AF3 JSON must be reused by another folding stack, including batch conversion, target auto-detection from output filename, and best-effort mapping of AF3 `bondedAtomPairs`, MSA fields, templates, and ligand CCD/smiles data.

AF3 JSON Converter

Convert valid AF3 input JSON into another model's input format using the bundled converter package in scripts/. Run commands from repository root and prefer .venv/bin/python.

Quick Start

1. List supported targets:

.venv/bin/python skills/af3-json-converter/scripts/convert_af3_json.py --list-targets

2. Convert AF3 JSON to Protenix:

.venv/bin/python skills/af3-json-converter/scripts/convert_af3_json.py \
  --input /path/to/af3_input.json \
  --to protenix \
  --out /path/to/out_protenix.json

3. Convert AF3 JSON to Boltz (YAML):

.venv/bin/python skills/af3-json-converter/scripts/convert_af3_json.py \
  --input /path/to/af3_input.json \
  --to boltz \
  --out /path/to/out_boltz.yaml

4. Convert AF3 JSON to OpenFold3:

.venv/bin/python skills/af3-json-converter/scripts/convert_af3_json.py \
  --input /path/to/af3_input.json \
  --to openfold3 \
  --out /path/to/out_openfold3.json

Conversion Workflow

1. Read and perform basic AF3 JSON shape validation before conversion (jobs, sequences, IDs, required core fields).
2. Choose a target explicitly with --to; if omitted, rely on --out auto-detection.
3. Set --out-dir when inline MSA/template/userCCD content may need to be materialized to files.
4. Keep schema validation enabled by default; use --no-validate only for debugging.
5. Inspect warnings in stdout and resolve lossy-field drops before downstream runs.

Target Auto-Detection Rules

If --to is omitted, infer target from --out:

• *.yaml or *.yml -> boltz
• filename containing openfold or of3 -> openfold3
• *.json -> protenix

If no rule matches, require --to.

Important Flags

• --allow-multi-ccd: allow multi-CCD ligands where target behavior permits.
• --out-dir: write inline text blobs (MSA/templates/userCCD) to files and reference paths in outputs.
• --no-validate: skip target schema validation (default behavior is fail-fast on schema mismatch).

Output and Mapping Notes

Use references/targets.md for target-specific mapping and known lossy conversions.

Key caveats:

• OpenFold3 conversion drops AF3 bondedAtomPairs (warning emitted).
• OpenFold3 conversion ignores AF3 modelSeeds (warning emitted).
• AF3 protein templates cannot always map losslessly to OpenFold3 template fields.
• Boltz YAML output prefers PyYAML; without it, converter falls back to JSON text.

Bundled Resources

• scripts/convert_af3_json.py: stable CLI entrypoint for this skill.
• scripts/af3_json_converter/: converter package, schemas, and per-target logic.
• references/targets.md: concise target behavior and conversion limitations.