FoldKit: A Python library for efficient storage and retrieval of co-folding predictions

FoldKit: A Python library for efficient storage and retrieval of co-folding predictions Jonathan A. Levine,1, 2, 3, ∗ Melissa Pathil,3, 4, 5 Samuel Nitz,1, 6 Olga Lyudovyk,3 and Benjamin D. Greenbaum3, 5, 7 1 Tri-Institutional Program in Computational Biology and Medicine,

Weill Cornell Medicine, New York, NY USA 2 Laboratory of Lymphocyte Dynamics, Rockefeller University, New York, NY USA

arXiv:2608.28788v1 [q-bio.QM] 28 Aug 2026

3 The Halvorsen Center for Computational Oncology,

Department of Epidemiology and Biostatistics, Memorial Sloan Kettering Cancer Center, New York, NY USA 4 Computational and Systems Biology Program, Sloan Kettering Institute, Memorial Sloan Kettering Cancer Center, New York, NY, USA 5 Physiology, Biophysics & Systems Biology, Weill Cornell Medicine, Weill Cornell Medical College, New York, NY USA 6 Laboratory of Host-Pathogen Biology, The Rockefeller University, New York, NY 10065, USA 7 The Olayan Center for Cancer Vaccines, Memorial Sloan Kettering Cancer Center, New York, NY USA (Dated: September 1, 2026) AlphaFold 3 (AF3) enables structure prediction of biomolecular complexes through co-folding multiple interacting molecules, making it increasingly useful for de novo protein design and for largescale studies of protein–protein, protein–peptide, and other biomolecular interactions. However, systematic co-folding experiments can produce large volumes of output data, particularly when multiple random seeds and samples are generated for each input complex. We introduce FoldKit, a Python package for efficient storage and analysis of large-scale AF3 co-folding results. FoldKit converts raw AF3 outputs into a compact, structured representation while preserving the metadata needed for downstream analysis. The FoldKit Python library provides convenient programmatic access to global, single chain, and interface confidence metrics such as pLDDT, pTM, ipTM, ipAE, and ipSAE, as well as an ensemble-level interface for accessing and aggregating these metrics for a single input across multiple seeds and samples. We benchmark FoldKit on three types of AF3 co-folding datasets: (i) a protein design campaign with 2 chains per input, (ii) a TCR-pMHC dataset with 4 chains per input, and (iii) a pooled-AF3 protein–protein interaction dataset with up to 22 chains per input. We find that FoldKit reduces storage requirements by approximately 5–15-fold compared to native AF3 outputs, depending on dataset composition, while maintaining direct programmatic access to individual predictions, ensembles, and confidence metrics. By reducing storage requirements and facilitating programmatic access to relevant outputs, FoldKit facilitates large-scale computational studies of biomolecular interactions. FoldKit is available from PyPI and can be installed using pip. INTRODUCTION

In recent years, co-folding has become an increasingly popular approach for a variety of tasks in computational biology. Multiple molecules are folded together using a structure prediction model, such as AlphaFold 3 (AF3) [1], and the resulting structures and confidence metrics can then be used to assess putative interactions between the input molecules, which are represented as separate chains within a single complex. Co-folding has become an important component of de novo binder design pipelines, where predictions of a designed protein sequence in com∗ Correspondence: levinej4@mskcc.org

plex with its target can effectively prioritize candidates prior to validation, increasing the experimental success rate [2–8]. These methods have been subsequently adapted to study the binding of larger, native protein complexes, such as antibodies [1, 9, 10] or T cell receptors (TCRs) [10–13], or for more general protein–protein interaction predictions [14–19]. More recently, a “pooled” version of AlphaFold3based co-folding was developed, where as many as 25 proteins are folded together at once, allowing numerous potential pairwise interactions to be screened simultaneously in one prediction [20]. These methods utilize a variety of outputs from the AlphaFold pipeline, including the predicted local distance difference test (pLDDT), the predicted

2

FoldKit Compressed Storage

Raw AlphaFold3 Output

CIF seed[s]_ sample[k]

NPZ

CSV

AF server

local installation

FoldKit Python API customizable metrics for: AF3Result + get_ptm(chain) + get_pae(chain) + get_ipae(chain1,chain2) + get_contact_probs(chain1,chain2) + get_plddt(chain1) + get_ipsae(chain1,chain2) ⋮

complex

chain

subchain AF3Ensemble + get_all_[metric](chain(s)) + get_ensemble_[metric](chain(s),ensemble_agg) ⋮

interchain

FIG. 1. The FoldKit Package FoldKit can process AlphaFold 3 results from either the AlphaFold 3 Server or from a local installation. The FoldKit command-line interface (CLI) exports AF3 results into a compressed format using NPZ files. The FoldKit Python API (application programming interface) can read AF3 results from either the raw output or the FoldKit compressed storage. The API enables users to programmatically access customizable metrics for the global complex, individual chains, subchains, or pairs of chains. The AF3Ensemble API enables convenient access to predictions across ensembles of multiple seeds and samples for the same input, where users can access metrics for the entire ensemble or choose how to aggregate them by passing in a custom function.

alignment error (PAE), and the predicted template- mation needed for downstream analyses, their storage modeling score (pTM). Usually the most informa- format leads to two major pain points for scientists: tive metrics for binding are computed by aggregating and/or transforming these confidence values over the 1. Extracting specific interchain or subchain metinterchain interfaces (in the typical notation they get rics from these files can require substantial prefixed with an “i”), like ipAE, ipTM, or ipSAE [21]. parsing and custom code, particularly when analyzing many predictions or heterogeneous Confidence values are output by the AlphaFold input complexes. 3 pipeline or the AlphaFold 3 Server in large JSON (JavaScript Object Notation) files alongside the pre2. The data is stored inefficiently, as numerical dicted structure file. JSON is a text-based format for values are represented as text, and the storage storing structured data, in which numerical values needed for directories of co-folding results for and other objects are represented as human-readable large datasets can become prohibitively extext. While these JSON files contain all of the inforpensive.

3 To solve these issues, we developed FoldKit. FOLDKIT

scaling exponents. Thus, larger AF3 complexes derive progressively greater storage savings from FoldKit.

FOLDKIT COMPRESSION ON PUBLIC DATA The FoldKit Python API (application programming interface) provides a convenient interface for To evaluate the utility of FoldKit on real-world loading AF3 co-folding results generated either through the AlphaFold 3 Server or local installa- data, we analyzed three existing AF3 co-folding tions, and for extracting and aggregating confidence datasets spanning a range of input sizes, ensemble metrics from the results (Fig. 1). The library al- sizes, and numbers of input chains: lows for customization of features, including user(i) the Overath et al. data [4, 22] with ≈ 3700 indefined aggregation functions, extraction of specific put complexes consisting of binder-target pairs, chain/interchain data, and extraction of data for pareach run with 1 AF3 seed and 3 AF3 samples tial chain subsequences. There is a programmatic (𝑁 𝐸𝑛𝑠𝑒𝑚𝑏𝑙𝑒 = 3), interface for extracting features from an ensemble of predictions for a single sequence input using multiple random seeds and samples, which has been shown to (ii) the Drost et al. data sampled from [23] (cofolded as part of Lyudovyk et al. [11]), comhelp with downstream classification tasks [11]. prising ≈ 5500 TCR-pMHC complexes with The FoldKit CLI (command-line interface) en4 chains each (TCR𝛼, TCR𝛽, MHC, peptide), ables the export of raw AF3 JSON files into a comeach run with 4 AF3 seeds and 5 AF3 samples pressed, structured representation using .npz files, (𝑁 𝐸𝑛𝑠𝑒𝑚𝑏𝑙𝑒 = 20), and provides built-in integration between the exported data and the Python API layer for accessing (iii) the Todor et al. data sampled from [20, 24], ensembles and individual results. containing ≈ 2100 pooled complexes with the number of proteins (i.e. chains) per complex normally distributed over 4–22 (𝜇 = 12.8, 𝜎 = FOLDKIT COMPRESSION ON SYNTHETIC DATA 2.6), run on the AlphaFold 3 Server with 1 seed and 5 samples (𝑁 𝐸𝑛𝑠𝑒𝑚𝑏𝑙𝑒 = 5). To evaluate the compression efficiency of FoldAcross all three datasets, exporting AF3 results Kit, we ran AlphaFold 3 with 1 seed and 1 sample on a synthetically generated dataset in which we var- with FoldKit substantially reduced storage requireied both the number of chains and the number of ments (Fig. 3A). For each dataset, both raw AF3 residues per chain (Fig. 2). We compared the storage and FoldKit storage requirements increased approxirequirements of the raw AF3 output directories with mately linearly with the number of input complexes, those of the corresponding FoldKit exports. FoldKit as expected when storing an increasing number of reduced the storage requirements of individual AF3 independent results. However, the FoldKit outputs outputs by approximately 5- to 20-fold (Fig. 2A). The exhibited substantially shallower scaling, resulting in size of raw AF3 outputs scaled with the total num- progressively larger storage savings as the number ber of residues as a power law with an exponent of of complexes increased (Fig. 3A). The magnitude of 1.859, consistent with the dominant contribution of these savings also depended on the size and complexthe 𝑂 (𝑁 2 ) residue-pair confidence matrices to stor- ity of the individual complexes, consistent with the age requirements (Fig. 2B, left). In contrast, FoldKit scaling behavior observed in the synthetic dataset. We next examined how the number of input chains outputs exhibited substantially weaker scaling, with a power-law exponent of 1.245, reflecting the use of ef- influenced FoldKit’s compression using the Todor et ficient matrix storage and removal of redundant data al. dataset. Increasing the number of chains in(Fig. 2B, right). Consequently, the FoldKit compres- troduces additional pairwise confidence information sion factor (raw AF3 size / FoldKit size) increased because AF3 generates pairwise predictions between with complex size, as expected from the difference in each pair of input chains. The number of chain pairs

4

A

B

FIG. 2. FoldKit substantially reduces storage requirements on a synthetic co-folding dataset A: Size (Mb) of output directories for a single AF3 prediction (1 seed, 1 sample, 𝑁Ensemble = 1) as a function of the number of chains and number of residues-per-chain for raw AF3 (left) and after FoldKit export (center). Right: The compression factor is defined as the ratio of raw AF3 size to FoldKit exported size. B: Left: Storage size (Mb) scaling-laws for raw AF3 (blue) and FoldKit (green). Raw AF3 is fit as a power-law with exponent 1.859 and FoldKit as a power-law with exponent 1.245. Right: Compression factor scaling with number of residues is fit as a power-law with the ratio of exponents from the individual power laws (1.859 − 1.245 = 0.614). Total residues is calculated as 𝑁chains ∗ 𝑁res.per chain .

increases as 𝑁chains , making pairwise confidence in2 formation an increasingly important component of the raw output as the number of chains grows. Consistent with this expectation, the compression factor increased approximately linearly with the number of 𝑁chains
chain pairs, (Fig. 3B). This provides further 2 evidence that the efficient representation of pairwise confidence information is a major source of FoldKit’s storage savings, though the exact performance depends on the number of residues in each chain, which is highly variable in this dataset. Thus, FoldKit provides particularly substantial storage benefits for large multi-chain AF3 jobs, such as those gener-

ated by pooled-AF3 approaches.

DISCUSSION

FoldKit addresses a practical bottleneck in largescale AF3 co-folding studies. As co-folding is increasingly applied to protein design, TCR-pMHC or antibody specificity prediction, and large pooled interaction screens, the raw JSON outputs from AF3 quickly become unwieldy, both in terms of storage footprint and the effort required to extract relevant confidence metrics. By converting these outputs into a compact, structured representation, FoldKit

5

A

B

Overath et al.

Drost et al.

Todor et al.

Todor et al.

FIG. 3. FoldKit substantially reduces storage requirements on real AF3 co-folding data A: Cumulative storage size (Gb) as a function of the number of input complexes for raw AF3 output (dashed) versus FoldKit output (solid), shown for the Overath et al. (𝑁chains = 2, 𝑁Ensemble = 3), Drost et al. (𝑁chains = 4, 𝑁Ensemble = 20), and Todor et al. (𝑁chains = 4–22, 𝑁Ensemble = 5) datasets. In all three datasets, both raw AF3 and FoldKit storage scale linearly with the number of complexes, but with a substantially shallower slope for FoldKit.
B: Compression factor (ratio of raw AF3 to FoldKit output size) as a function of the number of chain pairs, 𝑁chains , for 2 the Todor et al. dataset. Points show the mean ± SEM compression factor across complexes with a given number of chain pairs; the dashed line shows a linear fit (𝑅 2 = 0.851).

reduces storage costs by roughly an order of mag- rewritten to use numpy’s broadcasting feature, speednitude while preserving direct programmatic access ing up calculation for AlphaFold outputs with many to per-residue and per-interface confidence metrics, chains. individual predictions, and ensembles across seeds There are several limitations and directions for and samples. future work. First, FoldKit currently supports AF3 The benefits of FoldKit scale with the complex- outputs (both local and server-based runs); extendity of the input, since the number of pairwise confi- ing support to other co-folding tools would broaden dence matrices grows quadratically with the number its utility as the co-folding ecosystem diversifies. of chains. This makes FoldKit particularly useful Second, our benchmarks were conducted on three for emerging pooled co-folding approaches, where datasets spanning binder design, TCR-pMHC, and dozens of chains may be folded together in a sin- pooled interaction prediction; testing on additional gle job and the corresponding pairwise interface dataset types, including complexes with non-protein data would otherwise dominate storage requirements. chains (e.g., nucleic acids [25] or ligands [26]), Similarly, the version of ipSAE included in FoldKit is would help characterize how well FoldKit’s compres-

6 sion generalizes beyond protein-only inputs. Finally, while FoldKit focuses on efficient storage and retrieval, natural extensions include tighter integration with downstream modeling and visualization tools, allowing FoldKit exports to be used directly as inputs to classifiers or structural analysis pipelines without additional conversion steps. Overall, FoldKit provides a lightweight, generalpurpose solution to a storage and accessibility problem that will only grow as co-folding is applied more broadly across structural biology.

CODE AVAILABILITY

The code for FoldKit can be found at https:// github.com/jonlevi/foldkit. FoldKit can be installed using pip, as described in the git repo. Full documentation for FoldKit can be found at https: //jonlevi.github.io/foldkit/.

ACKNOWLEDGMENTS

This work utilized resources from the HighPerformance Computing (HPC) Group at Memorial Sloan Kettering Cancer Center. This work was in part supported by the Robert J. Kleberg, Jr. and Helen C. Kleberg Foundation. JAL is supported by NIAID Ruth L. Kirschstein National Research Service Award for Predoctoral Fellows 1F31AI200147-01.

REFERENCES [1] Abramson, J. et al. Accurate structure prediction of biomolecular interactions with AlphaFold 3. Nature 630, 493–500 (2024). [2] Bennett, N. R. et al. Improving de novo protein binder design with deep learning. Nat. Commun. 14, 2625 (2023). [3] Watson, J. L. et al. De novo design of protein structure and function with RFdiffusion. Nature 620, 1089–1100 (2023). [4] Overath, M. D. et al. Predicting experimental success in de novo binder design: a meta-analysis of 3,766 experimentally characterised binders. BioRxiv 2025–2008 (2025). [5] Cotet, T.-S. et al. Crowdsourced protein design: Lessons from the adaptyv EGFR binder competition. bioRxiv (2025).

[6] Pacesa, M. et al. One-shot design of functional protein binders with BindCraft. Nature 646, 483– 492 (2025). [7] Chow, A. et al. Sequence and structural determinants of efficacious de novo chimeric antigen receptors. BioRxiv (2025). [8] LiteFold Research. Litemol-1: A multi molecule foundation diffusion language model for agents. https://litefold.ai/research/litemol1 (2026). Correspondence: anindya@litefold.ai, cory@litefold.ai. [9] Yin, R. & Pierce, B. G. Evaluation of alphafold antibody–antigen modeling with implications for improving predictive accuracy. Protein Science 33, e4865 (2024). URL https://onlinelibrary. wiley.com/doi/abs/10.1002/pro.4865. https://onlinelibrary.wiley.com/doi/pdf/10.1002/pro.4865. [10] Yin, R. et al. Benchmarking alphafold and related deep learning approaches for modeling antibody and tcr antigen recognition. bioRxiv 2026–07 (2026). [11] Lyudovyk, O. et al. Ensembles of in silico structures enable t cell peptide-mhc binding prediction. bioRxiv 2026–07 (2026). [12] Woods, L. J. et al. General prediction of t cell receptor antigen specificity from sequence using alphafold 3. Biorxiv: the Preprint Server for Biology (2026). [13] Richardson, E. et al. IMMREP25: Unseen peptides. bioRxiv 2026–2003 (2026). [14] Humphreys, I. R. et al. Computed structures of core eukaryotic protein complexes. Science 374, eabm4805 (2021). [15] Bryant, P., Pozzati, G. & Elofsson, A. Improved prediction of protein-protein interactions using alphafold2. Nature communications 13, 1265 (2022). [16] Burke, D. F. et al. Towards a structurally resolved human protein interaction network. Nature structural & molecular biology 30, 216–225 (2023). [17] Guzmán-Vega, F. J. & Arold, S. T. Alphacrv: a pipeline for identifying accurate binder topologies in mass-modeling with alphafold. Bioinformatics Advances 4, vbae131 (2024). [18] Genz, L. R., Nair, S., Nagar, N. & Topf, M. Assessing scoring metrics for alphafold2 and alphafold3 protein complex predictions. Protein Science 34, e70327 (2025). [19] Pei, J., Zhang, J. & Cong, Q. Structural insights into predicted protein–protein interactions and protein complexes in the human proteome. Scientific Reports (2026). [20] Todor, H. et al. Predicting the protein interaction landscape of a free-living bacterium with pooledalphafold3. Molecular Systems Biology 22, 497–518 (2026). [21] Dunbrack Jr, R. L. Rēs ipsae loquunt: What’s wrong with alphafold’s iptm score and how to fix it. Biorxiv

7 (2025). [22] Overath, M. D., Andreas, R. & Jenkins, T. P. Dataset for: Predicting experimental success in de novo binder design: A meta-analysis of 3,766 experimentally characterised binders (2025). URL https: //doi.org/10.5281/zenodo.15722219. [23] Drost, F. et al. Predicting t cell receptor functionality against mutant epitopes. Cell Genomics 4 (2024). [24] Todor, H., Kim, L., Burkhart, H. & Gross, C. M. genitalium alphafold3 files (2025). URL https:

//doi.org/10.5281/zenodo.15499631. [25] Meng, H. et al. Precise dna base editing using alphafold3-based contact modelling. Nature 1–11 (2026). [26] Škrinjar, P. et al. Evaluating generalization in protein–ligand cofolding methods. Nature Structural & Molecular Biology 1–13 (2026).

Related documents

• SuryaBench: Benchmark Dataset for Advancing Machine Learning in Heliophysics and Space Weather Prediction.#165748
• Protein Structure Prediction: From Evolutionary Constraints to Generative Modeling#620510
• Protein Structure Prediction: From Evolutionary Constraints to Generative Modeling#618831
• Benchmarking Deep Learning Predictions of Mutation-Induced Fold Switching#623286
• AutoSDT: Scaling Data-Driven Discovery Tasks Toward Open Co-Scientists#1118396