af3-structure-json

name	af3-structure-json
description	Convert a single PDB/mmCIF structure into a validated AlphaFold3 JSON (alphafold3 dialect) by extracting polymer sequences, PTM/base modifications, ligands or ions (CCD codes), and optional bondedAtomPairs. Use when AF3 inputs must be rebuilt from solved structures while preserving chemistry.

PDB/mmCIF Structure -> AlphaFold3 JSON

Generate one AlphaFold3 (AF3) input JSON per structure file.

Use this skill when solved structures already exist in PDB/mmCIF and AF3 input must preserve:

• polymer sequences rebuilt from coordinates,
• non-canonical residues/bases as modifications,
• ligands/ions as AF3 ligand entities,
• optional covalent links as bondedAtomPairs.

Reference spec: references/AlphaFold3_input.md.

Quick run

1. Prepare input:

• Prefer mmCIF if covalent links matter (struct_conn is richer than PDB CONECT).
• Keep one biological assembly/model per file for predictable entity extraction.

2. Convert:

.venv/bin/python skills/af3-structure-json/scripts/structure_to_af3_json.py --help

.venv/bin/python skills/af3-structure-json/scripts/structure_to_af3_json.py \
  -i complex.cif \
  -o runs/$(date +%Y%m%d_%H%M%S)/inputs/af3.json \
  --seeds 1 \
  --fail_on_unresolved

3. Validate output before AF3 run:

• confirm sequences is non-empty and IDs are unique;
• confirm expected PTMs/ligands/covalent links are present;
• confirm no unexpected canonical-letter fallback occurred.

Output guarantees

• JSON uses dialect: "alphafold3" with required top-level keys.
• modelSeeds is required and non-empty.
• sequences is validated as non-empty before write.
• Entity IDs are validated as unique AF3-style IDs (A, B, ..., AA, ...).
• Homomer merge is on by default (--no_merge_homomers to disable).
• Default top-level values: version=3, modelSeeds=[1] unless overridden.
• Default MSA behavior is MSA-free:
  • protein: unpairedMsa: "", pairedMsa: "", templates: []
  • RNA: unpairedMsa: ""
  • DNA: no MSA fields

Canonical-letter resolution policy

AF3 polymer sequences must be canonical 1-letter codes. Resolution order:

1. Query assets/ccd_lookup.json (one_letter_code).
2. If unresolved, follow mon_nstd_parent_comp_id.
3. If still unresolved:
   • --fail_on_unresolved (recommended): stop and report the residue.
   • default: use X (protein) / N (NA) and emit a warning.
   • --allow_unknown: same as default (kept for compatibility).

Original CCD names are still preserved in modifications.

Extraction rules

• Polymer detection uses backbone heuristics:
  • protein-like: N, CA, C
  • nucleotide-like: C1'/C1* + one of P, N1, N9
• HETATM false positives are reduced with neighbor checks.
• Mixed protein/nucleotide chains are auto-fixed only for tiny hetero minority fragments (<=2 residues); otherwise fail.
• Non-canonical polymer residues become AF3 modifications.
• NA type inference: D* -> DNA, U -> RNA, else --default_na.
• Non-polymer residues become ligands via ccdCodes; waters are removed (HOH/WAT/H2O/DOD).
• Bond export depends on Biotite bond tables; missing tables trigger warnings.

Common options

• --fail_on_unresolved: fail on unresolved polymer monomers (recommended for scientific runs).
• --allow_unknown: use X/N fallback for unresolved monomers.
• --emit_bonds: export bondedAtomPairs.
• --group_ligands_by_bonds: merge multi-residue ligands by connectivity.
• --default_na rna: treat ambiguous NA chains as RNA.
• --strict_mixed_chains: disable mixed-chain auto-fix.
• --no_merge_homomers: keep one AF3 entity per detected chain/ligand.
• --exclude_ligand MG,NA,...: exclude selected CCDs from ligands.

Troubleshooting

• MSE/SEP/TPO/PSU missing in modifications: input likely lacks backbone atoms for those residues.
• DNA/RNA classification looks wrong: set --default_na, or normalize residue names upstream (DA/DC/... vs A/C/G/U).
• Mixed polymer types found in chain: split/fix residue naming upstream; or allow auto-fix by removing --strict_mixed_chains.
• Ligand fragmented into many entries: use --group_ligands_by_bonds and provide bond records.
• Missing covalent links: prefer mmCIF with struct_conn; many PDB files under-specify connectivity.
• Carbohydrates treated as ligands: extend polymer classifier only if glycan-polymer behavior is required.

Extension order

1. Improve monomer normalization/CCD mapping first.
2. Add userCCD, templates, or fixed bondedAtomPairs only after mapping is stable.
3. Add batch wrapper/manifest only after single-structure conversion is validated.