af3-json-factory

name	af3-json-factory
description	Convert CSV tables into valid AlphaFold3 input JSONs. Use this skill when you need to batch-generate AF3 JSONs from tabular inputs and run in MSA-free mode (protein uses empty unpairedMsa/pairedMsa, RNA uses empty unpairedMsa).

AF3 JSON Factory

Generate one AlphaFold3 input JSON per table row. Run commands from repository root and prefer .venv/bin/python.

Use this skill in two modes:

1. Standard CSV mode: use type_k/seq_k columns directly.
2. Schema mode: use --schema when column names are custom or layouts are complex.

Reference: references/AlphaFold3_input.md (AF3 input spec).

Non-negotiable output rules

• Output JSON is alphafold3 dialect, and includes required top-level fields (dialect, version, modelSeeds, name, sequences).
• This skill runs in MSA-free mode:
  • protein: unpairedMsa: "", pairedMsa: "", templates: []
  • RNA: unpairedMsa: ""
  • DNA/ligand: no MSA fields
• Defaults: --version 3 and --seeds 1 (single seed unless explicitly overridden).
• Entity IDs must be unique per row and match AF3 style (A-Z, AA, ...).
• To represent homomer copies, set one entity id as a list (for example ["A","B","C"]) instead of duplicating the same sequence entity.

Fast path (standard CSV)

Use when your table has type_1/seq_1, type_2/seq_2, ...

Supported type_k:

• protein, rna, dna, ligand_ccd, ligand_smiles

Recommended optional columns:

• job_id (or pass --id-col)
• id_k (explicit AF3 entity id like A, B, L, or JSON list like ["A","B","C"] for homomer copies), otherwise ids are auto-assigned.
• type_k/seq_k indices must be contiguous (1,2,3,...) with no gaps.
• Sequence values are normalized to uppercase and validated:
  • protein: uppercase letters only
  • rna: A/C/G/U/N (T is rejected)
  • dna: A/C/G/T/N

Run:

.venv/bin/python skills/af3-json-factory/scripts/csv_to_af3_json.py --help

.venv/bin/python skills/af3-json-factory/scripts/csv_to_af3_json.py \
  --table inputs.csv \
  --out-dir runs/$(date +%Y%m%d_%H%M%S)/inputs/json \
  --id-col job_id \
  --seeds 1

Flexible path (complex CSV)

Use when your table DOES NOT match type_k/seq_k, or you need custom column names.

1. Copy assets/schema.example.json.

   • A matching example table is available at assets/schema.example.csv.

2. Edit entities[]:

   • required: kind
   • choose one of id or id_col (or omit both for auto-ID)
   • id supports a single string ("A") or a list (["A","B","C"]) for homomer copies
   • set one value source: sequence_col / smiles_col / ccd_col
   • optional: set optional: true to skip this entity when the row value is empty

3. Run with --schema:

.venv/bin/python skills/af3-json-factory/scripts/csv_to_af3_json.py \
  --table complex.csv \
  --schema my_schema.json \
  --out-dir runs/$(date +%Y%m%d_%H%M%S)/inputs/json \
  --id-col job_id \
  --seeds 1,2

If the schema cannot express your input, then edit scripts/csv_to_af3_json.py, using references/AlphaFold3_input.md as the ground-truth spec.

Error-handling policy

• Default is fail-fast: first bad row stops the run.
• For messy data, use --on-error skip to keep going; bad rows are recorded in the manifest.
• Duplicate job_id values are rejected to prevent silent JSON overwrite.

Output contract

• Writes *.json under --out-dir
• Writes manifest.jsonl under --out-dir with status=ok|error and error details.
• Rejects duplicated job_id (including collisions with existing files in --out-dir).

Post-run QC checklist

• Confirm manifest.jsonl has no status=error rows.
• Spot-check 1-2 JSONs:
  • required top-level keys exist,
  • every sequence/ligand entity has unique ID,
  • RNA entities contain unpairedMsa only,
  • ligand CCD codes are uppercase and valid.

Emergency Handbook for Common Accidents

• Unknown entity type → standardize to the supported set or use schema mapping.
• Ligand CCD vs SMILES confusion → choose one per ligand (they’re mutually exclusive).
• Missing/duplicate IDs → let the script auto-assign IDs, or provide id_k/schema id.
• Rows with optional ligands/cofactors → use schema mode and set those entities as optional: true.
• You need modifications/templates/bonds/userCCD → extend the schema mapping first; only then touch code.