add dockerfile and folding studio cli

Dockerfile

@@ -0,0 +1,32 @@
+ARG UV_VERSION="0.6.14"
+
+FROM ghcr.io/astral-sh/uv:${UV_VERSION} AS uv-fetcher
+
+FROM python:3.11-slim AS runtime
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    wget build-essential git && \
+    rm -rf /var/lib/apt/lists/*
+
+COPY --from=uv-fetcher /uv /uvx /usr/local/bin/
+
+ENV VIRTUAL_ENV=/modules/.venv
+RUN uv venv "$VIRTUAL_ENV" && . "$VIRTUAL_ENV/bin/activate"
+ENV PATH="$VIRTUAL_ENV/bin:$PATH"
+
+# Set the working directory to the user's home directory
+WORKDIR /app
+
+COPY pyproject.toml uv.lock /app/
+
+RUN uv sync --frozen --active --directory /app --inexact
+
+COPY folding-studio /app/folding-studio
+RUN cd /app/folding-studio && uv pip install -e .
+
+COPY app.py /app/app.py
+
+EXPOSE 7860
+ENV GRADIO_SERVER_NAME="0.0.0.0"
+
+CMD ["python3", "app.py"]

README.md

@@ -3,8 +3,7 @@ title: Fs
 emoji: 🚀
 colorFrom: indigo
 colorTo: red
-sdk: gradio
-sdk_version: 5.30.0
+sdk: docker
 app_file: app.py
 pinned: false
 short_description: folding studio test

folding-studio/CONTRIBUTING.md

@@ -0,0 +1,8 @@
+# Contributing to the Documentation
+
+## Serve the Documentation Locally
+```bash
+poetry install --with docs
+poetry run mkdocs serve
+```
+This will start a local server at http://127.0.0.1:8000.

folding-studio/docs/app.yaml

@@ -0,0 +1,24 @@
+# This is the configuration file for the Google App Engine instance.
+# GAE is capable of hosting any sort of web app,
+# however, here we focus on the static website hosting capabilities.
+# https://cloud.google.com/appengine/docs/standard/hosting-a-static-website
+runtime: python39
+
+handlers:
+  # static files with a URL ending with a file extension
+  # (e.g. favicon.ico, manifest.json, jylade.png)
+  - url: /(.*\..+)$
+    static_files: site/\1
+    upload: site/(.*\..+)$
+  # index page
+  - url: /
+    static_files: site/index.html
+    upload: site/index.html
+  # anything that ends with a slash (e.g. /docs/)
+  - url: /(.*)/$
+    static_files: site/\1/index.html
+    upload: site/(.*)
+  # anything else (e.g. /docs)
+  - url: /(.*)
+    static_files: site/\1/index.html
+    upload: site/(.*)

folding-studio/docs/docs/css/main.css

@@ -0,0 +1,8 @@
+.md-sidebar__inner .md-nav__title {
+    display: none !important;
+}
+
+/* Hide the copy button for .no-copy blocks */
+.no-copy .md-clipboard {
+    display: none;
+}

folding-studio/docs/docs/explanation/advanced_algorithms.md

@@ -0,0 +1,100 @@
+## Gap trick
+
+Gap Trick allows folding multimer complexes using the AlphaFold2/OpenFold **monomer**
+models.
+
+It is only available when using custom templates. Additionally, the provided
+templates **MUST** exclusively include chains that precisely correspond to the
+query sequences, no more, no less, and in the same order.
+
+## Initial guess
+
+The initial guess algorithm allows to use a pre-defined structure in the first
+recycling stage of the AlphaFold2 forward pass. The original algorithm is
+described in [Bennett et al.](https://www.nature.com/articles/s41467-023-38328-5)
+and can be found in their [GitHub repo](https://github.com/nrbennet/dl_binder_design/blob/main/af2_initial_guess/).
+
+## MSA subsampling
+
+MSA subsampling allows to change the default number of MSA representation to
+give as input to the model.
+
+This feature is only supported for monomer.
+
+The impact of MSA subsampling has been studied by [D. Del Alamo et al.](https://elifesciences.org/articles/75751).
+
+!!! quote
+    "Whereas models of most proteins generated using the default AF2
+    pipeline are conformationally homogeneous and nearly identical to one
+    another, reducing the depth of the input multiple sequence alignments by
+    stochastic subsampling led to the generation of accurate models in multiple
+    conformations." - D. Del Alamo et al.
+
+## Template masking
+
+Template Masking enables the creation of template features by masking regions
+of the structures considered less important for resolving the multimer
+interface.
+
+This method is exclusively available in Gap Trick mode. Therefore
+the same constraints on the input template structures applies, i.e they
+**MUST** exclusively include chains that precisely correspond to the query
+sequences, no more, no less, and in the same order.
+
+Consider an input `FASTA` file containing 3 chains of a multimer complex, for
+example an antigen chain and two antibody chains:
+
+```
+>Antigen
+VRFPNITNLCPFHEVFNATTFASVYAWNRKRISNCVADYSVIYNFAPFFAFKCYGVSPTKLNDLCFTNVYADSFVIRGNEVSQIAPGQTGNIADYNYKLPDDFTGCVIAWNSNKLDSKPSGNYNYLYRLFRKSKLKPFERDISTEIYQAGNKPCNGVAGPNCYSPLQSYGFRPTYGVGHQPYRVVVLSFELLHAPATVCGPK
+>Antibody | Chain 1
+DIQMTQSPSSLSASVGDRVTITCRASQSISSYLNWYQQKPGKAPKLLIYAASSLQSGVPSRFSGSGSGTDFTLTISSLQPEDFATYYCQQSYSTPGVTFGPGTKVDIK
+>Antibody | Chain 2
+QVQLVESGGGVVQPGRSLRLSCAASGFTFSSYDMHWVRQAPGKGLEWVAVISYDGSSKFYAESVKGRFTISRDNSKNTLYLQMNSLRAEETAVYYCVKDGEQLVPLFDYWGQGTLVTVSS
+```
+
+The user aims to resolve the binding interface between the antigen and antibody
+chains, which is a common scenario for applying the template masking algorithm.
+In this case, a single template file is used, and the masking pattern
+alternately masks the binding partners and the binding interface. To activate
+the template masking algorithm, the user must provide a template mask file that
+defines the masking pattern:
+
+```json
+{
+    "templates_masks": [
+    {
+        "template_name": "7si2_chothia_CGF.cif",
+        "masks": [
+        "----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------",
+        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
+        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
+        ]
+    },
+    {
+        "template_name": "7si2_chothia_CGF.cif",
+        "masks": [
+        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
+        "------------------------------------------------------------------------------------------------------------",
+        "------------------------------------------------------------------------------------------------------------------------"
+        ]
+    },
+    {
+        "template_name": "7si2_chothia_CGF.cif",
+        "masks": [
+        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX--XXXXXX----------XX--XXXXXXXXXXXXXXXXXXXXX-XXXXXXXXXXXXXX---XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
+        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-----XXXXXXXXXXXX",
+        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX----XX--X-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-XX----XXXXXXXXXXXXXXX"
+        ]
+    }
+    ]
+}
+```
+
+The `masks` fields must adhere to the following constraints:
+
+- Contain as many mask line as chains in the input `FASTA` file,
+- Each mask line must have as many characters as the corresponding chain in the
+  input `FASTA` file,
+- Only contain `X` (residue is masked) or `-` (residue is not masked)
+  characters,

folding-studio/docs/docs/explanation/index.md

@@ -0,0 +1,4 @@
+# Explanation
+This **Explanation section** provides deeper insights into the models and advanced algorithms supported in our custom folding CLI. Unlike the **How-to guides**, which focus on practical steps, these explanations cover the underlying principles that influence model selection and algorithm performance.
+
+You will find an overview of [each model](./supported_models.md), its strengths, and its limitations, as well as details on [advanced features](./advanced_algorithms.md) like MSA subsampling and template masking. The goal is to help you understand how these components fit together so you can make the right choices for your predictions.

folding-studio/docs/docs/explanation/supported_models.md

@@ -0,0 +1,125 @@
+This documentation provides an overview of the supported protein folding models
+in Folding Studio.  Please refer to the official documentation page for more details on a model features, how it was trained and how it is claimed to perform with respect to similar models. Users are encouraged run their own benchmarking tests tailored to their use-cases.
+Folding Studio  models can be organized into two categories: AlphaFold2-like and AlphaFold3-like architectures.
+
+- AlphaFold2-like models: This group includes **AlphaFold2**, **OpenFold**, and **SoloSeq**.
+- AlphaFold3-like models: This group includes **Boltz-1**, **Chai-1**, and **Protenix**.
+
+AlphaFold3 is the new state-of-the-art method for protein-antibody interface prediction, improving upon AlphaFold2. Key advancements include:
+
+- The replacement of AlphaFold2's Structure module with a Diffusion module, enhancing predictions without additional constraints.
+- An expanded vocabulary to support RNA, DNA, and other molecules like ligands.
+- A smaller MSA module and the removal of the MSA from the Pairformer module, which replaces AlphaFold2's Evoformer module.
+- Internal changes in the Pairformer module, including information flow from pairs to single representations.
+
+These modifications improve complex predictions and integrate recent ML advancements.
+
+!!! Data
+    The key difference between AlphaFold2-like models and AlphaFold3-like models input data is that while AlphaFold 2 primarily requires only a protein sequence as input, AlphaFold3 can accept a wider range of molecular information, including not just protein sequences but also details about other molecules like DNA, RNA, and ligands, allowing it to predict the structures of protein complexes involving these molecules.
+
+Please note that the MSA search process (applicable to all models with MSA support) runs on servers hosted by InstaDeep. This ensures complete confidentiality of all user inputs.
+
+## AlphaFold2
+
+[![GitHub](https://img.shields.io/badge/GitHub-%23121011.svg?logo=github&logoColor=white)](https://github.com/google-deepmind/alphafold)
+[![Paper](https://img.shields.io/badge/Paper-018EF5?logo=readme&logoColor=fff)](https://www.nature.com/articles/s41586-021-03819-2)
+
+**Overview:** AlphaFold2 (AF2) is a deep learning model developed by DeepMind
+for high-accuracy protein structure prediction. It leverages evolutionary
+relationships and deep learning techniques to generate atomic-level protein
+structures.
+
+**Key Features:**
+
+- Uses multiple sequence alignments (MSAs) for improved accuracy.
+- Evoformer module for deep sequence and pairwise residue learning.
+- Structure module with iterative 3D refinement.
+- Suitable for high-precision structural biology and drug discovery.
+
+___
+
+## OpenFold
+
+[![GitHub](https://img.shields.io/badge/GitHub-%23121011.svg?logo=github&logoColor=white)](https://github.com/aqlaboratory/openfold)
+[![Paper](https://img.shields.io/badge/Paper-018EF5?logo=readme&logoColor=fff)](https://www.nature.com/articles/s41592-024-02272-z)
+[![Documentation](https://img.shields.io/badge/Read%20the%20Docs-8CA1AF?logo=readthedocs&logoColor=fff)](https://openfold.readthedocs.io/en/latest/index.html)
+
+**Overview:** OpenFold is an open-source reimplementation of AlphaFold2 in
+PyTorch, designed for efficiency and accessibility.
+
+**Key Features:**
+
+- Optimizations in the implementation which allow for faster inference time (at least for proteins of few hundreds of residues) and lesser RAM consumption.
+
+___
+
+## SoloSeq
+
+[![Documentation](https://img.shields.io/badge/Read%20the%20Docs-8CA1AF?logo=readthedocs&logoColor=fff)](https://openfold.readthedocs.io/en/latest/Single_Sequence_Inference.html)
+
+**Overview:** SoloSeq is a modified version of OpenFold which replaces MSA features by ESM-1b sequence embeddings.
+
+**Key Features:**
+
+- MSA-free Prediction: Uses ESM-1b model embeddings to predict structure without multiple sequence alignments (MSA).
+- Flexible Optimization: Offers flags for controlling relaxation, output saving, and MMCIF file generation.
+
+___
+
+## Chai-1
+
+[![GitHub](https://img.shields.io/badge/GitHub-%23121011.svg?logo=github&logoColor=white)](https://github.com/chaidiscovery/chai-lab)
+[![Paper](https://img.shields.io/badge/Paper-018EF5?logo=readme&logoColor=fff)](https://www.biorxiv.org/content/10.1101/2024.10.10.615955v1.full.pdf)
+
+**Overview:** Chai-1 is a multi-modal protein structure prediction model that
+supports proteins, RNA, DNA, and small molecules.
+
+**Key Features:**
+
+- Multi-modal capabilities for protein-protein and biomolecule interactions.
+- Transformer-based architecture with deep representation learning.
+- Best for users looking for an MSA-free alternative with high versatility.
+
+___
+
+## Boltz-1
+
+[![GitHub](https://img.shields.io/badge/GitHub-%23121011.svg?logo=github&logoColor=white)](https://github.com/jwohlwend/boltz?)
+[![Paper](https://img.shields.io/badge/Paper-018EF5?logo=readme&logoColor=fff)](https://www.biorxiv.org/content/10.1101/2024.11.19.624167v1.full)
+
+**Overview:** Boltz-1 is a protein folding model developed by MIT Jameel Clinic,
+optimized for computational efficiency.
+
+**Key Features:**
+
+- Hybrid attention mechanisms improve residue interaction modeling.
+- Optimized inference for fast predictions.
+- Advanced multi-chain folding for complex biomolecular structures.
+- Ideal for researchers needing high-speed, scalable structure prediction.
+
+**Supported data format**
+
+| Feature  | Fasta              | YAML    |
+| -------- |--------------------| ------- |
+| Polymers | :white_check_mark: | :white_check_mark:   |
+| Smiles   | :white_check_mark: | :white_check_mark:   |
+| CCD code | :white_check_mark: | :white_check_mark:   |
+| Custom MSA | :white_check_mark: | :white_check_mark:   |
+| Modified Residues | :x:                |  :white_check_mark: |
+| Covalent bonds | :x:                | :white_check_mark:   |
+| Pocket conditioning | :x:                | :white_check_mark:   |
+
+
+___
+
+## Protenix
+
+[![GitHub](https://img.shields.io/badge/GitHub-%23121011.svg?logo=github&logoColor=white)](https://github.com/bytedance/Protenix)
+[![Paper](https://img.shields.io/badge/Paper-018EF5?logo=readme&logoColor=fff)](https://www.biorxiv.org/content/10.1101/2025.01.08.631967v1.full-text)
+
+**Overview:** Protenix is an open-source alternative to AlphaFold3,
+developed for scalability and custom applications.
+
+**Key Features:**
+
+- Protenix only support MSA search with MMSeqs2 and does not support template features

folding-studio/docs/docs/how-to-guides/af2_openfold/advanced_algorithms/gap_trick_job.md

@@ -0,0 +1,21 @@
+## Goal
+The Gap Trick enables the folding of multimer complexes using monomer models from AlphaFold2/OpenFold **monomer** models.
+
+## Application
+
+It is only available when using custom templates (i.e. `"template_mode"` must be set to  `"custom"`). Additionally, the provided templates **MUST** exclusively include chains that precisely correspond to the query sequences, no more, no less, and in the same order.
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding predict af2 path/to/my/file.fasta --project-code "your-project-code"  --gap-trick --template_mode custom --custom_template /path/to/template_1.cif
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from pathlib import Path
+    from folding_studio.commands.predict import af2 as af2_predict
+
+    af2_predict(source=Path("path/to/my/file.fasta"), project_code="your-project-code", gap_trick=True, template_mode="custom", custom_template=[Path("/path/to/template_1.cif")], num_recycle=3, random_seed=0)
+    ```

folding-studio/docs/docs/how-to-guides/af2_openfold/advanced_algorithms/initial_guess_af2.md

@@ -0,0 +1,150 @@
+## Goal
+
+The initial guess algorithm allows to use a pre-defined structure in the first recycling stage of the AlphaFold2 forward pass. The original algorithm is described in [Bennett et al.](https://www.nature.com/articles/s41467-023-38328-5) and in the [GitHub repo](https://github.com/nrbennet/dl_binder_design/blob/main/af2_initial_guess/).
+
+!!! warning
+    Unlike the other features in the how-to guides, this algorithm is only available with the AlphaFold2 model.
+
+## Application
+
+The initial guess structure file **must be** in `.cif` format. This algorithm is only available when disabling MSA and templates (i.e. `"msa_mode"` and `"template_mode"` must both be set to  `"none"`). Additionally, the provided initial guess file **MUST** exclusively include chains that precisely correspond to the query sequences, no more, no less.
+
+=== ":octicons-command-palette-16: CLI single job"
+
+    ```bash
+    folding predict af2 3bve.fasta --project-code "your-project-code" --initial-guess-file 3bve_dimer.cif --msa-mode none --template-mode none
+    ```
+
+=== ":octicons-command-palette-16: CLI batch job"
+
+    ```bash
+    folding predict af2 batch_jobs.csv --project-code "your-project-code"
+    ```
+
+    === ":material-table: CSV example"
+
+    ```csv
+    complex_id,description,fasta_sequence,num_recycle,random_seed,msa_mode,template_mode,initial_guess_file
+    3bve-ig,chain A,PMLSKDIIKLLNEQVNKEMNSSNLYMSMSSWCYTHSLDGAGLFLFDHAAEEYEHAKKLIIFLNENNVPVQLTSISAPEHKFEGLTQIFQKAYEHEQHISESINNIVDHAIKSKDHATFNFLQWYVAEQHEEEVLFKDILDKIELIGNENHGLYLADQYVKGIAKSRK,3,145,none,none,initial_guess/3bve_dimer.cif
+    3bve-ig,chain B,PMLSKDIIKLLNEQVNKEMNSSNLYMSMSSWCYTHSLDGAGLFLFDHAAEEYEHAKKLIIFLNENNVPVQLTSISAPEHKFEGLTQIFQKAYEHEQHISESINNIVDHAIKSKDHATFNFLQWYVAEQHEEEVLFKDILDKIELIGNENHGLYLADQYVKGIAKSRK,3,145,none,none,initial_guess/3bve_dimer.cif
+    1hqk-ig,chain 1,MQIYEGKLTAEGLRFGIVASRFNHALVDRLVEGAIDCIVRHGGREEDITLVRVPGSWEIPVAAGELARKEDIDAVIAIGVLIRGATPHFDYIASEVSKGLANLSLELRKPITFGVITADTLEQAIERAGTKHGNKGWEAALSAIEMANLFKSLR,3,145,none,none,initial_guess/1hqk_pentamer.cif
+    1hqk-ig,chain 2,MQIYEGKLTAEGLRFGIVASRFNHALVDRLVEGAIDCIVRHGGREEDITLVRVPGSWEIPVAAGELARKEDIDAVIAIGVLIRGATPHFDYIASEVSKGLANLSLELRKPITFGVITADTLEQAIERAGTKHGNKGWEAALSAIEMANLFKSLR,3,145,none,none,initial_guess/1hqk_pentamer.cif
+    1hqk-ig,chain 3,MQIYEGKLTAEGLRFGIVASRFNHALVDRLVEGAIDCIVRHGGREEDITLVRVPGSWEIPVAAGELARKEDIDAVIAIGVLIRGATPHFDYIASEVSKGLANLSLELRKPITFGVITADTLEQAIERAGTKHGNKGWEAALSAIEMANLFKSLR,3,145,none,none,initial_guess/1hqk_pentamer.cif
+    1hqk-ig,chain 4,MQIYEGKLTAEGLRFGIVASRFNHALVDRLVEGAIDCIVRHGGREEDITLVRVPGSWEIPVAAGELARKEDIDAVIAIGVLIRGATPHFDYIASEVSKGLANLSLELRKPITFGVITADTLEQAIERAGTKHGNKGWEAALSAIEMANLFKSLR,3,145,none,none,initial_guess/1hqk_pentamer.cif
+    1hqk-ig,chain 5,MQIYEGKLTAEGLRFGIVASRFNHALVDRLVEGAIDCIVRHGGREEDITLVRVPGSWEIPVAAGELARKEDIDAVIAIGVLIRGATPHFDYIASEVSKGLANLSLELRKPITFGVITADTLEQAIERAGTKHGNKGWEAALSAIEMANLFKSLR,3,145,none,none,initial_guess/1hqk_pentamer.cif
+    ```
+
+
+=== ":material-language-python: script for single job"
+
+    To submit jobs with custom files programmatically, we use helper functions made available in the [`folding_studio` package](../../../tutorials/installation.md#cli-and-folding_studio-library) library.
+
+    ```python
+    import json
+    from pathlib import Path
+
+    from folding_studio import get_id_token
+    from folding_studio import single_job_prediction
+    from folding_studio_data_models import AF2Parameters, FeatureMode
+
+    parameters =  AF2Parameters(
+        initial_guess_file="3bve_dimer.cif",
+        template_mode=FeatureMode.NONE,
+        msa_mode=FeatureMode.NONE,
+        random_seed=0,
+        num_recycle=3,
+    )
+
+    # Obtain the identity token from gcloud auth
+    identity_token = get_id_token()
+
+    try:
+        response = single_job_prediction(
+            identity_token=identity_token,
+            fasta_file=Path("3bve.fasta"),
+            parameters=parameters,
+        )
+        json.dump(response, open("submission_initial_guess.json", "w"))
+    except Exception as err:
+        print("Error during submission.")
+        print(err)
+    ```
+
+=== ":material-language-python: script for batch job"
+
+    To submit jobs with custom files programmatically, we use helper functions made available in the [`folding_studio` package](../../../tutorials/installation.md#cli-and-folding_studio-library) library.
+
+    ```python
+    import json
+    from pathlib import Path
+
+    from folding_studio import batch_prediction_from_file
+    from folding_studio import get_id_token
+    from folding_studio_data_models import (
+        AF2Parameters,
+        AF2Request,
+        BatchRequest,
+        FeatureMode,
+        Sequence,
+    )
+
+    requests = [
+        AF2Request(
+            complex_id="3bve-ig",
+            sequences=[
+                Sequence(
+                    description="chain A",
+                    fasta_sequence="PMLSKDIIKLLNEQVNKEMNSSNLYMSMSSWCYTHSLDGAGLFLFDHAAEEYEHAKKLIIFLNENNVPVQLTSISAPEHKFEGLTQIFQKAYEHEQHISESINNIVDHAIKSKDHATFNFLQWYVAEQHEEEVLFKDILDKIELIGNENHGLYLADQYVKGIAKSRK",
+                ),
+                Sequence(
+                    description="chain B",
+                    fasta_sequence="PMLSKDIIKLLNEQVNKEMNSSNLYMSMSSWCYTHSLDGAGLFLFDHAAEEYEHAKKLIIFLNENNVPVQLTSISAPEHKFEGLTQIFQKAYEHEQHISESINNIVDHAIKSKDHATFNFLQWYVAEQHEEEVLFKDILDKIELIGNENHGLYLADQYVKGIAKSRK",
+                ),
+            ],
+            parameters= AF2Parameters(
+                num_recycle=3,
+                random_seed=145,
+                msa_mode=FeatureMode.NONE,
+                template_mode=FeatureMode.NONE,
+                initial_guess_file="3bve_dimer.cif",
+            ),
+        ),
+        AF2Request(
+            complex_id="1hqk-ig",
+            sequences=[
+                Sequence(
+                    description=f"chain {i + 1}",
+                    fasta_sequence="MQIYEGKLTAEGLRFGIVASRFNHALVDRLVEGAIDCIVRHGGREEDITLVRVPGSWEIPVAAGELARKEDIDAVIAIGVLIRGATPHFDYIASEVSKGLANLSLELRKPITFGVITADTLEQAIERAGTKHGNKGWEAALSAIEMANLFKSLR",
+                )
+                for i in range(5)
+            ],
+            parameters= AF2Parameters(
+                num_recycle=3,
+                random_seed=145,
+                msa_mode=FeatureMode.NONE,
+                template_mode=FeatureMode.NONE,
+                initial_guess_file="1hqk_pentamer.cif",
+            ),
+        ),
+    ]
+
+    # Build and validate the request
+    batch_request = BatchRequest(requests=requests)
+
+    # Prepare the batch request file for submission
+    json_data = batch_request.model_dump_json()
+    batch_file = Path("batch_request.json")
+    batch_file.write_text(json_data)
+
+    # Obtain the identity token from gcloud auth
+    identity_token = get_id_token()
+
+    try:
+        response = batch_prediction_from_file(
+            identity_token=identity_token, file=batch_file
+        )
+        json.dump(response, open("submission_batch.json", "w"))
+    except Exception as err:
+        print("Error during batch submission.")
+        print(err)
+    ```

folding-studio/docs/docs/how-to-guides/af2_openfold/advanced_algorithms/msa_subsampling_job.md

@@ -0,0 +1,37 @@
+## Goal
+MSA subsampling allows to change the default number of MSA representation to give as input to the model.
+
+This feature is only supported for monomer.
+
+The impact of MSA subsampling has been studied by [D. Del Alamo et al.](https://elifesciences.org/articles/75751).
+
+!!! quote
+    "Whereas models of most proteins generated using the default AF2 pipeline are conformationally homogeneous and nearly identical to one another, reducing the depth of the input multiple sequence alignments by stochastic subsampling led to the generation of accurate models in multiple conformations."
+    - D. Del Alamo et al.
+
+## Application
+To enable MSA subsampling, you can modify the `max_extra_msa` and `max_msa_cluster` parameters.
+
+- `max_extra_msa` : maximum number of non-clustered MSA representation to use as input
+- `max_msa_cluster` : maximum number of clustered MSA representation to use as input
+
+By default `max_msa_cluster` will be half the value of `max_extra_msa`, up to 512.
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding predict af2 path/to/my/file.fasta --max-extra-msa 124 --max-msa-cluster 32
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from pathlib import Path
+    from folding_studio.commands.predict import af2 as af2_predict
+
+    af2_predict(source=Path("path/to/my/file.fasta"), max_extra_msa=124, max_msa_cluster=32)
+    ```
+
+
+!!! warning
+    The specified `max_extra_msa` or `max_msa_cluster` values are applied to all AlphaFold2/OpenFold models.

folding-studio/docs/docs/how-to-guides/af2_openfold/advanced_algorithms/template_masking_job.md

@@ -0,0 +1,549 @@
+## Goal
+Template Masking enables the creation of template features by masking regions
+of the structures considered less important for resolving the multimer
+interface.
+
+## Application
+This method is exclusively available in Gap Trick mode. Therefore
+the same constraints on the input template structures applies, i.e they
+**MUST** exclusively include chains that precisely correspond to the query
+sequences, no more, no less, and in the same order.
+
+Consider an input `FASTA` file containing 3 chains of a multimer complex, for example an antigen chain and two antibody chains:
+
+!!! example
+    ```title="antibody_antigen.fasta"
+    >Antigen
+    VRFPNITNLCPFHEVFNATTFASVYAWNRKRISNCVADYSVIYNFAPFFAFKCYGVSPTKLNDLCFTNVYADSFVIRGNEVSQIAPGQTGNIADYNYKLPDDFTGCVIAWNSNKLDSKPSGNYNYLYRLFRKSKLKPFERDISTEIYQAGNKPCNGVAGPNCYSPLQSYGFRPTYGVGHQPYRVVVLSFELLHAPATVCGPK
+    >Antibody | Chain 1
+    DIQMTQSPSSLSASVGDRVTITCRASQSISSYLNWYQQKPGKAPKLLIYAASSLQSGVPSRFSGSGSGTDFTLTISSLQPEDFATYYCQQSYSTPGVTFGPGTKVDIK
+    >Antibody | Chain 2
+    QVQLVESGGGVVQPGRSLRLSCAASGFTFSSYDMHWVRQAPGKGLEWVAVISYDGSSKFYAESVKGRFTISRDNSKNTLYLQMNSLRAEETAVYYCVKDGEQLVPLFDYWGQGTLVTVSS
+    ```
+
+The user aims to resolve the binding interface between the antigen and antibody
+chains, which is a common scenario for applying the template masking algorithm.
+In this case, a single template file is used, and the masking pattern
+alternately masks the binding partners and the binding interface. To
+activate the template masking algorithm, the user must provide a template mask
+file that defines the masking pattern:
+
+!!! example
+
+    ```json title="masks.json"
+    {
+      "templates_masks": [
+        {
+          "template_name": "7si2_chothia_CGF.cif",
+          "masks": [
+            "----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------",
+            "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
+            "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
+          ]
+        },
+        {
+          "template_name": "7si2_chothia_CGF.cif",
+          "masks": [
+            "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
+            "------------------------------------------------------------------------------------------------------------",
+            "------------------------------------------------------------------------------------------------------------------------"
+          ]
+        },
+        {
+          "template_name": "7si2_chothia_CGF.cif",
+          "masks": [
+            "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX--XXXXXX----------XX--XXXXXXXXXXXXXXXXXXXXX-XXXXXXXXXXXXXX---XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
+            "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-----XXXXXXXXXXXX",
+            "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX----XX--X-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-XX----XXXXXXXXXXXXXXX"
+          ]
+        }
+      ]
+    }
+    ```
+The `masks` fields must adhere to the following constraints:
+
+- Contain as many mask line as chains in the input `FASTA` file,
+- Each mask line must have as many characters as the corresponding chain in the input `FASTA` file,
+- Only contain `X` (residue is masked) or `-` (residue is not masked) characters,
+
+## Submission
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding predict af2 antibody_antigen.fasta --gap-trick --template-mode custom --custom-template 7si2_chothia_CGF.cif --templates-masks-file masks.json
+    ```
+
+=== ":octicons-command-palette-16: CLI batch job"
+
+    ```bash
+    folding predict af2 batch_jobs.csv
+    ```
+    === ":material-table: CSV example"
+
+    ```csv
+    complex_id,description,fasta_sequence,num_recycle,random_seed,gap_trick,msa_mode,template_mode,custom_templates,templates_masks_file
+    Antibody + Antigen,Antigen,VRFPNITNLCPFHEVFNATTFASVYAWNRKRISNCVADYSVIYNFAPFFAFKCYGVSPTKLNDLCFTNVYADSFVIRGNEVSQIAPGQTGNIADYNYKLPDDFTGCVIAWNSNKLDSKPSGNYNYLYRLFRKSKLKPFERDISTEIYQAGNKPCNGVAGPNCYSPLQSYGFRPTYGVGHQPYRVVVLSFELLHAPATVCGPK,3,145,1,none,custom,['templates/7si2_chothia_CGF.cif'],templates_masks/ab_ag_mask_0.json
+    Antibody + Antigen,Antigen | Chain 1,DIQMTQSPSSLSASVGDRVTITCRASQSISSYLNWYQQKPGKAPKLLIYAASSLQSGVPSRFSGSGSGTDFTLTISSLQPEDFATYYCQQSYSTPGVTFGPGTKVDIK,3,145,1,none,custom,['templates/7si2_chothia_CGF.cif'],templates_masks/ab_ag_mask_0.json
+    Antibody + Antigen,Antibody | Chain 2,QVQLVESGGGVVQPGRSLRLSCAASGFTFSSYDMHWVRQAPGKGLEWVAVISYDGSSKFYAESVKGRFTISRDNSKNTLYLQMNSLRAEETAVYYCVKDGEQLVPLFDYWGQGTLVTVSS,3,145,1,none,custom,['templates/7si2_chothia_CGF.cif'],templates_masks/ab_ag_mask_0.json
+    ```
+
+=== ":material-language-python: script for single job"
+
+    To submit jobs with custom files programmatically, we use helper functions made available in the [`folding_studio` package](../../../tutorials/installation.md#cli-and-folding_studio-library) library.
+
+    ```python
+    import json
+    from pathlib import Path
+
+    from folding_studio import get_id_token
+    from folding_studio import single_job_prediction
+    from folding_studio_data_models import AF2Parameters, FeatureMode
+
+    parameters =  AF2Parameters(
+        custom_templates=["7si2_chothia_CGF.cif"],
+        template_mode=FeatureMode.CUSTOM,
+        gap_trick=True,
+        templates_masks_file="ab_ag_mask_0.json",
+        random_seed=0,
+        num_recycle=3,
+    )
+
+    # Obtain the identity token from gcloud auth
+    identity_token = get_id_token()
+
+    try:
+        response = single_job_prediction(
+            identity_token=identity_token,
+            fasta_file=Path("ab_ag.fasta"),
+            parameters=parameters,
+            ignore_cache=True,
+        )
+        json.dump(response, open("submission_tm.json", "w"))
+    except Exception as err:
+        print("Error during submission.")
+        print(err)
+    ```
+
+=== ":material-language-python: script for batch job"
+
+    To submit jobs with custom files programmatically, we use helper functions made available in the [`folding_studio` package](../../../tutorials/installation.md#cli-and-folding_studio-library) library.
+
+    ```python
+    import json
+    from pathlib import Path
+
+    from folding_studio import batch_prediction_from_file
+    from folding_studio import get_id_token
+    from folding_studio_data_models import (
+        AF2Parameters,
+        AF2Request,
+        BatchRequest,
+        FeatureMode,
+        Sequence,
+    )
+
+    requests = [
+        AF2Request(
+            complex_id="Antibody + Antigen",
+            sequences=[
+                Sequence(
+                    description="Antigen",
+                    fasta_sequence="VRFPNITNLCPFHEVFNATTFASVYAWNRKRISNCVADYSVIYNFAPFFAFKCYGVSPTKLNDLCFTNVYADSFVIRGNEVSQIAPGQTGNIADYNYKLPDDFTGCVIAWNSNKLDSKPSGNYNYLYRLFRKSKLKPFERDISTEIYQAGNKPCNGVAGPNCYSPLQSYGFRPTYGVGHQPYRVVVLSFELLHAPATVCGPK",
+                ),
+                Sequence(
+                    description="Antibody | Chain 1",
+                    fasta_sequence="DIQMTQSPSSLSASVGDRVTITCRASQSISSYLNWYQQKPGKAPKLLIYAASSLQSGVPSRFSGSGSGTDFTLTISSLQPEDFATYYCQQSYSTPGVTFGPGTKVDIK",
+                ),
+                Sequence(
+                    description="Antibody | Chain 2",
+                    fasta_sequence="QVQLVESGGGVVQPGRSLRLSCAASGFTFSSYDMHWVRQAPGKGLEWVAVISYDGSSKFYAESVKGRFTISRDNSKNTLYLQMNSLRAEETAVYYCVKDGEQLVPLFDYWGQGTLVTVSS",
+                ),
+            ],
+            parameters= AF2Parameters(
+                template_mode=FeatureMode.CUSTOM,
+                gap_trick=True,
+                custom_templates=["templates/7si2_chothia_CGF.cif"],
+                templates_masks_file="templates_masks/ab_ag_mask_0.json",
+            ),
+        ),
+        AF2Request(
+            complex_id="Mutated Antibody + Antigen",
+            sequences=[
+                Sequence(
+                    description="Antigen",
+                    fasta_sequence="VRFPNITNLCPFHEVFNATTFASVYAWNRKRISNCVADYSVIYNFAPFFAFKCYGVSPTKLNDLCFTNVYADSFVIRGNEVSQIAPGQTGNIADYNYKLPDDFTGCVIAWNSNKLDSKPSGNYNYLYRLFRKSKLKPFERDISTEIYQAGNKPCNGVAGPNCYSPLQSYGFRPTYGVGHQPYRVVVLSFELLHAPATVCGPK",
+                ),
+                Sequence(
+                    description="Antibody | Chain 1",
+                    fasta_sequence="DIQMTQSPSSLSASVGDRVTITCRASQSISSYLNWYQQKPGKAPKLLIYAASSLQSGVPSRFSGSGSGTDFTLTISSLQPEDFATYYCQQSYSTPGVTFGPGTKVDIM",
+                ),
+                Sequence(
+                    description="Antibody | Chain 2",
+                    fasta_sequence="QVQLVESGGGVVQPGRSLRLSCAASGFTFSSYDMHWVRQAPGKGLEWVAVISYDGSSKFYAESVKGRFTISRDNSKNTLYLQMNSLRAEETAVYYCVKDGEQLVPLFDYWGQGTLVTVSM",
+                ),
+            ],
+            parameters= AF2Parameters(
+                template_mode=FeatureMode.CUSTOM,
+                gap_trick=True,
+                custom_templates=["templates/7si2_chothia_CGF.cif"],
+                templates_masks_file="templates_masks/ab_ag_mask_0.json",
+            ),
+        ),
+    ]
+    # Build and validate the request
+    batch_request = BatchRequest(requests=requests)
+
+    # Prepare the batch request file for submission
+    json_data = batch_request.model_dump_json()
+    batch_file = Path("batch_request.json")
+    batch_file.write_text(json_data)
+
+    # Obtain the identity token from gcloud auth
+    identity_token = get_id_token()
+
+    try:
+        response = batch_prediction_from_file(
+            identity_token=identity_token, file=batch_file
+        )
+        json.dump(response, open("submission_batch.json", "w"))
+    except Exception as err:
+        print("Error during batch submission.")
+        print(err)
+    ```
+
+## Generate mask
+
+We provide the following guide for generating the mask file for binding
+partners: A (antigen chain) and B and C (antibody chains). This process
+requires the `bioblocks` package. Please refer to this
+[page](https://instadeep.gitlab.io/bioai-group/BioBlocks/setup/setup.html) for
+installation instructions.
+
+  ```python
+
+  from __future__ import annotations
+  import numpy as np
+  from pathlib import Path
+  import warnings
+  import json
+
+  from bioblocks.blocks import Model, Residue, Chain
+  from bioblocks.io import read_model
+  from bioblocks.sequence import get_alignment_score, align_sequences
+
+
+  THRESHOLD: float = 10.0
+  MASK_TOKEN: str = "X"
+  KEEP_TOKEN: str = "-"
+
+
+  def get_ca_atom_coord(residue: Residue) -> np.ndarray:
+      """Get CA atoms or None if not present.
+
+      Args:
+          residue (Residue): Residue entity.
+
+      Returns:
+          np.ndarray: Array of coordinates
+      """
+      try:
+          coords = np.array(residue["CA"].coord)
+      except:
+          chain_id = residue.parent.id
+          model_id = residue.parent.parent.id
+          warnings.warn(
+              f"{residue.id}, chain {chain_id}, model {model_id} misses CA atom"
+          )
+          coords = np.array([None, None, None])
+      return coords
+
+
+  def fix_nan_ca_coords(ca_atoms: np.ndarray) -> np.ndarray:
+      """Interpolate missing CA atom coordinates.
+
+      Args:
+          ca_atoms (np.ndarray): CA atom coordinates.
+
+      Returns:
+          np.ndarray: Updated atom coordinates without missing entries.
+      """
+      nan_entries = np.unique(np.where(ca_atoms == None)[0])
+      if nan_entries.size == 0:
+          return ca_atoms
+      ca_atoms_out = ca_atoms.copy()
+      for idx in nan_entries:
+          if idx == 0:
+              ca_atoms_out[idx, :] = ca_atoms_out[idx + 1, :]
+          else:
+              ca_atoms_out[idx, :] = ca_atoms_out[idx - 1, :]
+      ca_atoms_out = ca_atoms_out.astype(np.float32)
+      return ca_atoms_out
+
+
+  def compute_chain_contact_mask(
+      chain: Chain, docking_partner_ca_atoms: np.ndarray, threshold: float = THRESHOLD
+  ) -> str:
+      """Compute contact mask for a chain.
+
+      Args:
+          chain (Chain): Chain entity of a loaded structure.
+          docking_partner_ca_atoms (np.ndarray): Selected atoms of the docking partner counter to
+                                                the current chain.
+          threshold (float): Threshold on CA-CA distance.
+
+      Returns:
+          str: String defining contact residues for the chain.
+      """
+      chain_atoms = np.array([get_ca_atom_coord(r) for r in chain])
+      chain_atoms = fix_nan_ca_coords(chain_atoms)
+
+      distances = np.linalg.norm(
+          chain_atoms[:, None, :] - docking_partner_ca_atoms[None, :, :], axis=-1
+      )
+      distance_mask = (distances < threshold).any(axis=-1)
+      mask = "".join(
+          KEEP_TOKEN if distance_mask_i else MASK_TOKEN
+          for distance_mask_i in distance_mask
+      )
+      return mask
+
+
+  def generate_contact_masks_from_template(
+      model: Model, docking_partners: str, threshold: float = THRESHOLD
+  ) -> dict[str, np.ndarray]:
+      """Generate contact masks from a template.
+
+      Args:
+          model (Model): Model entity of a loaded structure.
+          docking_partners (str): Docking partners split by "_", e.g. A_BC.
+          threshold (float): Threshold to compute contact residues based on CA distances.
+
+      Returns:
+          dict[str, np.ndarry]: Contact map for each chain.
+      """
+      left_partners, right_partners = docking_partners.split("_")
+      left_partner_atoms = np.array(
+          [get_ca_atom_coord(r) for chain_id in left_partners for r in model[chain_id]]
+      )
+      right_partner_atoms = np.array(
+          [get_ca_atom_coord(r) for chain_id in right_partners for r in model[chain_id]]
+      )
+      left_partner_atoms = fix_nan_ca_coords(left_partner_atoms)
+      right_partner_atoms = fix_nan_ca_coords(right_partner_atoms)
+      mask_left = {
+          chain_id: compute_chain_contact_mask(
+              model[chain_id], right_partner_atoms, threshold
+          )
+          for chain_id in left_partners
+      }
+      mask_right = {
+          chain_id: compute_chain_contact_mask(
+              model[chain_id], left_partner_atoms, threshold
+          )
+          for chain_id in right_partners
+      }
+      return {**mask_left, **mask_right}
+
+
+  def parse_fasta_as_dict(fasta_string: str) -> dict[str, str]:
+      """Parses FASTA string and returns dictionary of description and sequence.
+
+      Args:
+          fasta_string (str): The string contents of a FASTA file.
+
+      Returns:
+          dict[str, str]: Mapping between description and sequences of the FASTA string.
+      """
+      sequences = []
+      descriptions = []
+      index = -1
+      for line in fasta_string.splitlines():
+          line = line.strip()
+          if line.startswith(">"):
+              index += 1
+              descriptions.append(line[1:])  # Remove the '>' at the beginning.
+              sequences.append("")
+              continue
+          elif not line:
+              continue  # Skip blank lines.
+          sequences[index] += line
+
+      return {d: s for d, s in zip(descriptions, sequences)}
+
+
+  def fasta_to_template_chains(fasta_map: dict[str, str], model: Model) -> dict[str, str]:
+      """Map fasta sequences to template model chain labels based on sequence similarity.
+
+      Note:
+          Template structure must have at least the same number of chains as a number of query fasta sequences.
+
+      Args:
+          fasta_map (dict[str, str]): Mapping between description and sequences.
+          model (Model): Model entity of a loaded structure.
+
+      Returns:
+          dict[str, str | None]: Mapping between model descriptions and structure chain labels.
+      """
+      chain_dict = {
+          chain.id: chain.sequence.replace("X", "") for chain in model.get_chains()
+      }
+      output_mapping = {desc_i: None for desc_i in fasta_map}
+      for desc_i, seq_i in fasta_map.items():
+          if chain_dict:
+              scores = [(k, get_alignment_score(v, seq_i)) for k, v in chain_dict.items()]
+              scores.sort(key=lambda x: x[1])
+              output_mapping[desc_i] = scores[-1][0]
+              del chain_dict[scores[-1][0]]
+      return output_mapping
+
+
+  def get_alignment_index_mapping(
+      seq_1: str, seq_2: str, aligned: bool = True
+  ) -> dict[int, int]:
+      """Mapping of aligned residue indices between two sequences.
+
+      Args:
+          seq_1 (str): First sequence.
+          seq_2 (str): Second sequence.
+          aligned (bool): Flag denoting whether the sequences are aligned or not.
+
+      Returns:
+          dict[int, int]: Dictionary containing the mapping between ``seq_1`` and ``seq_2``
+              indices. The keys correspond to the residue indices in the original target sequence,
+              the values correspond to the residue indices in the original template sequence.
+      """
+      index_mapping: dict[int, int] = {}
+      res_idx_1, res_idx_2 = 0, 0
+      for res_1, res_2 in (
+          zip(seq_1, seq_2) if aligned else zip(align_sequences(seq_1, seq_2))
+      ):
+          # If the chains do not contain the same residues, ignore
+          if res_1 == "-" or res_2 == "-":
+              res_idx_1 += res_1 != "-"
+              res_idx_2 += res_2 != "-"
+              continue
+
+          index_mapping[res_idx_1] = res_idx_2
+          res_idx_1 += 1
+          res_idx_2 += 1
+      return index_mapping
+
+
+  def get_sequence_contact_mask(
+      fasta_map: dict[str, str],
+      model: Model,
+      docking_partners: str,
+      threshold: float = THRESHOLD,
+      not_mapped_fill_token: str = MASK_TOKEN,
+  ) -> dict[str, str]:
+      """Generate contact mask for each sequence in the fasta file corresponding to a template.
+
+      Args:
+          fasta_map (dict[str, str]): Mapping between description and sequences.
+          model (Model): Model entity of a loaded structure.
+          docking_partners (str): Docking partners split by "_", e.g. A_BC.
+          threshold (float): Threshold to compute contact residues based on CA distances.
+          not_mapped_fill_token (str): Fill token for sequences that were not mapped to template.
+
+      Returns:
+          dict[str,str]: Mapping between fasta descriptions and sequence contact maps.
+      """
+      fasta2template = fasta_to_template_chains(fasta_map, model)
+      template_contact_masks = generate_contact_masks_from_template(
+          model, docking_partners, threshold
+      )
+      contact_masks: dict[str, str] = {}
+      for desc_i, chain_id in fasta2template.items():
+          fasta_seq = fasta_map[desc_i]
+          if chain_id:
+              template_seq = model[chain_id].sequence.replace("X", "")
+              aligned_sequences = align_sequences(fasta_seq, template_seq)
+              chain_mask = template_contact_masks[chain_id]
+              idx_mapping = get_alignment_index_mapping(*aligned_sequences)
+              fasta_seq_mask = "".join(
+                  not_mapped_fill_token
+                  if i not in idx_mapping
+                  else chain_mask[idx_mapping[i]]
+                  for i in range(len(fasta_seq))
+              )
+          else:
+              fasta_seq_mask = not_mapped_fill_token * len(fasta_seq)
+          contact_masks[desc_i] = fasta_seq_mask
+      return contact_masks
+
+
+  def get_partners_masks(
+      fasta_map: dict[str, str],
+      model: Model,
+      docking_partners: str,
+      not_mapped_fill_token: str = MASK_TOKEN,
+  ) -> list[dict[str, str]]:
+      """Generate masks for chains of each docking partner.
+
+      Args:
+          fasta_map (dict[str, str]): Mapping between description and sequences.
+          model (Model): Model entity of a loaded structure.
+          docking_partners (str): Docking partners split by "_", e.g. A_BC.
+          not_mapped_fill_token (str): Fill token for sequences that were not mapped to template.
+
+      Returns:
+          list[dict[str,str]]: List of mappings for each docking partner.
+      """
+      fasta2template = fasta_to_template_chains(fasta_map, model)
+      fasta2template_inv = {v: k for k, v in fasta2template.items() if v}
+      docking_partners_split = docking_partners.split("_")
+      output_masks: list[dict[str, str]] = []
+      for dp_i in docking_partners_split:
+          output_masks_i: dict[str, str] = {
+              k: not_mapped_fill_token * len(fasta_map[k]) for k in fasta2template
+          }
+          for chain_i in fasta2template_inv:
+              desc = fasta2template_inv[chain_i]
+              if chain_i in dp_i:
+                  output_masks_i[desc] = KEEP_TOKEN * len(fasta_map[desc])
+              else:
+                  output_masks_i[desc] = MASK_TOKEN * len(fasta_map[desc])
+          output_masks.append(output_masks_i)
+      return output_masks
+
+
+  if __name__ == "__main__":
+      model_path = Path("7si2_chothia_CGF.cif")
+      docking_partners = "A_BC"
+
+      model = read_model(model_path)
+
+      fasta = (
+          ">Antigen\n"
+          "VRFPNITNLCPFHEVFNATTFASVYAWNRKRISNCVADYSVIYNFAPFFAFKCYGVSPTKLNDLCFTNVYADSFVIRGNEVSQIAPGQTGNIADYNYKLPDDFTGCVIAWNSNKLDSKPSGNYNYLYRLFRKSKLKPFERDISTEIYQAGNKPCNGVAGPNCYSPLQSYGFRPTYGVGHQPYRVVVLSFELLHAPATVCGPK\n"
+          ">Antibody | Chain 1\n"
+          "DIQMTQSPSSLSASVGDRVTITCRASQSISSYLNWYQQKPGKAPKLLIYAASSLQSGVPSRFSGSGSGTDFTLTISSLQPEDFATYYCQQSYSTPGVTFGPGTKVDIK\n"
+          ">Antibody | Chain 2\n"
+          "QVQLVESGGGVVQPGRSLRLSCAASGFTFSSYDMHWVRQAPGKGLEWVAVISYDGSSKFYAESVKGRFTISRDNSKNTLYLQMNSLRAEETAVYYCVKDGEQLVPLFDYWGQGTLVTVSS"
+      )
+
+      fasta_map = parse_fasta_as_dict(fasta_string=fasta)
+
+      contact_masks = get_sequence_contact_mask(fasta_map, model, docking_partners)
+      partners_masks = get_partners_masks(fasta_map, model, docking_partners)
+
+      output_dict = {"templates_masks": []}
+      for partner_mask_i in partners_masks:
+          output_dict["templates_masks"].append(
+              {
+                  "template_name": model_path.name,
+                  "masks": list(partner_mask_i.values()),
+              }
+          )
+      output_dict["templates_masks"].append(
+          {
+              "template_name": model_path.name,
+              "masks": list(contact_masks.values()),
+          }
+      )
+
+      mask_file = "masks.json"
+      with open(mask_file, "w") as f:
+          json.dump(output_dict, f, indent=2)
+  ```

folding-studio/docs/docs/how-to-guides/af2_openfold/batch_job_from_configuration_file.md

@@ -0,0 +1,204 @@
+## Goal
+
+A batch job allow to submit multiple jobs at once. This avoids making too much API calls.
+To submit a batch job through the folding CLI, you can pass a configuration file in `json` or `csv` format.
+
+
+## Defining a batch job configuration file
+A common way of submitting a batch job is via a configuration file in `json` or `csv` format.
+When submitting a batch job through a configuration file, all the options passed to the predict command will be ignored.
+
+### JSON
+
+For a `json` format configuration file, its structure needs to be the same as a [`BatchRequest`](https://folding-studio-data-models-dot-int-bio-foldingstudio-gcp.nw.r.appspot.com/request/#folding_studio_data_models.request.BatchRequest) object.
+
+=== "json"
+
+    ```json
+    {
+      "requests": [
+        {
+          "complex_id": "mono_2LIS_auto_msa_custom_template",
+          "sequences": [
+            {
+              "description": ">mono_2LIS_auto_msa_custom_template|2LIS_1|Chain A|SPERM LYSIN|Haliotis rufescens (6454)",
+              "fasta_sequence": "RSWHYVEPKFLNKAFEVALKVQIIAGFDRGLVKWLRVHGRTLSTVQKKALYFVNRRYMQTHWANYMLWINKKIDALGRTPVVGDYTRLGAEIGRRIDMAYFYDFLKDKNMIPKYLPYMEEINRMRPADVPVKYMGK"
+            }
+          ],
+          "folding_model": "af2",
+          "parameters": {
+            "num_recycle": 3,
+            "random_seed": null,
+            "custom_templates": ["5II8"],
+            "gap_trick": false,
+            "msa_mode": "search",
+            "template_mode": "custom"
+          }
+        },
+        {
+          "complex_id": "multi_6M0J_standard",
+          "sequences": [
+            {
+              "description": ">multi_6M0J_standard|6M0J_1|Chain A|Angiotensin-converting enzyme 2|Homo sapiens (9606)",
+              "fasta_sequence": "STIEEQAKTFLDKFNHEAEDLFYQSSLASWNYNTNITEENVQNMNNAGDKWSAFLKEQSTLAQMYPLQEIQNLTVKLQLQALQQNGSSVLSEDKSKRLNTILNTMSTIYSTGKVCNPDNPQECLLLEPGLNEIMANSLDYNERLWAWESWRSEVGKQLRPLYEEYVVLKNEMARANHYEDYGDYWRGDYEVNGVDGYDYSRGQLIEDVEHTFEEIKPLYEHLHAYVRAKLMNAYPSYISPIGCLPAHLLGDMWGRFWTNLYSLTVPFGQKPNIDVTDAMVDQAWDAQRIFKEAEKFFVSVGLPNMTQGFWENSMLTDPGNVQKAVCHPTAWDLGKGDFRILMCTKVTMDDFLTAHHEMGHIQYDMAYAAQPFLLRNGANEGFHEAVGEIMSLSAATPKHLKSIGLLSPDFQEDNETEINFLLKQALTIVGTLPFTYMLEKWRWMVFKGEIPKDQWMKKWWEMKREIVGVVEPVPHDETYCDPASLFHVSNDYSFIRYYTRTLYQFQFQEALCQAAKHEGPLHKCDISNSTEAGQKLFNMLRLGKSEPWTLALENVVGAKNMNVRPLLNYFEPLFTWLKDQNKNSFVGWSTDWSPYADHHHHHH"
+            },
+            {
+              "description": ">multi_6M0J_standard|6M0J_2|Chain B[auth E]|Spike protein S1|Severe acute respiratory syndrome coronavirus 2 (2697049)",
+              "fasta_sequence": "RVQPTESIVRFPNITNLCPFGEVFNATRFASVYAWNRKRISNCVADYSVLYNSASFSTFKCYGVSPTKLNDLCFTNVYADSFVIRGDEVRQIAPGQTGKIADYNYKLPDDFTGCVIAWNSNNLDSKVGGNYNYLYRLFRKSNLKPFERDISTEIYQAGSTPCNGVEGFNCYFPLQSYGFQPTNGVGYQPYRVVVLSFELLHAPATVCGPKKSTNLVKNKCVNFHHHHHH"
+            }
+          ],
+          "folding_model": "openfold",
+          "parameters": {
+            "num_recycle": 2,
+            "random_seed": 5,
+            "gap_trick": false,
+            "msa_mode": "search",
+            "template_mode": "search"
+          }
+        }
+      ]
+    }
+    ```
+
+### CSV
+
+In a `CSV` format configuration file, each row represents a different request. The columns `complex_id`, `description` and `fasta_sequence` describe the proteins, while the others defines options passed for the folding process.
+
+Multimer proteins are specified by listing each chain on separate lines and assigning them the same `complex_id`. Parameters can be repeated or left empty after the first sequence, as the API will only keep the parameters defined for the first sequence of the multimer.
+
+!!! Note
+    The `CSV` format might be a bit tricky to set up in particular when using custom templates and MSAs. In that case, it might be more convenient to use the [`JSON` format](#json).
+
+=== "csv"
+
+    ```csv
+    complex_id,description,fasta_sequence,folding_model,custom_templates,num_recycle,random_seed,msa_mode,template_mode,gap_trick,custom_msas
+    mono_2LIS_auto_msa_custom_template,>2LIS_1|Chain A|SPERM LYSIN|Haliotis rufescens (6454),RSWHYVEPKFLNKAFEVALKVQIIAGFDRGLVKWLRVHGRTLSTVQKKALYFVNRRYMQTHWANYMLWINKKIDALGRTPVVGDYTRLGAEIGRRIDMAYFYDFLKDKNMIPKYLPYMEEINRMRPADVPVKYMGK,af2,"['1agw.cif','1agz.cif']",3,0,search,custom,0,"['1agb_A.sto','1agb_B.sto']"
+    multi_6M0J_standard,>6M0J_1|Chain A|Angiotensin-converting enzyme 2|Homo sapiens (9606),STIEEQAKTFLDKFNHEAEDLFYQSSLASWNYNTNITEENVQNMNNAGDKWSAFLKEQSTLAQMYPLQEIQNLTVKLQLQALQQNGSSVLSEDKSKRLNTILNTMSTIYSTGKVCNPDNPQECLLLEPGLNEIMANSLDYNERLWAWESWRSEVGKQLRPLYEEYVVLKNEMARANHYEDYGDYWRGDYEVNGVDGYDYSRGQLIEDVEHTFEEIKPLYEHLHAYVRAKLMNAYPSYISPIGCLPAHLLGDMWGRFWTNLYSLTVPFGQKPNIDVTDAMVDQAWDAQRIFKEAEKFFVSVGLPNMTQGFWENSMLTDPGNVQKAVCHPTAWDLGKGDFRILMCTKVTMDDFLTAHHEMGHIQYDMAYAAQPFLLRNGANEGFHEAVGEIMSLSAATPKHLKSIGLLSPDFQEDNETEINFLLKQALTIVGTLPFTYMLEKWRWMVFKGEIPKDQWMKKWWEMKREIVGVVEPVPHDETYCDPASLFHVSNDYSFIRYYTRTLYQFQFQEALCQAAKHEGPLHKCDISNSTEAGQKLFNMLRLGKSEPWTLALENVVGAKNMNVRPLLNYFEPLFTWLKDQNKNSFVGWSTDWSPYADHHHHHH,openfold,,2,5,search,search,0,
+    multi_6M0J_standard,>6M0J_2|Chain B[auth E]|Spike protein S1|Severe acute respiratory syndrome coronavirus 2 (2697049),RVQPTESIVRFPNITNLCPFGEVFNATRFASVYAWNRKRISNCVADYSVLYNSASFSTFKCYGVSPTKLNDLCFTNVYADSFVIRGDEVRQIAPGQTGKIADYNYKLPDDFTGCVIAWNSNNLDSKVGGNYNYLYRLFRKSNLKPFERDISTEIYQAGSTPCNGVEGFNCYFPLQSYGFQPTNGVGYQPYRVVVLSFELLHAPATVCGPKKSTNLVKNKCVNFHHHHHH,,,2,5,search,search,0,
+    ```
+
+## Application
+
+### Using the CLI
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding predict af2 batch_job.csv # or batch_job.json
+    ```
+
+### Using Python scripts
+
+To submit a batch job with scripts, we advise using helper functions made
+available in the [`folding_studio` package](../../tutorials/installation.md#cli-and-folding_studio-library) library. This helper
+function will automatically upload the custom files (MSA, templates, initial guess, templates
+masks) you specified in your configuration file.
+You can use a configuration file (see [Defining a batch job configuration file](#defining-a-batch-job-configuration-file)) or define a `JSON` object.
+
+#### From a json object
+
+To submit a batch job from a `JSON` object defined programmatically, we must
+build a
+[`BatchRequest`](https://folding-studio-data-models-dot-int-bio-foldingstudio-gcp.nw.r.appspot.com/request/#folding_studio_data_models.request.BatchRequest)
+object. Once the `BatchRequest` object is built, it is written to a `JSON` file
+and submitted with the `batch_prediction_from_file` helper function from the
+[`folding_studio` package](../../tutorials/installation.md#cli-and-folding_studio-library) library. This helper function will
+automatically upload the custom files (MSA, templates, initial guess, templates
+masks) you specified in your configuration file.
+
+```python
+import json
+from pathlib import Path
+
+from folding_studio import batch_prediction_from_file
+from folding_studio import get_id_token
+from folding_studio_data_models import (
+    AF2Parameters,
+    AF2Request,
+    BatchRequest,
+    FeatureMode,
+    OpenFoldParameters,
+    OpenFoldRequest,
+    Sequence,
+)
+
+folding_requests = [
+    # Monomer job with default AF2 parameters
+    AF2Request(
+        complex_id="Monomer Construct 0001",
+        sequences=[
+            Sequence(description="Wild Type + mutation X", fasta_sequence="MVFKLLLP")
+        ],
+        parameters= AF2Parameters(),
+    ),
+    # Monomer job with default OpenFold parameters
+    OpenFoldRequest(
+        complex_id="Monomer Construct 0001",
+        sequences=[
+            Sequence(description="Wild Type + mutation X", fasta_sequence="MVFKLLLP")
+        ],
+        parameters=OpenFoldParameters(),
+    ),
+    # Multimer job with deactivated template and 5 recycles.
+    AF2Request(
+        complex_id="Multimer Construct id 0001",
+        sequences=[
+            Sequence(description="Wild Type + mutation X", fasta_sequence="MVFKLLLP"),
+            Sequence(description="Antibody S203 Heavy Chain", fasta_sequence="MPAAFFF"),
+            Sequence(description="Antibody S203 Light Chain", fasta_sequence="MPAKK"),
+        ],
+        parameters= AF2Parameters(
+            msa_mode=FeatureMode.SEARCH,
+            template_mode=FeatureMode.NONE,
+            random_seed=0,
+            num_recycle=5,
+        ),
+    ),
+]
+
+# Build and validate the request
+batch_request = BatchRequest(requests=folding_requests)
+
+# Prepare the batch request file for submission
+json_data = batch_request.model_dump_json()
+batch_file = Path("batch_request.json")
+batch_file.write_text(json_data)
+
+# Obtain the identity token from gcloud auth
+identity_token = get_id_token()
+
+try:
+    response = batch_prediction_from_file(
+        identity_token=identity_token, file=batch_file
+    )
+    json.dump(response, open("submission_batch.json", "w"))
+except Exception as err:
+    print("Error during batch submission.")
+    print(err)
+```
+
+#### From a configuration file
+
+To submit a batch job from a configuration file, simply pass it to the `batch_prediction_from_file` helper function from the [`folding_studio` package](../../tutorials/installation.md#cli-and-folding_studio-library) library. This helper function will automatically upload the custom files (MSA, templates, initial guess, templates masks) you specified in your configuration file.
+
+```python
+import json
+from pathlib import Path
+
+from folding_studio import batch_prediction_from_file
+from folding_studio import get_id_token
+
+# Obtain the identity token from gcloud auth
+identity_token = get_id_token()
+
+batch_file = Path("my-batch-file.csv")
+try:
+    response = batch_prediction_from_file(
+        identity_token=identity_token, file=batch_file
+    )
+    json.dump(response, open("submission_batch.json", "w"))
+except Exception as err:
+    print("Error during batch submission.")
+    print(err)
+```

folding-studio/docs/docs/how-to-guides/af2_openfold/batch_job_from_directory.md

@@ -0,0 +1,45 @@
+## Goal
+
+A batch job allow to submit multiple jobs at once. This avoid making too much API calls.
+To submit a batch job through the folding CLI, you can simply pass a directory of FASTA files.
+
+## Application
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding predict af2 path/to/my/fasta/directory --num-recycle 3 --random-seed 0
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from pathlib import Path
+    from folding_studio.commands.predict import af2 as af2_predict
+
+    af2_predict(source=Path("path/to/my/fasta/directory"), num_recycle=3, random_seed=0)
+    ```
+
+Using the CLI, you will get the following information if the job was successfully submitted.
+
+``` { .shell .no-copy }
+Batch prediction job metadata written to batch_prediction_20250305172626.json
+This file contains your experiments ids.
+Batch prediction job submitted successfully !
+The following experiments have been submitted (see batch_prediction_20250305172626.json for the full list):
+['dfdddbc4e2969e327863260ba50f5a3cc1c62992']
+For example, you can query an experiment status with the command:
+
+             folding experiment status dfdddbc4e2969e327863260ba50f5a3cc1c62992
+
+The results of the following experiments were found in the cache (see batch_prediction_20250305172626.json for the full list):
+['a13e8c9003695773b2623179fd0eafdf6296602d']
+Use the `folding experiment results id` command to download the prediction results. For example:
+
+             folding experiment results a13e8c9003695773b2623179fd0eafdf6296602d
+
+```
+
+!!! warning
+    If you submit a batch job using a directory of `FASTA` files, the options passed to the `predict` command will be applied to **ALL** the proteins.
+    If you want to pass protein specific options, you need to submit you batch job through a [configuration file](./batch_job_from_configuration_file.md)

folding-studio/docs/docs/how-to-guides/af2_openfold/cancel_experiment.md

@@ -0,0 +1,31 @@
+## Goal
+
+You can cancel one or more ongoing submission from their `experiment_id`.
+
+For a batch job submission, cancelling one submission won't interfere with the other jobs in the batch.
+
+If you want to cancel a whole batch submission, you have to cancel all the submission experiment ids.
+
+## Application
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding experiment cancel experiment_id_1
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from folding_studio.commands.experiment import cancel
+
+    cancel(exp_id=["experiment_id_1"])
+    ```
+
+!!! Note
+    Requests cannot be cancelled with keyboard interruption
+
+    Cancelling a running process of the CLI or a Python script with a keyboard
+    interruption (`ctrl+c`) **will most likely not** cancel the job submission process.
+    This is because once the `POST` request has reached the server, there is no way
+    to send an interruption signal to the running process on the server.

folding-studio/docs/docs/how-to-guides/af2_openfold/download_logs.md

@@ -0,0 +1,19 @@
+## Goal
+This How-to guide explains how to download the logs of an experiment.
+
+## Application
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding experiment logs b21b09a6a43dcfb282bdc00ec79bd7ae06de97b9 --output ./logs_exp_b21b09.zip
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from pathlib import Path
+    from folding_studio.commands.experiment import logs
+
+    logs(exp_id="b21b09a6a43dcfb282bdc00ec79bd7ae06de97b9", output=Path("./logs_exp_b21b09.zip"))
+    ```

folding-studio/docs/docs/how-to-guides/af2_openfold/download_prediction_results.md

@@ -0,0 +1,55 @@
+## Goal
+
+AlphaFold2/OpenFold models generate predictions and but also confidence metrics. Once the prediction process of an experiment has finished, all of them are saved into a zip file.
+
+The zip file contains :
+
+- The confidence metrics of the models in `.json` format.
+- The relaxed predictions per models in `.pdb` format.
+- The raw predictions per models in `.pkl` format.
+
+Here is an example of the zip file structure :
+
+``` { .shell .no-copy }
+results
+├── metrics_per_model.json
+├── msa_coverage.json
+├── relaxed_predictions
+│   ├── model_1_ptm.pdb
+│   ├── model_2_ptm.pdb
+│   ├── model_3_ptm.pdb
+│   ├── model_4_ptm.pdb
+│   └── model_5_ptm.pdb
+├── rmsd_per_model.json
+└── unrelaxed_predictions
+    ├── model_1_ptm.pdb
+    ├── model_2_ptm.pdb
+    ├── model_3_ptm.pdb
+    ├── model_4_ptm.pdb
+    └── model_5_ptm.pdb
+```
+
+## Application
+
+Once the experiment has finished, you can download the results zip file.
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding experiment results b21b09a6a43dcfb282bdc00ec79bd7ae06de97b9 --output ./result_exp_b21b09.zip
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from pathlib import Path
+    from folding_studio.commands.experiment import results
+
+    results(exp_id="b21b09a6a43dcfb282bdc00ec79bd7ae06de97b9", output=Path("./result_exp_b21b09.zip"))
+    ```
+
+You will get the message:
+
+``` { .shell .no-copy }
+File downloaded successfully to result_exp_b21b09.zip.
+```

folding-studio/docs/docs/how-to-guides/af2_openfold/fetch_folding_job_status.md

@@ -0,0 +1,74 @@
+## Goal
+This how-to guide explains how to manage folding jobs using the `experiment_id`. Each submission creates a unique experiment, enabling caching and avoiding redundant computations. You can track the status of individual or batch jobs with the `experiment_id`.
+
+## Application
+
+### Fetch a job `experiment_id`
+Submitting a folding job creates an experiment. This allows caching and avoid
+useless re-computation of previously submitted folding job.
+This applies also to batch jobs, if you submit a batch of `n` jobs, `n`
+experiments will be created.
+
+Each experiment is associated with a unique `experiment_id`. Its generation is
+deterministic, created from the submitted FASTA sequence (without taking into
+account the description) and the job parameters.
+
+Once your folding job has been submitted, and thus the experiment created, you
+can get various information from the `experiment_id`.
+
+You can get the list of your experiment ids that succeeded or are still pending
+using :
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding experiment list
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from folding_studio.commands.experiment import list
+
+    list()
+    ```
+
+You will get a table with the different experiments launched:
+
+``` { .shell .no-copy }
+Done and pending experiments list written to None
+            Done and pending experiments
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┓
+┃                            Experiment ID ┃ Status ┃
+┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━┩
+│ a13e8c9003695773b2623179fd0eafdf6296602d │ Done   │
+│ 37d816fd1ad0461dd4291963ec10ca5c631058db │Pending │
+└──────────────────────────────────────────┴────────┘
+```
+
+### Retrieve a job status
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding experiment status b21b09a6a43dcfb282bdc00ec79bd7ae06de97b9
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from folding_studio.commands.experiment import status
+
+    status(exp_id="b21b09a6a43dcfb282bdc00ec79bd7ae06de97b9")
+    ```
+
+The experiment status is the current state of the experiment.
+
+| VALUE       | DESCRIPTION                                                                     |
+| ----------- | ------------------------------------------------------------------------------- |
+| `Done`      | The experiment is done and its features and results are available for download. |
+| `Pending`   | The experiment is still ongoing.                                                |
+| `Failed`    | The experiment has failed.                                                      |
+| `Cancelled` | The experiment was cancelled.                                                   |
+
+Once you have submitted a folding job, you can get its status at any time.

folding-studio/docs/docs/how-to-guides/af2_openfold/get_experiment_features.md

@@ -0,0 +1,60 @@
+## Goal
+Before making a folding prediction, a feature generation process will build the two main features needed by the AlphaFold2 model :
+
+- The [Multiple Sequence Alignment](https://en.wikipedia.org/wiki/Multiple_sequence_alignment) (MSA) search results. By default, the Folding Studio pipeline will trigger an MSA search on Uniref90, small BFD, Mgnify and Uniprot (multimer jobs only) using the `jackhmmer` algorithm.
+
+- The protein [template](https://en.wikipedia.org/wiki/Homology_modeling) search results. By default, the Folding Studio pipeline will trigger a template search on the PDB70 structure databases using the `hhsearch` algorithm (`hhblits` for multimer jobs).
+
+Once the feature generation process of an experiment has finished, all the generated features are saved into a zip file.
+
+The zip file contains :
+
+- The full pickled features in `.pkl` format.
+- The output of the MSA search: the MSA search results on multiple databases in `.a3m` format.
+- The output of the template search : the four best matching templates in `.cif` format.
+
+Here is an example of the zip file structure for a monomer :
+
+``` { .shell .no-copy }
+extracted_experiment_features_zip
+├── features.pkl
+├── msas
+│   ├── mgnify_hits.a3m
+│   ├── pdb_hits.hhr
+│   ├── small_bfd_hits.a3m
+│   └── uniref90_hits.a3m
+└── templates
+    ├── 5kwb.cif
+    ├── 6m0j.cif
+    ├── 6vsj.cif
+    ├── 6vw1.cif
+    └── selected_templates.json
+```
+
+For multimer, the structure is similar except that there is a dedicated subdirectory for each protein in the `msas` and `templates` directory.
+
+You can download this zip file to check the generated features and use its content for specifying [custom MSA feature](./../af2_openfold/set_af_folding_parameters.md#custom-msas) or [custom template features](../af2_openfold/set_af_folding_parameters.md#custom-templates) in further experiments.
+
+
+## Application
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding experiment features b21b09a6a43dcfb282bdc00ec79bd7ae06de97b9 --output ./features_exp_b21b09.zip
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from pathlib import Path
+    from folding_studio.commands.experiment import features
+
+    features(exp_id="b21b09a6a43dcfb282bdc00ec79bd7ae06de97b9", output=Path("./features_exp_b21b09.zip"))
+    ```
+
+Once the features are downloaded, you will get the following message:
+
+``` { .shell .no-copy }
+File downloaded successfully to features_exp_b21b09.zip.
+```

folding-studio/docs/docs/how-to-guides/af2_openfold/provide_input_data.md

@@ -0,0 +1,32 @@
+## Goal
+This guide will help you determine whether a given input sequence is compatible with the Alphafold2 and OpenFold models.
+
+## Supported inputs
+
+To submit an folding job with Alphafold2 and OpenFold, you need the sequence input file in
+[`FASTA`](https://en.wikipedia.org/wiki/FASTA_format) format containing your
+protein sequence.
+
+It can be a monomer or a multimer sequence.
+
+=== "monomer"
+
+    ```text
+    >SARS-CoV-2|RBD|Omicron variant
+    RVQPTESIVRFPNITNLCPFDEVFNATRFASVYAWNRKRISNCVADYSVLYNLAPFFTFK
+    CYGVSPTKLNDLCFTNVYADSFVIRGDEVRQIAPGQTGNIADYNYKLPDDFTGCVIAWNS
+    NKLDSKVSGNYNYLYRLFRKSNLKPFERDISTEIYQAGNKPCNGVAGFNCYFPLRSYSFR
+    PTYGVGHQPYRVVVLSFELLHAPATVCGPKKSTNLVKNKCVNF
+    ```
+
+=== "multimer"
+
+    ```text
+    >SARS-CoV-2|RBD|Omicron variant
+    RVQPTESIVRFPNITNLCPFDEVFNATRFASVYAWNRKRISNCVADYSVLYNLAPFFTFK
+    CYGVSPTKLNDLCFTNVYADSFVIRGDEVRQIAPGQTGNIADYNYKLPDDFTGCVIAWNS
+    NKLDSKVSGNYNYLYRLFRKSNLKPFERDISTEIYQAGNKPCNGVAGFNCYFPLRSYSFR
+    PTYGVGHQPYRVVVLSFELLHAPATVCGPKKSTNLVKNKCVNF
+    >Processed angiotensin-converting enzyme 2|Homo sapiens (9606)
+    STIEEQAKTFLDKFNHEAEDLFYQSSLASWNYNTNITEENVQNMNNAGDKWSAFLKEQSTLAQMYPLQEIQNLTVKLQLQALQQNGSSVLSEDKSKRLNTILNTMSTIYSTGKVCNPDNPQECLLLEPGLNEIMANSLDYNERLWAWESWRSEVGKQLRPLYEEYVVLKNEMARANHYEDYGDYWRGDYEVNGVDGYDYSRGQLIEDVEHTFEEIKPLYEHLHAYVRAKLMNAYPSYISPIGCLPAHLLGDMWGRFWTNLYSLTVPFGQKPNIDVTDAMVDQAWDAQRIFKEAEKFFVSVGLPNMTQGFWENSMLTDPGNVQKAVCHPTAWDLGKGDFRILMCTKVTMDDFLTAHHEMGHIQYDMAYAAQPFLLRNGANEGFHEAVGEIMSLSAATPKHLKSIGLLSPDFQEDNETEINFLLKQALTIVGTLPFTYMLEKWRWMVFKGEIPKDQWMKKWWEMKREIVGVVEPVPHDETYCDPASLFHVSNDYSFIRYYTRTLYQFQFQEALCQAAKHEGPLHKCDISNSTEAGQKLFNMLRLGKSEPWTLALENVVGAKNMNVRPLLNYFEPLFTWLKDQNKNSFVGWSTDWSPYADRHHHHHH
+    ```

folding-studio/docs/docs/how-to-guides/af2_openfold/set_af_folding_parameters.md

@@ -0,0 +1,407 @@
+## Goal
+
+The different folding parameters are detailed in the [reference section](../../reference/cli.md#predict) but this how-to guide gives some examples of how to use them.
+
+## Application
+
+### Number of recycle steps
+
+You can choose the number of recycling steps that the input undergoes.
+Recycling steps refer to the iterative refinement process where the input data
+is repeatedly processed through the entire network. During each recycling step,
+the network uses the output from the previous cycle as a new input, allowing it
+to progressively refine and improve its predictions.
+
+This iterative approach can enhance the accuracy of the final output,
+especially for complex structures or cases where more nuanced adjustments are
+needed. By adjusting the number of recycling steps, you can control the balance
+between computational time and the desired level of refinement for your
+predictions
+
+By default, it is set to 3.
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding predict af2 path/to/my/monomer.fasta --num-recycle 5
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from pathlib import Path
+    from folding_studio.commands.predict import af2 as af2_predict
+
+    af2_predict(source=Path("path/to/my/monomer.fasta"), num_recycle=5)
+    ```
+
+### Random seed
+
+To generate different results from the same input sequence, you can change the random seed used during the forward pass.
+
+By default, it is set to 0.
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding predict af2 path/to/my/monomer.fasta --random-seed 42
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from pathlib import Path
+    from folding_studio.commands.predict import af2 as af2_predict
+
+    af2_predict(source=Path("path/to/my/monomer.fasta"), random_seed=42)
+    ```
+
+If you would like to submit a random seed scan job with the CLI, you can use the `--num-seed` option which specifies the number of random seed values to submit.
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding predict af2 path/to/my/monomer.fasta --num-seed 10
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from pathlib import Path
+    from folding_studio.commands.predict import af2 as af2_predict
+
+    af2_predict(source=Path("path/to/my/monomer.fasta"), num_seed=10)
+    ```
+
+### Ignore cached experiments
+
+By default, if you submit a job that has already been submitted, it will not run, and the cached results will be returned.
+This is determined by the job experiment id, see [Fetch a job experiment_id](../../how-to-guides/af2_openfold/fetch_folding_job_status.md#fetch-a-job-experiment_id) for more details.
+
+However, you can override this behavior and force the job to run, even if it was submitted earlier.
+
+!!! warning
+    This will overwrite the previous experiment results, replacing them with the most recent ones.
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding predict af2 path/to/my/monomer.fasta --no-cache
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from pathlib import Path
+    from folding_studio.commands.predict import af2 as af2_predict
+
+    af2_predict(source=Path("path/to/my/monomer.fasta"), cache=False)
+    ```
+
+### Use specific AlphaFold2/OpenFold models
+
+By default, predictions are generated using all five AlphaFold2/OpenFold models. They
+each have slight variations in how they predict protein structures, providing a
+range of potential outcomes.
+Leveraging all five models increases the robustness of the predictions, as it
+allows for a more comprehensive exploration of possible protein conformations.
+
+However, if you wish to narrow down the prediction process to specific models,
+you can do so by specifying the IDs of the models you want to use.
+It allows you to focus on particular models that may be better suited for your
+specific use case or to reduce computational time by excluding models that are
+less relevant for your needs.
+
+Find more details about the difference between the model training procedures
+and inputs
+[here](https://static-content.springer.com/esm/art%3A10.1038%2Fs41586-021-03819-2/MediaObjects/41586_2021_3819_MOESM1_ESM.pdf#page=47).
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding predict af2 path/to/my/monomer.fasta --model-subset 1 --model-subset 2 --model-subset 3
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from folding_studio.commands.predict import af2 as af2_predict
+
+    af2_predict(source=path/to/my/monomer.fasta, model_subset=[1, 2, 3])
+    ```
+
+### Features generation mode
+
+=== "MSA"
+
+    | Value                | Description                                                                                  |
+    | -------------------- | -------------------------------------------------------------------------------------------- |
+    | `"search"` (default) | automated MSA search of sequence databases using `JackHMMer` (Uniref90, small_bfd and mgnfy) |
+    | `"mmseqs"`           | automated search of Uniref30 and Colabfold_env_db using the **self-hosted** `MMSeqs2` server |
+    | `"none"`             | deactivate MSA features features                                                             |
+    | `"custom"`           | use user provided MSA input (`.sto` or `.a3m` format)                                        |
+
+    !!! note
+        `MMSeqs2` produce fairly different MSA results compared to JackHMMer, they use different datasets (Uniref30 and colbafold_env_db) and different search algorithms. However the MSA produced by `MMSeqs2` is generally more diverse and can be leverage predict structures with higher accuracy (see this [publication](https://www.nature.com/articles/s41592-023-02130-4)). For more information about MMSeqs2, please refer to the corresponding [paper](https://www.biorxiv.org/content/10.1101/079681v5).
+
+=== "Templates"
+
+    | Value                | Description                                                                                  |
+    | -------------------- | -------------------------------------------------------------------------------------------- |
+    | `"search"` (default) | automated search of PDB70 structure databases using `hhsearch` (`hhblits` for multimer jobs) |
+    | `"mmseqs"`           | automated search of pdb100 structure database using the **self-hosted** `mmseqs2` server     |
+    | `"none"`             | deactivate template features                                                                 |
+    | `"custom"`           | use user provided template structures (`.cif` format) or PDB code.                          |
+
+#### Custom features
+
+Instead of using the default experiment feature generation process, you might want to specify your own MSA or template features, or even remove them altogether.
+
+We see two main use cases where you might want to override the default feature generation process :
+
+- You want to utilize custom features specifically tailored for your folding job. For example, you have obtained a protein structure from crystallography experiment and want to use as custom templates.
+
+- You already submitted a folding a job for the same protein and you want to use its features to speed up the new jobs.
+
+##### Custom MSAs
+
+To modify the default MSA feature computation behavior, you need to specify the MSA feature computation mode using the `msa_mode="custom"` mode. If you pass custom MSA features but didn't set the MSA feature mode to `custom`, they won't be taken into account and the MSA feature mode will be the default (`search`).
+
+We support specifying custom MSA features as file of `.sto` or `.a3m` formats :
+
+- You need to provide **at least as many** `.sto` or `.a3m` files as chains in the FASTA file. You may provide several MSA files for a chain.
+
+- To assign a custom MSA to a specific chain, append the chain identifier as a suffix to the file name.
+
+!!! example
+    For instance, in a complex with two chains A and B (as listed in the FASTA file), name your custom MSA files `my_custom_msa_A.sto` and `my_custom_msa_B.sto`.
+
+!!! warning
+    If you use `.a3m` files downloaded from a
+    [ColabFold](https://colab.research.google.com/github/sokrypton/ColabFold/blob/main/AlphaFold2.ipynb)
+    notebook run, make sure to remove lines starting with a `#` before submitting
+    the job. These are artifacts added by the ColabFold pipeline after the MMSeqs2
+    run which are not relevant to Folding Studio but **will cause a crash**.
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    # monomer folding job submission with custom msa features
+    folding predict af2 path/to/my/monomer.fasta --msa-mode custom --custom-msa /path/to/monomer_custom_msa_A.sto
+
+    # multimer folding job submission with custom msa features
+    folding predict af2 path/to/my/multimer.fasta --msa-mode custom --custom-msa path/to/custom_msa_1_A.sto --custom-msa path/to/custom_msa_2_A.sto  --custom-msa path/to/custom_msa_B.sto
+
+    # monomer folding job submission with mmseqs for msa and templates
+    folding predict af2 path/to/my/monomer.fasta --msa-mode mmseqs --template-mode mmseqs
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from pathlib import Path
+    from folding_studio.commands.predict import af2 as af2_predict
+
+    # monomer folding job submission with custom msa features
+    af2_predict(source=Path("path/to/my/monomer.fasta"), msa_mode="custom", custom_msa=[Path("/path/to/monomer_custom_msa_A.sto")])
+
+    # multimer folding job submission with custom msa features
+    af2_predict(source=Path("path/to/my/multimer.fasta"), msa_mode="custom", custom_msa=[Path("/path/to/custom_msa_1_A.sto"), Path("/path/to/custom_msa_2_A.sto"), Path("/path/to/custom_msa_B.sto")])
+
+    # monomer folding job submission with mmseqs for msa and templates
+    af2_predict(source=Path("path/to/my/monomer.fasta"), msa_mode="mmseqs", template_mode="mmseqs")
+    ```
+
+##### Custom templates
+
+To modify the default template feature computation behavior, you need to specify the template feature computation mode using the `template_mode` parameter :
+
+We support specifying custom templates as file of `.cif` format or as PDB codes of crystal structures. Both options can be used at the same time for the same job.
+
+You are free to provide as many templates as you wish. However the AlphaFold2 pipeline will only keep the best 4 matching templates.
+
+Note that by design, AlphaFold2 **monomer** models 3, 4, and 5 do not incorporate template features. As a result, modifying the template feature calculations will not affect their predictions.
+
+!!! note
+    If `"template_mode": "search"` is used with `"msa_mode": "none"`, an automated MSA search on Uniref90 will still be run in order to obtain an MSA necessary for `hhsearch/hhblits` to complete the template search.
+    However these MSA search results will not be included in the features.
+
+!!! warning
+    If you pass custom template features but didn't set the template feature mode to `custom`, they won't be taken into account and the template feature mode will be the default (`search`).
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding predict af2 path/to/my/monomer.fasta--template-mode custom --custom-template-id 5ii8 --custom-template-id 6m0j --custom-template /path/to/template_1.cif --custom-template /path/to/template_2.cif --custom-template /path/to/template_3.cif
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from pathlib import Path
+    from folding_studio.commands.predict import af2 as af2_predict
+
+    af2_predict(source=Path("path/to/my/monomer.fasta"), template_mode="custom", custom_template_id=["5ii8", "6m0j"], custom_template=[Path("/path/to/template_1.cif"), Path("/path/to/template_2.cif"), Path("/path/to/template_3.cif")])
+    ```
+
+### Specification for batch jobs
+
+  To submit jobs with custom files programmatically, we use helper functions made available in the `folding_studio` [package](../../tutorials/installation.md#cli-and-folding_studio-library).
+
+=== "Custom templates"
+
+    ```python
+    import json
+    from pathlib import Path
+
+    from folding_studio import batch_prediction_from_file
+    from folding_studio import get_id_token
+    from folding_studio_data_models import (
+        AF2Parameters,
+        AF2Request,
+        BatchRequest,
+        FeatureMode,
+        OpenFoldParameters,
+        OpenFoldRequest,
+        Sequence,
+    )
+
+    # Define local templates path
+    template_A_local_path = "/path/to/custom_template_A.cif"
+    template_B_local_path = "/path/to/custom_template_B.cif"
+    template_C_local_path = "/path/to/custom_template_C.cif"
+
+    # Build the batch request
+    requests = [
+        AF2Request(
+            complex_id="Monomer Construct 0001",
+            sequences=[
+                Sequence(description="Wild Type + mutation X", fasta_sequence="MVFKLLLP")
+            ],
+            parameters= AF2Parameters(
+                template_mode=FeatureMode.CUSTOM, custom_templates=[template_A_local_path]
+            ),
+        ),
+        OpenFoldRequest(
+            complex_id="Monomer Construct 0001 with OpenFold",
+            sequences=[
+                Sequence(description="Wild Type + mutation X", fasta_sequence="MVFKLLLP")
+            ],
+            parameters=OpenFoldParameters(
+                template_mode=FeatureMode.CUSTOM, custom_templates=[template_A_local_path]
+            ),
+        ),
+        AF2Request(
+            complex_id="Multimer Construct id 0001",
+            sequences=[
+                Sequence(description="Wild Type + mutation X", fasta_sequence="MVFKLLLP"),
+                Sequence(description="Antibody S203 Heavy Chain", fasta_sequence="MPAAFFF"),
+                Sequence(description="Antibody S203 Light Chain", fasta_sequence="MPAKK"),
+            ],
+            parameters= AF2Parameters(
+                template_mode=FeatureMode.CUSTOM,
+                custom_templates=[
+                    template_A_local_path,
+                    template_B_local_path,
+                    template_C_local_path,
+                ],
+            ),
+        ),
+    ]
+    # Build and validate the request
+    batch_request = BatchRequest(requests=requests)
+
+    # Prepare the batch request file for submission
+    json_data = batch_request.model_dump_json()
+    batch_file = Path("batch_request.json")
+    batch_file.write_text(json_data)
+
+    # Obtain the identity token from gcloud auth
+    identity_token = get_id_token()
+
+    try:
+        response = batch_prediction_from_file(
+            identity_token=identity_token, file=batch_file
+        )
+        json.dump(response, open("submission_batch.json", "w"))
+    except Exception as err:
+        print("Error during batch submission.")
+        print(err)
+    ```
+
+=== "Custom MSAs"
+
+    ```python
+    import json
+    from pathlib import Path
+
+    from folding_studio import batch_prediction_from_file
+    from folding_studio import get_id_token
+    from folding_studio_data_models import (
+        AF2Parameters,
+        AF2Request,
+        BatchRequest,
+        FeatureMode,
+        OpenFoldParameters,
+        OpenFoldRequest,
+        Sequence,
+    )
+
+    # Define local MSA path
+    msa_A_local_path = "/path/to/custom_msa_A.sto"
+    msa_B_local_path = "/path/to/custom_msa_B.sto"
+    msa_C_local_path = "/path/to/custom_msa_C.sto"
+
+    # Build the batch request
+    requests = [
+        AF2Request(
+            complex_id="Monomer Construct 0001",
+            sequences=[
+                Sequence(description="Wild Type + mutation X", fasta_sequence="MVFKLLLP")
+            ],
+            parameters= AF2Parameters(
+                msa_mode=FeatureMode.CUSTOM, custom_msas=[msa_A_local_path]
+            ),
+        ),
+        OpenFoldRequest(
+            complex_id="Monomer Construct 0001 with OpenFold",
+            sequences=[
+                Sequence(description="Wild Type + mutation X", fasta_sequence="MVFKLLLP")
+            ],
+            parameters=OpenFoldParameters(
+                msa_mode=FeatureMode.CUSTOM, custom_msas=[msa_A_local_path]
+            ),
+        ),
+        AF2Request(
+            complex_id="Multimer Construct id 0001",
+            sequences=[
+                Sequence(description="Wild Type + mutation X", fasta_sequence="MVFKLLLP"),
+                Sequence(description="Antibody S203 Heavy Chain", fasta_sequence="MPAAFFF"),
+                Sequence(description="Antibody S203 Light Chain", fasta_sequence="MPAKK"),
+            ],
+            parameters= AF2Parameters(
+                msa_mode=FeatureMode.CUSTOM,
+                custom_msas=[msa_A_local_path, msa_B_local_path, msa_C_local_path],
+            ),
+        ),
+    ]
+    # Build and validate the request
+    batch_request = BatchRequest(requests=requests)
+
+    # Prepare the batch request file for submission
+    json_data = batch_request.model_dump_json()
+    batch_file = Path("batch_request.json")
+    batch_file.write_text(json_data)
+
+    # Obtain the identity token from gcloud auth
+    identity_token = get_id_token()
+
+    try:
+        response = batch_prediction_from_file(
+            identity_token=identity_token, file=batch_file
+        )
+        json.dump(response, open("submission_batch.json", "w"))
+    except Exception as err:
+        print("Error during batch submission.")
+        print(err)
+    ```

folding-studio/docs/docs/how-to-guides/af2_openfold/single_af2_job.md

@@ -0,0 +1,27 @@
+## Goal
+This how-to guide shows how to run a folding job using AlphaFold2.
+
+!!! Note
+    All the other how-to guides in **AlphaFold2/OpenFold section** of **How-to guides** apply to Alphafold2.
+
+## Application
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding predict af2 path/to/my/file.fasta --num-recycle 3 --random-seed 0
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from pathlib import Path
+    from folding_studio.commands.predict import af2 as af2_predict
+
+    af2_predict(source=Path("path/to/my/file.fasta"), num_recycle=3, random_seed=0)
+    ```
+
+!!! Warning
+    If you consider to submit >10 folding jobs, it is **strongly** advised to
+    use batch job submission from a [directory](./batch_job_from_directory.md) or from a [configuration file](./batch_job_from_configuration_file.md). A batch job will mutualize the feature generation steps, speeding up significantly the jobs processing if
+    they use similar features.

folding-studio/docs/docs/how-to-guides/af2_openfold/single_openfold_job.md

@@ -0,0 +1,27 @@
+## Goal
+This how-to guide shows how to run a folding job using OpenFold, an alternative option to Alphafold2 in Folding Studio.
+
+!!! Note
+    All the other how-to guides in **AlphaFold2/OpenFold section** of **How-to guides** apply to OpenFold.
+
+## Application
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding predict openfold path/to/my/file.fasta --num-recycle 3 --random-seed 0
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from pathlib import Path
+    from folding_studio.commands.predict import openfold as openfold_predict
+
+    openfold_predict(source=Path("path/to/my/file.fasta"), num_recycle=3, random_seed=0)
+    ```
+
+!!! Warning
+    If you consider to submit >10 folding jobs, it is **strongly** advised to
+    use batch job submission from a [directory](./batch_job_from_directory.md) or from a [configuration file](./batch_job_from_configuration_file.md). A batch job will mutualize the feature generation steps, speeding up significantly the jobs processing if
+    they use similar features.

folding-studio/docs/docs/how-to-guides/af2_openfold/soloseq_job.md

@@ -0,0 +1,104 @@
+## Goal
+
+This tutorial explains how to run structure predictions using SoloSeq, an OpenFold-like model.
+
+!!! Warning
+    SoloSeq is a synchronous model and uses different feature engineering process compared to AlphaFold2/Openfold. Therefore, the process of submitting SoloSeq jobs and retrieving output differs significantly from the processes described for AlphaFold2/OpenFold and the different other how-to guides from **AlphaFold2/OpenFold** folder do not apply to SoloSeq.
+
+## Application
+
+### Launch a job from a FASTA file
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding predict soloseq path/to/my/fasta/file.fasta --project-code "your-project-code" --output-dir ./
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from folding_studio.client import Client
+    from folding_studio.query.soloseq import SoloSeqQuery
+
+    inference_parameters = {"project_code": "your-project-code",
+                            "seed":42}
+
+    file_path = "path/to/my/fasta/file.fasta"
+
+    # Create client
+    client = Client.from_jwt()
+
+    # Define query
+    query = SoloSeqQuery.from_file(path=file_path, parameters=inference_parameters)
+
+    # Send request
+    response = client.send_request(query)
+
+    # Download results
+    output_path = "./output.zip"
+    response.download_results(output_path, force=True, unzip=True)
+    ```
+
+### Launch a job from a directory of FASTA files
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding predict soloseq path/to/my/fasta/directory --project-code "your-project-code" --output-dir ./
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from folding_studio.client import Client
+    from folding_studio.query.soloseq import SoloSeqQuery
+
+    inference_parameters = {"project_code": "your-project-code",
+                            "seed":42}
+
+    directory_path = "path/to/my/fasta/directory"
+
+    # Create client
+    client = Client.from_jwt()
+
+    # Define query
+    query = SoloSeqQuery.from_directory(path=directory_path, parameters=inference_parameters)
+
+    # Send request
+    response = client.send_request(query)
+
+    # Download results
+    output_path = "./output.zip"
+    response.download_results(output_path, force=True, unzip=True)
+    ```
+
+### Launch a job from a protein sequence directly
+
+`SoloSeq` allow passing the protein sequence directly as input.
+This makes the prediction job easier to integrate with your code.
+
+=== ":material-language-python: Python"
+
+    ```python
+    from folding_studio.client import Client
+    from folding_studio.query.soloseq import SoloSeqQuery
+
+    inference_parameters = {"project_code": "your-project-code",
+                            "seed":42}
+
+    sequence = ">A|protein\\nQLEDSEVEAVAKGLEEMYANGVTEDNFKNYVKNNFAQQEISSVEEELNVNIS"
+
+    # Create client
+    client = Client.from_jwt()
+
+    # Define query
+    query = SoloSeqQuery.from_protein_sequence(sequence=sequence, parameters=inference_parameters)
+
+    # Send request
+    response = client.send_request(query)
+
+    # Download results
+    output_path = "./output.zip"
+    response.download_results(output_path, force=True, unzip=True)
+    ```

folding-studio/docs/docs/how-to-guides/af3/batch_job_from_directory.md

@@ -0,0 +1,40 @@
+## Goal
+
+A batch job allow to submit multiple jobs at once. This avoid making too much API calls.
+To submit a batch job through the folding CLI, you can simply pass a directory of FASTA files (or both FASTA and YAML files if you are using **Boltz-1** model)
+
+## Application
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding predict boltz path/to/my/fasta/directory --num-recycle 3 --random-seed 0 --output ./ --unzip
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from folding_studio.client import Client
+    from folding_studio.query.boltz import BoltzQuery
+
+    inference_parameters = {"project_code": "your-project-code",
+                            "seed":42}
+
+    directory_path = "path/to/my/fasta/directory"
+
+    # Create client
+    client = Client.authenticate()
+
+    # Define query
+    query = BoltzQuery.from_directory(path=directory_path, parameters=inference_parameters)
+
+    # Send request
+    response = client.send_request(query)
+
+    # Download results
+    output_path = "./output.zip"
+    response.download_results(output_path, force=True, unzip=True)
+    ```
+
+!!! Note
+    Depending on the model you want to use, you can replace `predict boltz` with `predict chai` or `predict protenix`.

folding-studio/docs/docs/how-to-guides/af3/boltz_single_yaml_job.md

@@ -0,0 +1,38 @@
+## Goal
+**Boltz-1** model allows passing a YAML file (or a directory containing YAML files, see [batch job from directory section](./batch_job_from_directory.md) for more details about launching jobs from a directory) as input. The YAML format is more flexible and allows for more complex inputs, particularly around covalent bonds.
+This YAML has to follow the Boltz-1 format below.
+
+See [Boltz-1 documentation about prediction](https://github.com/jwohlwend/boltz/blob/main/docs/prediction.md) for details about YAML input format.
+
+## Application
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding predict boltz path/to/my/file.yaml --project-code "your-project-code" --output ./
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from folding_studio.client import Client
+    from folding_studio.query.boltz import BoltzQuery
+
+    inference_parameters = {"project_code": "your-project-code",
+                            "seed":42}
+
+    file_path = "path/to/my/file.yaml"
+
+    # Create client
+    client = Client.authenticate()
+
+    # Define query
+    query = BoltzQuery.from_file(path=file_path, parameters=inference_parameters)
+
+    # Send request
+    response = client.send_request(query)
+
+    # Download results
+    output_path = "./output.zip"
+    response.download_results(output_path, force=True)
+    ```

folding-studio/docs/docs/how-to-guides/af3/provide_input_data.md

@@ -0,0 +1,39 @@
+## Goal
+This guide will help you determine whether a given input sequence is compatible with the Alphafold3-like models.
+
+## Application
+
+### Alphafold3-like models supported inputs
+To submit an folding job with Alphafold3-like models, you need the sequence input file in
+[`FASTA`](https://en.wikipedia.org/wiki/FASTA_format) format containing your sequence.
+
+AlphaFold3-like models support various molecular types for structure prediction, and these can be provided as input in different formats. Below is a summary of the supported molecular types:
+
+- **Proteins**: Protein sequences are widely supported and can be provided for structure prediction tasks.
+    - monomer
+    - multimer
+- **DNA** and **RNA**: Both DNA and RNA sequences are supported for structure prediction.-
+- **Ligands**: Ligands can be specified in two ways:
+    - SMILES: A textual format describing the chemical structure of molecules.
+    - CCD Code: A standard identifier for chemical compounds, defined in the Chemical Component Dictionary.
+
+**You can find detailed explanations of the input data formats for each model at the links below.**
+
+### Boltz-1
+Here is an explanation of the different input data formats that can be used for Boltz-1 prediction: [Boltz-1 documentation](https://github.com/jwohlwend/boltz/blob/main/docs/prediction.md). You can also find some input [examples](https://github.com/jwohlwend/boltz/tree/main/examples).
+
+### Chai-1
+Here is an explanation of the different input data formats that can be used for Chai-1 with restraints: [Chai-1 documentation](https://github.com/chaidiscovery/chai-lab/blob/main/examples/restraints/README.md). You can also find some input [examples](https://github.com/chaidiscovery/chai-lab/tree/main/examples).
+
+### Protenix
+Here is an explanation of the different input data formats that can be used for Protenix: [Protenix documentation](https://github.com/bytedance/Protenix/blob/main/docs/infer_json_format.md).
+
+!!! Warning
+    The Protenix endpoint currently does not support JSON format. It is a work in progress.
+
+!!! note
+    The Protenix endpoint also accepts RCSB FASTA format following this structure. The number of chains will automatically be derived from the description (e.g. 2 chains in the example below):
+    ``` { .shell .no-copy }
+    >1HSG_1|Chains A, B|HIV-1 PROTEASE|Human immunodeficiency virus 1 (11676)
+    PQITLWQRPLVTIKIGGQLKEALLDTGADDTVLEEMSLPGRWKPKMIGGIGGFIKVRQYDQILIEICGHKAIGTVLVGPTPVNIIGRNLLTQIGCTLNF
+    ```

folding-studio/docs/docs/how-to-guides/af3/single_job_boltz.md

@@ -0,0 +1,72 @@
+## Goal
+
+**Boltz-1** is one of the AlphaFold3-like models supported by Folding Studio. Here is a how-to guide to learn how to launch a simple single folding job on a FASTA file using **Boltz-1**.
+
+## Application
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding predict boltz path/to/my/file.fasta --output ./ --unzip --project-code "your-project-code"
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from folding_studio.client import Client
+    from folding_studio.query.boltz import BoltzQuery
+
+    inference_parameters = {"project_code": "your-project-code"}
+
+    file_path = "path/to/my/file.fasta"
+
+    # Create client
+    client = Client.authenticate()
+
+    # Define query
+    query = BoltzQuery.from_file(path=file_path, parameters=inference_parameters)
+
+    # Send request
+    response = client.send_request(query)
+
+    # Download results
+    output_path = "./output.zip"
+    response.download_results(output_path, force=True, unzip=True)
+    ```
+
+!!! note
+    Do not forget that Boltz-1 accepts FASTA format following this structure
+    ``` { .shell .no-copy }
+    >CHAIN_ID|ENTITY_TYPE|MSA_PATH
+    SEQUENCE
+    ```
+    `MSA_PATH` is ignored if `--use-msa-server` is used.
+
+    For further information on YAML format, check [documentation](https://github.com/jwohlwend/boltz/blob/main/docs/prediction.md).
+
+Using the CLI, you will get the following information if the job was successfully submitted.
+
+``` { .shell .no-copy }
+╭───────────────────────────────╮
+│ 🧬 Boltz1 Folding submission  │
+╰───────────────────────────────╯
+🔑 Authenticating client ✅
+📦 Generating query ✅
+Generated query: {
+  "fasta_files": {
+    "file": ">A|protein|\nQLEDSEVEAVAKGLEEMYANGVTEDNFKNYVKNNFAQQEISSVEEELNVNISDSCVANKIKDEFFAMISISAIVKAAQKKAWKELAVTVLRFAKANGLKTNAIIVAGQLALWAVQCG"
+  },
+  "yaml_files": {},
+  "parameters": {
+    "seed": 42,
+    "recycling_steps": 3,
+    "sampling_steps": 200,
+    "diffusion_samples": 1,
+    "step_scale": 1.638,
+    "msa_pairing_strategy": "greedy",
+    "write_full_pae": false,
+    "write_full_pde": false
+  }
+}
+🧠 Processing folding job ✅
+```

folding-studio/docs/docs/how-to-guides/af3/single_job_chai.md

@@ -0,0 +1,66 @@
+## Goal
+
+**Chai-1** is one of the AlphaFold3-like models supported by Folding Studio. Here is a how-to guide to learn how to launch a simple single folding job on a FASTA file using **Chai-1**.
+
+## Application
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding predict chai path/to/my/file.fasta --output ./ --unzip --project-code "your-project-code"
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from folding_studio.client import Client
+    from folding_studio.query.chai import ChaiQuery
+
+    inference_parameters = {"project_code": "your-project-code"}
+
+    file_path = "path/to/my/file.fasta"
+
+    # Create client
+    client = Client.authenticate()
+
+    # Define query
+    query = ChaiQuery.from_file(path=file_path, parameters=inference_parameters)
+
+    # Send request
+    response = client.send_request(query)
+
+    # Download results
+    output_path = "./output.zip"
+    response.download_results(output_path, force=True, unzip=True)
+    ```
+
+!!! note
+    Do not forget that Chai-1 accepts FASTA format following this structure
+    ``` { .shell .no-copy }
+    >ENTITY_TYPE|STRUCTURE_ID
+    SEQUENCE
+    ```
+
+Using the CLI, you will get the following information if the job was successfully submitted.
+
+``` { .shell .no-copy }
+╭───────────────────────────────╮
+│ 🧬 Chai-1 Folding submission  │
+╰───────────────────────────────╯
+🔑 Authenticating client ✅
+📦 Generating query ✅
+Generated query: {
+  "fasta_files": {
+    "file": ">A|protein|\nQLEDSEVEAVAKGLEEMYANGVTEDNFKNYVKNNFAQQEISSVEEELNVNISDSCVANKIKDEFFAMISISAIVKAAQKKAWKELAVTVLRFAKANGLKTNAIIVAGQLALWAVQCG\n"
+  },
+  "use_msa_server": false,
+  "use_templates_server": false,
+  "num_trunk_recycles": 3,
+  "seed": 0,
+  "num_diffn_timesteps": 200,
+  "restraints": null,
+  "recycle_msa_subsample": 0,
+  "num_trunk_samples": 1
+}
+🧠 Processing folding job ✅
+```

folding-studio/docs/docs/how-to-guides/af3/single_job_from_protein_sequence.md

@@ -0,0 +1,32 @@
+## Goal
+**Boltz-1**, **Chai-1** and **Protenix** models allow passing the protein sequence directly as input.
+This makes the prediction jobs easier to integrate with your code.
+
+## Application
+=== ":material-language-python: Python"
+
+    ```python
+    from folding_studio.client import Client
+    from folding_studio.query.boltz import BoltzQuery
+
+    inference_parameters = {"project_code": "your-project-code",
+                            "seed":42}
+
+    sequence = ">A|protein\nQLEDSEVEAVAKGLEEMYANGVTEDNFKNYVKNNFAQQEISSVEEELNVNIS"
+
+    # Create client
+    client = Client.authenticate()
+
+    # Define query
+    query = BoltzQuery.from_protein_sequence(sequence=sequence, parameters=inference_parameters)
+
+    # Send request
+    response = client.send_request(query)
+
+    # Download results
+    output_path = out_dir / "output.zip"
+    response.download_results(output_path, force=True, unzip=True)
+    ```
+
+!!! Note
+    Depending on the model you want to use, you can replace `BoltzQuery` with `ChaiQuery` or `ProtenixQuery`.

folding-studio/docs/docs/how-to-guides/af3/single_job_protenix.md

@@ -0,0 +1,65 @@
+## Goal
+
+**Protenix** is one of the AlphaFold3-like models supported by Folding Studio. Here is a how-to guide to learn how to launch a simple single folding job on a FASTA file using **Protenix**.
+
+## Application
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding predict protenix path/to/my/file.fasta --output ./ --unzip --project-code "your-project-code"
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from folding_studio.client import Client
+    from folding_studio.query.protenix import ProtenixQuery
+
+    inference_parameters = {"project_code": "your-project-code"}
+
+    file_path = "path/to/my/file.fasta"
+
+    # Create client
+    client = Client.authenticate()
+
+    # Define query
+    query = ProtenixQuery.from_file(path=file_path, parameters=inference_parameters)
+
+    # Send request
+    response = client.send_request(query)
+
+    # Download results
+    output_path = "./output.zip"
+    response.download_results(output_path, force=True, unzip=True)
+    ```
+
+!!! note
+    Protenix also accepts RCSB FASTA format following this structure. The number of chains will automatically be derived from the description (e.g. 2 chains in the example below):
+    ``` { .shell .no-copy }
+    >1HSG_1|Chains A, B|HIV-1 PROTEASE|Human immunodeficiency virus 1 (11676)
+    PQITLWQRPLVTIKIGGQLKEALLDTGADDTVLEEMSLPGRWKPKMIGGIGGFIKVRQYDQILIEICGHKAIGTVLVGPTPVNIIGRNLLTQIGCTLNF
+    ```
+
+!!! warning
+    In this preview version, Protenix is only compatible with MSA search mode (`--use-msa-server`) and is enabled by default.
+
+Using the CLI, you will get the following information if the job was successfully submitted.
+
+``` { .shell .no-copy }
+╭─────────────────────────────────╮
+│ 🧬 Protenix Folding submission  │
+╰─────────────────────────────────╯
+🔑 Authenticating client ✅
+📦 Generating query ✅
+Generated query: {
+  "fasta_files": {
+    "file":
+">A|protein\nMASWSHPQFEKGGTHVAETSAPTRSEPDTRVLTLPGTASAPEFRLIDIDGLLNNRATTDV\nRDLGSGRLNAWGNSFPAAELPAPGSLITVAGIPFTWANAHAR>GDNIRCEGQVVDIPPGQY\nDWIYLLAASERRSEDTIWAHYDDGHADPLRVGISDFLDGTPAFGELSAFRTSR
+MHYPHHV\nQEGLPTTMWLTRVGMPRHGVARSLRLPRSVAMHVFALTLRTAAAVRLAEGATT\n"
+  },
+  "use_msa_server": true,
+  "seeds": "0"
+}
+🧠 Processing folding job ✅
+```

folding-studio/docs/docs/how-to-guides/index.md

@@ -0,0 +1,54 @@
+# How-to guides
+
+The **How-to guides section** provides step-by-step instructions for using Folding Studio efficiently. You will find step-by-step guides for various workflows, from setting up and submitting folding jobs to analyzing the results.
+
+## AlphaFold2/OpenFold
+
+Learn how to work with **AlphaFold2/OpenFold** models in Folding Studio:
+
+- [Provide Input Data](./af2_openfold/provide_input_data.md): Understand what data you can use for folding tasks.
+- [Launch a Folding Job using AlphaFold2](./af2_openfold/single_af2_job.md): Instructions to launch a folding job with the AlphaFold2 model.
+- [Launch a Folding Job using OpenFold](./af2_openfold/single_openfold_job.md): Instructions to launch a folding job with the OpenFold model.
+- [Set Folding Parameters](./af2_openfold/set_af_folding_parameters.md): Discover how to configure custom folding parameters for your jobs.
+- Launch a Batch Folding Job: Learn how to submit batch jobs [from configuration files](./af2_openfold/batch_job_from_configuration_file.md) or [directories](./af2_openfold/batch_job_from_directory.md) containing multiple fasta files.
+- [Check Job Status](./af2_openfold/fetch_folding_job_status.md): Instructions on how to fetch the status of your folding job.
+- [Download Job Logs](./af2_openfold/download_logs.md): Instructions on how to download the logs of your folding job.
+- [Cancel a Job Submission](./af2_openfold/cancel_experiment.md): Learn how to cancel a folding job that is in progress.
+- [Retrieve Features](./af2_openfold/get_experiment_features.md): Discover how to extract features generated by your folding jobs, such as structural metrics.
+- [Download Results](./af2_openfold/download_prediction_results.md): Learn how to download the results from completed folding jobs.
+- Launch Jobs using advanced algorithms:
+    - [Launch a Folding Job using MSA subsampling](./af2_openfold/advanced_algorithms/msa_subsampling_job.md): Learn how to use MSA subsampling to optimize sequence alignments for structure prediction.
+    - [Launch a Folding Job using the Gap Trick for Folding Multimer Complexes](./af2_openfold/advanced_algorithms/gap_trick_job.md): Discover how to fold multimer complexes using monomer models with the Gap Trick approach.
+    - [Launch a Folding Job using an Initial Guess Structure in AlphaFold2](./af2_openfold/advanced_algorithms/initial_guess_af2.md): Learn how to provide an initial structure guess to guide the AlphaFold2 folding process.
+    - [Launch a Folding Job applying Template Masking in Gap Trick Mode](./af2_openfold/advanced_algorithms/template_masking_job.md): Learn how to mask template regions to refine multimer folding while using Gap Trick mode.
+- [Launch a Folding Job using SoloSeq](./af2_openfold/soloseq_job.md): Discover how to run a folding job with the **SoloSeq** model, an OpenFold-like model.
+
+
+## Preview - AlphaFold3-like Models
+
+For advanced folding tasks, Folding Studio supports models similar to **AlphaFold3**:
+
+- [Provide Input Data](./af3/provide_input_data.md): Understand what data you can use for AlphaFold3-like jobs.
+- [Launch a Single Job using Boltz-1](./af3/single_job_boltz.md): Instructions for running a single folding job from a FASTA file using Boltz-1 model.
+- [Launch a Single Job using Chai-1](./af3/single_job_chai.md): Instructions for running a single folding job from a FASTA file using Chai-1 model.
+- [Launch a Single Job using Protenix](./af3/single_job_protenix.md): Instructions for running a single folding job from a FASTA file using Protenix model.
+- [Launch a Single Job from a YAML File using Boltz-1](./af3/boltz_single_yaml_job.md): Instructions for running a single folding job from a YAML file using Boltz-1 model.
+- [Launch a Batch Job from a Directory](./af3/batch_job_from_directory.md): Learn how to submit a batch job by organizing your fasta files in a directory.
+- [Launch a Job from a Protein Sequence](./af3/single_job_from_protein_sequence.md): Step-by-step guide to running a job directly from a protein sequence.
+
+## Post-processing
+
+Once your folding or alignment jobs are complete, you can perform post-processing tasks:
+
+- [Calculate Interface pLDDT and pAE](./other/pLDDT_pAE_calculation.md): Learn how to calculate pLDDT and pAE to assess protein model quality.
+
+## Multiple Sequence Alignment (MSA)
+
+Folding Studio also supports performing MSA searches:
+
+- [Provide Input Data for MSA](./msa_search/provide_input_data.md): Understand what data you can use for MSA search tasks.
+- [Launch an MSA Search with MMSeqs2](./msa_search/msa_search_mmseqs2.md): Step-by-step guide to running an MSA search.
+- [Launch an MSA Search ignoring cache](./msa_search/msa_no_cache.md): Learn how to run an MSA search while bypassing previously cached results.
+- [Check MSA Job Status](./msa_search/fetch_msa_job_status.md): Discover how to check the status of your MSA job.
+- [Download MSA Job Logs](./msa_search/download_msa_logs.md): Instructions on how to download the logs of your MSA job.
+- [Download MSA Results](./msa_search/download_msa_search_results.md): Learn how to download the results of an MSA search.

folding-studio/docs/docs/how-to-guides/msa_search/download_msa_logs.md

@@ -0,0 +1,19 @@
+## Goal
+This How-to guide explains how to download the logs of an MSA experiment.
+
+## Application
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding msa experiment logs b21b09a6a43dcfb282bdc00ec79bd7ae06de97b9 --output ./msa_logs_exp_b21b09.zip
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from pathlib import Path
+    from folding_studio.commands.msa import logs
+
+    logs(msa_exp_id="b21b09a6a43dcfb282bdc00ec79bd7ae06de97b9", output=Path("./msa_logs_exp_b21b09.zip"))
+    ```

folding-studio/docs/docs/how-to-guides/msa_search/download_msa_search_results.md

@@ -0,0 +1,53 @@
+## Goal
+
+The MSA search results will comprise:
+
+- The [Multiple Sequence Alignment](https://en.wikipedia.org/wiki/Multiple_sequence_alignment) (MSA) search results. By default, the Folding Studio pipeline will trigger an MSA search on Uniref90, small BFD, Mgnify and Uniprot (multimer jobs only) using the `jackhmmer` algorithm.
+- The msa coverage file.
+
+Once the MSA search job has finished, all the generated features are saved into a zip file.
+
+The zip file contains :
+
+- The output of the MSA search: the MSA search results on multiple databases in `.a3m` format.
+- The output of the template search : the four best matching templates in `.cif` format.
+
+Here is an example of the zip file structure for a monomer :
+
+``` { .shell .no-copy }
+extracted_experiment_features_zip
+├── msas
+│   ├── mgnify_hits.a3m
+│   ├── pdb_hits.hhr
+│   ├── small_bfd_hits.a3m
+│   └── uniref90_hits.a3m
+└── msa_coverage.json
+└── logs.txt
+
+```
+
+For multimer, the structure is similar except that there is a dedicated subdirectory for each protein.
+
+## Application
+
+You can download the zip file above to check the generated features by running this command.
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding msa experiment features b21b09a6a43dcfb282bdc00ec79bd7ae06de97b9 --output ./msa_features_exp_b21b09.zip
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from pathlib import Path
+    from folding_studio.commands.msa import features
+
+    features(msa_exp_id="b21b09a6a43dcfb282bdc00ec79bd7ae06de97b9", output=Path("./msa_features_exp_b21b09.zip"))
+    ```
+Once the MSA features are downloaded, you will get the following message:
+
+``` { .shell .no-copy }
+File downloaded successfully to msa_features_exp_b21b09.zip.
+```

folding-studio/docs/docs/how-to-guides/msa_search/fetch_msa_job_status.md

@@ -0,0 +1,60 @@
+## Goal
+This how-to guide explains how to manage MSA search jobs using the `msa_experiment_id`. Each submission creates a unique experiment, enabling caching and avoiding redundant computations.
+
+## Application
+
+### Fetch a search job `msa_experiment_id`
+Submitting an MSA search job creates an experiment. This allows caching and avoid
+useless re-computation of previously submitted MSA search job.
+
+Each experiment is associated with a unique `msa_experiment_id`. Its generation is
+deterministic, created from the submitted FASTA sequence (without taking into
+account the description) and the job parameters.
+
+By default, if you resubmit an MSA experiment with the same sequence and parameters, it will not be triggered and the response will inform you of the status of the original MSA experiment and its results, if any available. This can be overridden in the options (see [Launch an MSA search ignoring cache](./msa_no_cache.md)).
+
+Once your MSA job has been submitted, and thus the msa experiment created, you
+can get various information from the `msa_experiment_id`.
+
+You can get the list of your msa experiment ids that succeeded or are still pending
+using :
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding msa experiment list
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from folding_studio.commands.msa import list
+
+    list()
+    ```
+
+### Retrieve a search job status
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding msa experiment status b21b09a6a43dcfb282bdc00ec79bd7ae06de97b9
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from pathlib import Path
+    from folding_studio.commands.msa import status
+
+    status(msa_exp_id="b21b09a6a43dcfb282bdc00ec79bd7ae06de97b9")
+    ```
+
+The experiment status is the current state of the experiment.
+
+| VALUE       | DESCRIPTION                                                                     |
+| ----------- | ------------------------------------------------------------------------------- |
+| `Done`      | The experiment is done and its features and results are available for download. |
+| `Pending`   | The experiment is still ongoing.                                                |
+| `Failed`    | The experiment has failed.                                                      |
+| `Cancelled` | The experiment was cancelled.

folding-studio/docs/docs/how-to-guides/msa_search/msa_no_cache.md

@@ -0,0 +1,19 @@
+## Goal
+This tutorial guides you through running an MSA (Multiple Sequence Alignment) search ...
+
+## Application
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding msa search path/to/my/file.fasta --no-cache
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from pathlib import Path
+    from folding_studio.commands.msa import search
+
+    search(source=Path("path/to/my/file.fasta"), cache=False)
+    ```

folding-studio/docs/docs/how-to-guides/msa_search/msa_search_mmseqs2.md

@@ -0,0 +1,29 @@
+## Goal
+This tutorial guides you through running an MSA (Multiple Sequence Alignment) search using MMseqs2 instead of JackHMMer, which is the default method when no specific option is provided in the command.
+
+## Application
+You can choose between two MSA search mode :
+
+| Value                | Description                                                                                  |
+| -------------------- | -------------------------------------------------------------------------------------------- |
+| `"search"` (default) | automated search of Uniref90, small_bfd and MGnfy databases using `JackHMMer`                |
+| `"mmseqs"`           | automated search of Uniref30 and Colabfold_env_db using the **self-hosted** `MMSeqs2` server |
+
+
+!!! note
+    `MMSeqs2` produce fairly different MSA results compared to JackHMMer, they use different datasets (Uniref30 and colbafold_env_db) and different search algorithms. However the MSA produced by `MMSeqs2` is generally more diverse and can be leverage predict structures with higher accuracy (see this [publication](https://www.nature.com/articles/s41592-023-02130-4)). For more information about MMSeqs2, please refer to the corresponding [paper](https://www.biorxiv.org/content/10.1101/079681v5).
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding msa search path/to/my/file.fasta --msa-mode mmseqs
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from pathlib import Path
+    from folding_studio.commands.msa import search
+
+    search(source=Path("path/to/my/file.fasta"), msa_mode="mmseqs")
+    ```

folding-studio/docs/docs/how-to-guides/msa_search/provide_input_data.md

@@ -0,0 +1,32 @@
+## Goal
+This guide will help you determine whether a given input sequence is compatible for launching an MSA search.
+
+## Supported inputs
+
+To submit an MSA search job, you need the sequence input file in
+[`FASTA`](https://en.wikipedia.org/wiki/FASTA_format) format containing your
+protein sequence.
+
+It can be a monomer or a multimer sequence.
+
+=== "monomer"
+
+    ```text
+    >SARS-CoV-2|RBD|Omicron variant
+    RVQPTESIVRFPNITNLCPFDEVFNATRFASVYAWNRKRISNCVADYSVLYNLAPFFTFK
+    CYGVSPTKLNDLCFTNVYADSFVIRGDEVRQIAPGQTGNIADYNYKLPDDFTGCVIAWNS
+    NKLDSKVSGNYNYLYRLFRKSNLKPFERDISTEIYQAGNKPCNGVAGFNCYFPLRSYSFR
+    PTYGVGHQPYRVVVLSFELLHAPATVCGPKKSTNLVKNKCVNF
+    ```
+
+=== "multimer"
+
+    ```text
+    >SARS-CoV-2|RBD|Omicron variant
+    RVQPTESIVRFPNITNLCPFDEVFNATRFASVYAWNRKRISNCVADYSVLYNLAPFFTFK
+    CYGVSPTKLNDLCFTNVYADSFVIRGDEVRQIAPGQTGNIADYNYKLPDDFTGCVIAWNS
+    NKLDSKVSGNYNYLYRLFRKSNLKPFERDISTEIYQAGNKPCNGVAGFNCYFPLRSYSFR
+    PTYGVGHQPYRVVVLSFELLHAPATVCGPKKSTNLVKNKCVNF
+    >Processed angiotensin-converting enzyme 2|Homo sapiens (9606)
+    STIEEQAKTFLDKFNHEAEDLFYQSSLASWNYNTNITEENVQNMNNAGDKWSAFLKEQSTLAQMYPLQEIQNLTVKLQLQALQQNGSSVLSEDKSKRLNTILNTMSTIYSTGKVCNPDNPQECLLLEPGLNEIMANSLDYNERLWAWESWRSEVGKQLRPLYEEYVVLKNEMARANHYEDYGDYWRGDYEVNGVDGYDYSRGQLIEDVEHTFEEIKPLYEHLHAYVRAKLMNAYPSYISPIGCLPAHLLGDMWGRFWTNLYSLTVPFGQKPNIDVTDAMVDQAWDAQRIFKEAEKFFVSVGLPNMTQGFWENSMLTDPGNVQKAVCHPTAWDLGKGDFRILMCTKVTMDDFLTAHHEMGHIQYDMAYAAQPFLLRNGANEGFHEAVGEIMSLSAATPKHLKSIGLLSPDFQEDNETEINFLLKQALTIVGTLPFTYMLEKWRWMVFKGEIPKDQWMKKWWEMKREIVGVVEPVPHDETYCDPASLFHVSNDYSFIRYYTRTLYQFQFQEALCQAAKHEGPLHKCDISNSTEAGQKLFNMLRLGKSEPWTLALENVVGAKNMNVRPLLNYFEPLFTWLKDQNKNSFVGWSTDWSPYADRHHHHHH
+    ```

folding-studio/docs/docs/how-to-guides/other/pLDDT_pAE_calculation.md

@@ -0,0 +1,178 @@
+Here we propose recipes to compute interface PLDDT (ipLDDT) and interface PAE (iPAE). The value of these metrics depend on the **chosen** definition of interface residues.
+
+These scripts will use `bioblocks`, you can follow this [link](https://instadeep.gitlab.io/bioai-group/BioBlocks/setup/setup.html) to get detailed steps for installation, you will also need this specific [dependency](https://instadeep.gitlab.io/bioai-group/BioBlocks/setup/setup.html#manual-msms-installation). We use the `get_interface_residues` function to define the interface residues. Please refer to the [`bioblocks` documentation page](https://instadeep.gitlab.io/bioai-group/BioBlocks/api/generated/bioblocks.geometry.get_interface_residues.html#bioblocks-geometry-get-interface-residues) for more details on the input parameters.
+
+### ipLDDT
+
+To calculate the ipLDDT, make sure you downloaded the results of the experiment in question. You will need the metrics file path as well as the prediction path.
+
+1. Download your desired experiments results by running:
+
+```bash
+folding experiment results 6fdb36d380c3f9ba49137af47cf2eed5a6774cab --output result_exp_6fdb3.zip
+unzip result_exp_6fdb3.zip
+```
+
+2. Download the code snippet below into a Python file.
+3. Select a model prediction and edit in the file both `model_name` and `prediction_path`.
+4. Edit the `metrics_file_path` with the metrics `metrics_per_model.json` file path.
+5. Run your Python file.
+
+```python
+import numpy as np
+import json
+from bioblocks.io import read_model
+from bioblocks.geometry import get_interface_residues
+
+def calculate_mean_plddt_all_interfaces(
+    prediction_path: str, model_name: str, metrics_path: str
+) -> float:
+    """
+    Calculate the mean pLDDT for the interface residues between all chain pairs in the model.
+
+    Args:
+        prediction_path: Path to the prediction PDB file.
+        model_name: Name of the model.
+        metrics_path: Path to the JSON file containing pLDDT scores.
+
+    Returns:
+        float: The mean pLDDT score for the interface residues across all chain pairs.
+    """
+    pred = read_model(prediction_path)
+    chains = list(pred.get_chains())
+
+    with open(metrics_path, "r") as f:
+        metrics = json.load(f)
+
+    plddt = np.array(metrics[model_name]["plddt"])
+
+    # Create the offset list
+    offset = [0]
+    for i in range(len(chains) - 1):
+        offset.append(offset[-1] + len(list(chains[i].get_residues())))
+
+    all_interface_indices = []
+
+    # Iterate over all pairs of chains to calculate the interface residues
+    for i in range(len(chains)):
+        chain_a = chains[i]
+        for j in range(i + 1, len(chains)):
+            chain_b = chains[j]
+            residues = get_interface_residues(chain_a, chain_b)
+            interface_indexes_a = [
+                res.id.residue_index - 1 + offset[i] for res in residues[0]
+            ]
+            interface_indexes_b = [
+                res.id.residue_index - 1 + offset[j] for res in residues[1]
+            ]
+            all_interface_indices.extend(interface_indexes_a + interface_indexes_b)
+
+    all_interface_indices = np.unique(np.array(all_interface_indices))
+    mean_plddt = np.mean(plddt[all_interface_indices])
+
+    return mean_plddt
+
+if __name__ == "__main__":
+
+    prediction_path = "/PATH/TO/YOUR/PREDICTION/PDB/FILE"
+    metrics_file_path = "/PATH/TO/YOUR/PREDICTION/METRICS/JSON/FILE"
+    model_name = "model_1_multimer_v3"
+
+    iplddt = calculate_mean_plddt_all_interfaces(prediction_path, model_name, metrics_file_path)
+    print(f"Mean Interface PLDDT across all chain pairs: {iplddt}")
+
+```
+
+### ipAE
+
+To calculate the ipAE, make sure you downloaded the results of the experiment in question. You will need the metrics file path as well as the prediction path.
+
+1. Download your desired experiments results by running:
+
+```bash
+folding experiment results 6fdb36d380c3f9ba49137af47cf2eed5a6774cab --output result_exp_6fdb3.zip
+unzip result_exp_6fdb3.zip
+```
+
+2. Download the code snippet below into a Python file.
+3. Select a model prediction and edit in the file both `model_name` and `prediction_path`.
+4. Edit the `metrics_file_path` with the metrics `metrics_per_model.json` file path.
+5. Run your Python file.
+
+```python
+
+import numpy as np
+import json
+from bioblocks.io import read_model
+from bioblocks.geometry import get_interface_residues
+
+
+def calculate_interface_pae_all_chains(
+    prediction_path: str, model_name: str, metrics_path: str
+) -> float:
+    """
+    Calculate the Interface PAE by averaging the PAE of cross-interface residue pairs between all chain pairs.
+
+    Args:
+        prediction_path: Path to the prediction PDB file.
+        model_name: Name of the model.
+        metrics_path: Path to the JSON file containing PAE matrix.
+
+    Returns:
+        float: The average Interface PAE score across all chain pairs.
+    """
+    pred = read_model(prediction_path)
+
+    chains = list(pred.get_chains())
+
+    with open(metrics_path, "r") as f:
+        metrics = json.load(f)
+
+    pae_matrix = np.array(metrics[model_name]["pae"])
+
+    # Create the offset list
+    offset = [0]
+    for i in range(len(chains) - 1):
+        offset.append(offset[-1] + len(list(chains[i].get_residues())))
+
+    interface_pae_values = []
+
+    for i in range(len(chains)):
+        chain_a = chains[i]
+        for j in range(i + 1, len(chains)):
+            chain_b = chains[j]
+
+            residues = get_interface_residues(chain_a, chain_b)
+            interface_indexes_a = [
+                res.id.residue_index - 1 + offset[i] for res in residues[0]
+            ]
+            interface_indexes_b = [
+                res.id.residue_index - 1 + offset[j] for res in residues[1]
+            ]
+
+            # Calculate PAE for cross-interface residue pairs
+            for idx_a in interface_indexes_a:
+                for idx_b in interface_indexes_b:
+                    interface_pae_values.append(pae_matrix[idx_a, idx_b])
+                    interface_pae_values.append(
+                        pae_matrix[idx_b, idx_a]
+                    )  # Pae is not symmetrical
+
+    # Calculate the average PAE for the cross-interface residue pairs
+    if interface_pae_values:
+        mean_pae = np.mean(interface_pae_values)
+    else:
+        mean_pae = 0.0
+
+    return mean_pae
+
+if __name__ == "__main__":
+
+    prediction_path = "/PATH/TO/YOUR/PREDICTION/PDB/FILE"
+    metrics_file_path = "/PATH/TO/YOUR/PREDICTION/METRICS/JSON/FILE"
+    model_name = "model_1_multimer_v3"
+
+    ipae = calculate_interface_pae_all_chains(prediction_path, model_name, metrics_file_path)
+    print(f"Mean Interface PAE across all chain pairs: {ipae}")
+
+```

folding-studio/docs/docs/index.md

@@ -0,0 +1,82 @@
+---
+title: "Folding Studio"
+---
+
+## Welcome to Folding Studio
+
+Folding Studio enables you to perform protein structure predictions within the Google Cloud Platform (GCP) environment. By leveraging GCP's robust and scalable cloud infrastructure, it allows for fast and high-throughput protein folding predictions.
+
+This documentation will guide you through interacting programmatically with the Folding Studio CLI and python library, helping you efficiently utilize our tools for protein structure prediction. After reading through this documentation, you will be equipped to set up and submit single and batch jobs by defining input and model parameters, monitor the status of your jobs and retrieve job results, including structure predictions and confidence metrics.
+
+Some of the key features of Folding Studio include:
+
+- Flexible input options: Support for a variety of input formats, including FASTA sequences, YAML files, and more.
+- Batch job submission: Submit multiple jobs simultaneously, streamlining the prediction process for large datasets.
+- Confidence metrics: Retrieve structure predictions along with confidence metrics (e.g., pLDDT, pAE) to assess model quality.
+- Generated features: Access important features like multiple sequence alignments (MSA), templates, and more.
+- Real-time job monitoring: Track job progress, status, and results with ease using the CLI and the python library.
+
+To install Folding Studio, simply follow the [Installation Tutorial](tutorials/installation.md).
+
+Folding Studio supports a range of structure prediction models, categorized into AlphaFold2-like and AlphaFold3-like architectures.
+
+- AlphaFold2-like models: This category includes **AlphaFold2**, **OpenFold**, and **SoloSeq**. AlphaFold2 and OpenFold operate asynchronously, allowing users to submit predictions and retrieve results later. SoloSeq follows a similar modeling approach but runs synchronously.
+
+- AlphaFold3-like models: This category includes **Boltz-1**, **Chai-1**, and **Protenix**. Unlike AlphaFold2 and OpenFold, all models in this category operate synchronously, returning results upon query completion. Users of the `folding-studio` Python library will notice a different interaction pattern when working with these models, as they do not require polling for job status or retrieving results in separate steps.
+
+See [supported models section](./explanation/supported_models.md) for more details about this subject.
+
+## Documentation overview
+
+This documentation is organized as follows:
+
+- **Tutorials**: Step-by-step guides to get you started with Folding Studio, including installation, job submissions, and MSA searches.
+- **How-to Guides**: Detailed instructions for using specific features, such as setting folding parameters or calculating pLDDT and pAE.
+- **Reference**: Comprehensive details on CLI commands, input flags, and the Python library.
+- **Explanation**: In-depth explanation of supported models and advanced algorithms.
+
+---
+
+<div class="grid cards" markdown>
+
+- :material-clock-fast:{ .lg .middle } **Tutorials**
+
+    ---
+
+    [:octicons-arrow-right-24: Install Folding Studio](./tutorials/installation.md)
+
+    [:octicons-arrow-right-24: Run AlphaFold2 on a protein sequence](./tutorials/single_folding_job_af2.md)
+
+    [:octicons-arrow-right-24: Perform a Multiple Sequence Alignment (MSA) search](./tutorials/msa_search.md)
+
+    [:octicons-arrow-right-24: Preview - Run folding jobs with AlphaFold3-like models](./tutorials/single_folding_job_af3.md)
+
+- :octicons-rocket-16:{ .lg .middle } **How-to Guides**
+
+    ---
+
+    [:octicons-arrow-right-24: Alphafold2 / Openfold guides](./how-to-guides/af2_openfold/provide_input_data.md)
+
+    [:octicons-arrow-right-24: Multiple Sequence Alignment Search (MSA) guides](./how-to-guides/msa_search/provide_input_data.md)
+
+    [:octicons-arrow-right-24: Preview - Alphafold3-like models guides](./how-to-guides/af3/provide_input_data.md)
+
+    [:octicons-arrow-right-24: Post-processing recipes](./how-to-guides/other/pLDDT_pAE_calculation.md)
+
+- :material-dna:{ .lg .middle } **Explanation**
+
+    ---
+
+    [:octicons-arrow-right-24: Supported models](./explanation/supported_models.md)
+
+    [:octicons-arrow-right-24: Advanced algorithms](./explanation/advanced_algorithms.md)
+
+- :octicons-book-16:{ .lg .middle } **Reference**
+
+    ---
+
+    [:octicons-arrow-right-24: CLI](./reference/cli.md)
+
+    [:octicons-arrow-right-24: Python Library](./reference/python_lib_docs.md)
+
+</div>

folding-studio/docs/docs/reference/cli.md

@@ -0,0 +1,435 @@
+## `experiment`
+### `experiment status`
+
+Get an experiment status.
+
+**Usage**:
+
+```console
+folding experiment status EXP_ID
+```
+
+**Arguments**:
+
+| ARGUMENT | DESCRIPTION | VALUE TYPE |
+| -------- | ----------- | ----------- |
+| EXP_ID | ID of the experiment. | str |
+
+### `experiment list`
+
+Get all your done and pending experiment ids. The IDs are provided in the order of submission, starting with the most recent.
+
+**Usage**:
+
+```console
+folding experiment list [OPTIONS]
+```
+
+**Options**:
+
+| OPTIONS | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| ------- | ----------- | ---------- | ------------- |
+| --limit | Max number of experiment to display in the terminal. | int | 100 |
+| --output | Path to the file where the job metadata returned by the server are written. | Path | No default |
+
+### `experiment features`
+
+Get an experiment features.
+
+**Usage**:
+
+```console
+folding experiment features [OPTIONS] EXP_ID
+```
+
+**Arguments**:
+
+| ARGUMENT | DESCRIPTION | VALUE TYPE |
+| -------- | ----------- | ----------- |
+| EXP_ID | ID of the experiment. | str |
+
+**Options**:
+
+| OPTIONS | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| ------- | ----------- | ---------- | ------------- |
+| --output | Local path to download the zip to. | Path | <exp_id>_features.zip |
+| --force / --no-force | Forces the download to overwrite any existing file with the same name in the specified location. | bool | --no-force |
+| --unzip / --no-unzip | Automatically unzip the file after its download. | bool | --no-unzip |
+
+### `experiment results`
+
+Get an experiment results.
+
+**Usage**:
+
+```console
+folding experiment results [OPTIONS] EXP_ID
+```
+
+**Arguments**:
+
+| ARGUMENT | DESCRIPTION | VALUE TYPE |
+| -------- | ----------- | ----------- |
+| EXP_ID | ID of the experiment. | str |
+
+**Options**:
+
+| OPTIONS | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| ------- | ----------- | ---------- | ------------- |
+| --output | Local path to download the zip to. | Path | <exp_id>_results.zip |
+| --force / --no-force | Forces the download to overwrite any existing file with the same name in the specified location. | bool | --no-force |
+| --unzip / --no-unzip | Automatically unzip the file after its download. | bool | --no-unzip |
+
+### `experiment cancel`
+
+Cancel experiments job executions.      You can pass one or more experiment id
+
+**Usage**:
+
+```console
+folding experiment cancel EXP_ID
+```
+
+**Arguments**:
+
+| ARGUMENT | DESCRIPTION | VALUE TYPE |
+| -------- | ----------- | ----------- |
+| EXP_ID | ID of the experiment. | List[str] |
+
+### `experiment logs`
+
+Get an experiment logs.
+
+**Usage**:
+
+```console
+folding experiment logs [OPTIONS] EXP_ID
+```
+
+**Arguments**:
+
+| ARGUMENT | DESCRIPTION | VALUE TYPE |
+| -------- | ----------- | ----------- |
+| EXP_ID | ID of the experiment. | str |
+
+**Options**:
+
+| OPTIONS | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| ------- | ----------- | ---------- | ------------- |
+| --output | Local path to download the logs to. | Path | <exp_id>_logs.txt |
+| --force / --no-force | Forces the download to overwrite any existing file with the same name in the specified location. | bool | --no-force |
+
+## `msa`
+### `msa search`
+
+Run an MSA tool. Read more at <https://int-bio-foldingstudio-gcp.nw.r.appspot.com/tutorials/msa_search/.>
+
+**Usage**:
+
+```console
+folding msa search [OPTIONS] SOURCE
+```
+
+**Arguments**:
+
+| ARGUMENT | DESCRIPTION | VALUE TYPE |
+| -------- | ----------- | ----------- |
+| SOURCE | Path to the input fasta file. | Path |
+
+**Options**:
+
+| OPTIONS | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| ------- | ----------- | ---------- | ------------- |
+| --project-code | Project code. If unknown, contact your PM or the Folding Studio team. | str | No default |
+| --cache / --no-cache | Use cached experiment results if any. | bool | --cache |
+| --msa-mode | Mode of the MSA features generation. | FeatureMode | search |
+| --metadata-file | Path to the file where the job metadata returned by the server are written. | Path | No default |
+
+### `msa experiment`
+#### `msa experiment status`
+
+Get an MSA experiment status.
+
+**Usage**:
+
+```console
+folding msa experiment status MSA_EXP_ID
+```
+
+**Arguments**:
+
+| ARGUMENT | DESCRIPTION | VALUE TYPE |
+| -------- | ----------- | ----------- |
+| MSA_EXP_ID | ID of the MSA experiment. | str |
+
+#### `msa experiment features`
+
+Get an experiment features.
+
+**Usage**:
+
+```console
+folding msa experiment features [OPTIONS] MSA_EXP_ID
+```
+
+**Arguments**:
+
+| ARGUMENT | DESCRIPTION | VALUE TYPE |
+| -------- | ----------- | ----------- |
+| MSA_EXP_ID | ID of the MSA experiment. | str |
+
+**Options**:
+
+| OPTIONS | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| ------- | ----------- | ---------- | ------------- |
+| --output | Local path to download the zip to. | Path | &lt;msa_exp_id&gt;_features.zip |
+| --force / --no-force | Forces the download to overwrite any existing file with the same name in the specified location. | bool | --no-force |
+| --unzip / --no-unzip | Automatically unzip the file after its download. | bool | --no-unzip |
+
+#### `msa experiment logs`
+
+Get an experiment logs.
+
+**Usage**:
+
+```console
+folding msa experiment logs [OPTIONS] MSA_EXP_ID
+```
+
+**Arguments**:
+
+| ARGUMENT | DESCRIPTION | VALUE TYPE |
+| -------- | ----------- | ----------- |
+| MSA_EXP_ID | ID of the MSA experiment. | str |
+
+**Options**:
+
+| OPTIONS | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| ------- | ----------- | ---------- | ------------- |
+| --output | Local path to download the logs to. | Path | &lt;exp_id&gt;_logs.txt |
+| --force / --no-force | Forces the download to overwrite any existing file with the same name in the specified location. | bool | --no-force |
+
+#### `msa experiment list`
+
+Get all your done and pending experiment ids. The IDs are provided in the order of submission, starting with the most recent.
+
+**Usage**:
+
+```console
+folding msa experiment list [OPTIONS]
+```
+
+**Options**:
+
+| OPTIONS | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| ------- | ----------- | ---------- | ------------- |
+| --limit | Max number of experiment to display in the terminal. | int | 100 |
+| --output | Path to the file where the job metadata returned by the server are written. | Path | No default |
+
+## `predict`
+### `predict af2`
+
+Asynchronous AF2 folding submission.      Read more at <https://int-bio-foldingstudio-gcp.nw.r.appspot.com/how-to-guides/af2_openfold/single_af2_job/.>      If the source is a CSV or JSON file describing a batch prediction request, all the other     options will be overlooked.
+
+**Usage**:
+
+```console
+folding predict af2 [OPTIONS] SOURCE
+```
+
+**Arguments**:
+
+| ARGUMENT | DESCRIPTION | VALUE TYPE |
+| -------- | ----------- | ----------- |
+| SOURCE | Path to the data source. Either a fasta file, a directory of fasta files or a csv/json file describing a batch prediction request. | Path |
+
+**Options**:
+
+| OPTIONS | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| ------- | ----------- | ---------- | ------------- |
+| --project-code | Project code. If unknown, contact your PM or the Folding Studio team. | str | No default |
+| --cache / --no-cache | Use cached experiment results if any. | bool | --cache |
+| --template-mode | Mode of the template features generation. | FeatureMode | search |
+| --custom-template | Path to a custom template or a directory of custom templates. To pass multiple inputs, simply repeat the flag (e.g. `--custom_template template_1.cif --custom_template template_2.cif`). | List[Path] | [] |
+| --custom-template-id | ID of a custom template. To pass multiple inputs, simply repeat the flag (e.g. `--custom_template_id template_ID_1 --custom_template_id template_ID_2`). | List[str] | [] |
+| --initial-guess-file | Path to an initial guess file. | Path | No default |
+| --templates-masks-file | Path to a templates masks file. | Path | No default |
+| --msa-mode | Mode of the MSA features generation. | FeatureMode | search |
+| --custom-msa | Path to a custom msa or a directory of custom msas. To pass multiple inputs, simply repeat the flag (e.g. `--custom_msa msa_1.sto --custom_msa msa_2.sto`). | List[Path] | [] |
+| --max-msa-clusters | Max number of MSA clusters to search. | int | -1 |
+| --max-extra-msa | Max extra non-clustered MSA representation to use as source. | int | -1 |
+| --gap-trick / --no-gap-trick | Activate gap trick, allowing to model complexes with monomer models. | bool | --no-gap-trick |
+| --num-recycle | Number of refinement iterations of the predicted structures. | int | 3 |
+| --model-subset | Subset of AF2 model ids to use, between 1 and 5 included. | List[int] | [] |
+| --random-seed | Random seed used during the MSA sampling. Different random seed values will introduce variations in the predictions. | int | 0 |
+| --num-seed | Number of random seeds to use. Creates a batch prediction. | int | No default |
+| --metadata-file | Path to the file where the job metadata returned by the server are written. | Path | No default |
+
+### `predict openfold`
+
+Asynchronous OpenFold folding submission.      Read more at <https://int-bio-foldingstudio-gcp.nw.r.appspot.com/how-to-guides/af2_openfold/single_openfold_job/.>      If the source is a CSV or JSON file describing a batch prediction request, all the other     options will be overlooked.
+
+**Usage**:
+
+```console
+folding predict openfold [OPTIONS] SOURCE
+```
+
+**Arguments**:
+
+| ARGUMENT | DESCRIPTION | VALUE TYPE |
+| -------- | ----------- | ----------- |
+| SOURCE | Path to the data source. Either a fasta file, a directory of fasta files or a csv/json file describing a batch prediction request. | Path |
+
+**Options**:
+
+| OPTIONS | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| ------- | ----------- | ---------- | ------------- |
+| --project-code | Project code. If unknown, contact your PM or the Folding Studio team. | str | No default |
+| --cache / --no-cache | Use cached experiment results if any. | bool | --cache |
+| --template-mode | Mode of the template features generation. | FeatureMode | search |
+| --custom-template | Path to a custom template or a directory of custom templates. To pass multiple inputs, simply repeat the flag (e.g. `--custom_template template_1.cif --custom_template template_2.cif`). | List[Path] | [] |
+| --custom-template-id | ID of a custom template. To pass multiple inputs, simply repeat the flag (e.g. `--custom_template_id template_ID_1 --custom_template_id template_ID_2`). | List[str] | [] |
+| --templates-masks-file | Path to a templates masks file. | Path | No default |
+| --msa-mode | Mode of the MSA features generation. | FeatureMode | search |
+| --custom-msa | Path to a custom msa or a directory of custom msas. To pass multiple inputs, simply repeat the flag (e.g. `--custom_msa msa_1.sto --custom_msa msa_2.sto`). | List[Path] | [] |
+| --max-msa-clusters | Max number of MSA clusters to search. | int | -1 |
+| --max-extra-msa | Max extra non-clustered MSA representation to use as source. | int | -1 |
+| --gap-trick / --no-gap-trick | Activate gap trick, allowing to model complexes with monomer models. | bool | --no-gap-trick |
+| --num-recycle | Number of refinement iterations of the predicted structures. | int | 3 |
+| --model-subset | Subset of AF2 model ids to use, between 1 and 5 included. | List[int] | [] |
+| --random-seed | Random seed used during the MSA sampling. Different random seed values will introduce variations in the predictions. | int | 0 |
+| --num-seed | Number of random seeds to use. Creates a batch prediction. | int | No default |
+| --metadata-file | Path to the file where the job metadata returned by the server are written. | Path | No default |
+
+### `predict boltz`
+
+Synchronous Boltz-1 folding submission.
+
+**Usage**:
+
+```console
+folding predict boltz [OPTIONS] SOURCE
+```
+
+**Arguments**:
+
+| ARGUMENT | DESCRIPTION | VALUE TYPE |
+| -------- | ----------- | ----------- |
+| SOURCE | Path to the data source. Either a FASTA file, a YAML file, or a directory containing FASTA and YAML files. | Path |
+
+**Options**:
+
+| OPTIONS | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| ------- | ----------- | ---------- | ------------- |
+| --project-code | Project code. If unknown, contact your PM or the Folding Studio team. | str | No default |
+| --parameters-json | Path to JSON file containing Boltz inference parameters. | Path | No default |
+| --recycling-steps | Number of recycling steps for prediction. | int | 3 |
+| --sampling-steps | Number of sampling steps for prediction. | int | 200 |
+| --diffusion-samples | Number of diffusion samples for prediction. | int | 1 |
+| --step-scale | Step size related to the temperature at which the diffusion process samples the distribution. | float | 1.638 |
+| --msa-pairing-strategy | Pairing strategy for MSA generation. | str | greedy |
+| --write-full-pae / --no-write-full-pae | Whether to save the full PAE matrix as a file. | bool | --no-write-full-pae |
+| --write-full-pde / --no-write-full-pde | Whether to save the full PDE matrix as a file. | bool | --no-write-full-pde |
+| --use-msa-server / --no-use-msa-server | Flag to use the MSA server for inference. | bool | --use-msa-server |
+| --msa-path | Path to the custom MSAs. It can be a .a3m or .aligned.pqt file, or a directory containing these files. | str | No default |
+| --seed | Seed for random number generation. | int | 0 |
+| --output | Local path to download the result zip and query parameters to. Default to 'boltz_results'. | Path | boltz_results |
+| --force / --no-force | Forces the download to overwrite any existing file with the same name in the specified location. | bool | --no-force |
+| --unzip / --no-unzip | Unzip the file after its download. | bool | --no-unzip |
+| --spinner / --no-spinner | Use live spinner in log output. | bool | --spinner |
+
+### `predict chai`
+
+Synchronous Chai-1 folding submission.
+
+**Usage**:
+
+```console
+folding predict chai [OPTIONS] SOURCE
+```
+
+**Arguments**:
+
+| ARGUMENT | DESCRIPTION | VALUE TYPE |
+| -------- | ----------- | ----------- |
+| SOURCE | Path to the data source. Either a fasta file, a directory of fasta files or a csv/json file describing a batch prediction request. | Path |
+
+**Options**:
+
+| OPTIONS | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| ------- | ----------- | ---------- | ------------- |
+| --project-code | Project code. If unknown, contact your PM or the Folding Studio team. | str | No default |
+| --use-msa-server / --no-use-msa-server | Flag to enable MSA features. MSA search is performed by InstaDeep's MMseqs2 server. | bool | --use-msa-server |
+| --use-templates-server / --no-use-templates-server | Flag to enable templates. Templates search is performed by InstaDeep's MMseqs2 server. | bool | --no-use-templates-server |
+| --num-trunk-recycles | Number of trunk recycles during inference. | int | 3 |
+| --seed | Random seed for inference. | int | 0 |
+| --num-diffn-timesteps | Number of diffusion timesteps to run. | int | 200 |
+| --restraints | Restraints information. | str | No default |
+| --recycle-msa-subsample | Subsample parameter for recycling MSA during inference. | int | 0 |
+| --num-trunk-samples | Number of trunk samples to generate during inference. | int | 1 |
+| --msa-path | Path to the custom MSAs. It can be a .a3m or .aligned.pqt file, or a directory containing these files. | str | No default |
+| --output | Local path to download the result zip and query parameters to. Default to 'chai_results'. | Path | chai_results |
+| --force / --no-force | Forces the download to overwrite any existing file with the same name in the specified location. | bool | --no-force |
+| --unzip / --no-unzip | Unzip the file after its download. | bool | --no-unzip |
+| --spinner / --no-spinner | Use live spinner in log output. | bool | --spinner |
+
+### `predict protenix`
+
+Synchronous Protenix folding submission.
+
+**Usage**:
+
+```console
+folding predict protenix [OPTIONS] SOURCE
+```
+
+**Arguments**:
+
+| ARGUMENT | DESCRIPTION | VALUE TYPE |
+| -------- | ----------- | ----------- |
+| SOURCE | Path to the data source. Either a fasta file, a directory of fasta filesdescribing a batch prediction request. | Path |
+
+**Options**:
+
+| OPTIONS | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| ------- | ----------- | ---------- | ------------- |
+| --project-code | Project code. If unknown, contact your PM or the Folding Studio team. | str | No default |
+| --use-msa-server / --no-use-msa-server | Flag to use the MSA server for inference. Forced to True. | bool | --use-msa-server |
+| --seed | Random seed. | int | 0 |
+| --cycle | Pairformer cycle number. | int | 10 |
+| --step | Number of steps for the diffusion process. | int | 200 |
+| --sample | Number of samples in each seed. | int | 5 |
+| --output | Local path to download the result zip and query parameters to. Default to 'protenix_results'. | Path | protenix_results |
+| --force / --no-force | Forces the download to overwrite any existing file with the same name in the specified location. | bool | --no-force |
+| --unzip / --no-unzip | Unzip the file after its download. | bool | --no-unzip |
+| --spinner / --no-spinner | Use live spinner in log output. | bool | --spinner |
+
+### `predict soloseq`
+
+Synchronous SoloSeq folding submission
+
+**Usage**:
+
+```console
+folding predict soloseq [OPTIONS] SOURCE
+```
+
+**Arguments**:
+
+| ARGUMENT | DESCRIPTION | VALUE TYPE |
+| -------- | ----------- | ----------- |
+| SOURCE | Path to the data source. Either a fasta file or a directory of fasta files. | Path |
+
+**Options**:
+
+| OPTIONS | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| ------- | ----------- | ---------- | ------------- |
+| --project-code | Project code. If unknown, contact your PM or the Folding Studio team. | str | No default |
+| --seed | Random seed. | int | 0 |
+| --skip-relaxation / --no-skip-relaxation | Skip the relaxation process. | bool | --no-skip-relaxation |
+| --subtract-plddt / --no-subtract-plddt | Output (100 - pLDDT) instead of the pLDDT itself. | bool | --no-subtract-plddt |
+| --output | Local path to download the result zip and query parameters to. Default to 'soloseq_results'. | Path | soloseq_results |
+| --force / --no-force | Forces the download to overwrite any existing file with the same name in the specified location. | bool | --no-force |
+| --unzip / --no-unzip | Unzip the file after its download. | bool | --no-unzip |
+| --spinner / --no-spinner | Use live spinner in log output. | bool | --spinner |

folding-studio/docs/docs/reference/python_lib_docs.md

@@ -0,0 +1,719 @@
+# `folding-studio` Python Library
+
+This document provides an overview of the available functions and classes in `folding_studio`.
+
+## `get_id_token`
+
+**Signature:**
+```{ .python .no-copy }
+get_id_token() -> str
+```
+
+**Description:**
+
+Get the user's gcp token id.
+
+---
+
+## `single_job_prediction`
+
+**Signature:**
+```{ .python .no-copy }
+single_job_prediction(identity_token: str, fasta_file: pathlib.Path,
+parameters: folding_studio_data_models.parameters.alphafold.AF2Parameters | folding_studio_data_models.parameters.openfold.OpenFoldParameters | None = None,
+project_code: str | None = None, *, ignore_cache: bool = False, **kwargs) -> dict
+```
+
+**Description:**
+
+Make a single job prediction from folding parameters and a FASTA file.
+
+
+### Parameters:
+
+| PARAMETER | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| --------- | ----------- | ---------- | ------------- |
+| identity_token | GCP identity token | str | No default |
+| fasta_file | Input FASTA file | Path | No default |
+| parameters | Job parameters | AF2Parameters or OpenFoldParameters or None | None |
+| project_code | Project code under which the jobs are billed. If None, value is attempted to be read from environment. | str | None |
+| ignore_cache | Force the job submission or not | bool | False |
+
+---
+
+## `batch_prediction_from_file`
+
+**Signature:**
+```{ .python .no-copy }
+batch_prediction_from_file(identity_token: str, file: pathlib.Path, project_code: str | None = None) -> dict
+```
+
+**Description:**
+
+Make a batch prediction from a configuration files.
+
+### Parameters:
+
+| PARAMETER | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| --------- | ----------- | ---------- | ------------- |
+| identity_token | GCP identity token | str | No default |
+| file | Configuration file path | Path | No default |
+| project_code | Project code under which the jobs are billed. If None, value is attempted to be read from environment. | str | None |
+
+---
+
+## `af2`
+
+**Signature:**
+```{ .python .no-copy }
+af2(
+    source: Path,
+    project_code: str,
+    cache: bool = True,
+    template_mode: FeatureMode = FeatureMode.SEARCH,
+    custom_template: List[Path] = [],
+    custom_template_id: List[str] = [],
+    initial_guess_file: Optional[Path] = None,
+    templates_masks_file: Optional[Path] = None,
+    msa_mode: FeatureMode = FeatureMode.SEARCH,
+    custom_msa: List[Path] = [],
+    max_msa_clusters: int = -1,
+    max_extra_msa: int = -1,
+    gap_trick: bool = False,
+    num_recycle: int = 3,
+    model_subset: List[int] = [],
+    random_seed: int = 0,
+    num_seed: Optional[int] = None,
+    metadata_file: Optional[Path] = None,
+)
+```
+
+**Description:**
+
+Asynchronous AF2 folding submission. This command is used to submit a folding job to the AlphaFold2 model for protein structure prediction.
+If the `source` is a CSV or JSON file describing a batch prediction request, all the other options will be overlooked.
+
+### Parameters:
+
+| PARAMETER | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| ------- | ----------- | ---------- | ------------- |
+| source | Path to the data source. Either a fasta file, a directory of fasta files or a csv/json file describing a batch prediction request. | Path |
+| project_code | Project code. If unknown, contact your PM or the Folding Studio team. | str | |
+| cache | Use cached experiment results if any. | bool | True |
+| template_mode | Mode of the template features generation. | FeatureMode | FeatureMode.SEARCH |
+| custom_template | Path to a custom template or a directory of custom templates. | List[Path] | [] |
+| custom_template_id | ID of a custom template. | List[str] | [] |
+| initial_guess_file | Path to an initial guess file. | Path | No default |
+| templates_masks_file | Path to a templates masks file. | Path | No default |
+| msa_mode | Mode of the MSA features generation. | FeatureMode | FeatureMode.SEARCH |
+| custom_msa | Path to a custom msa or a directory of custom msas. | List[Path] | [] |
+| max_msa_clusters | Max number of MSA clusters to search. | int | -1 |
+| max_extra_msa | Max extra non-clustered MSA representation to use as source. | int | -1 |
+| gap_trick | Activate gap trick, allowing to model complexes with monomer models. | bool | False |
+| num_recycle | Number of refinement iterations of the predicted structures. | int | 3 |
+| model_subset | Subset of AF2 model ids to use, between 1 and 5 included. | List[int] | [] |
+| random_seed | Random seed used during the MSA sampling. Different random seed values will introduce variations in the predictions. | int | 0 |
+| num_seed | Number of random seeds to use. Creates a batch prediction. | int | No default |
+| metadata_file | Path to the file where the job metadata returned by the server are written. | Path | No default |
+
+---
+
+## `openfold`
+
+**Signature:**
+```{ .python .no-copy }
+openfold(
+    source: Path,
+    project_code: str,
+    cache: bool = True,
+    template_mode: FeatureMode = FeatureMode.SEARCH,
+    custom_template: List[Path] = [],
+    custom_template_id: List[str] = [],
+    templates_masks_file: Optional[Path] = None,
+    msa_mode: FeatureMode = FeatureMode.SEARCH,
+    custom_msa: List[Path] = [],
+    max_msa_clusters: int = -1,
+    max_extra_msa: int = -1,
+    gap_trick: bool = False,
+    num_recycle: int = 3,
+    model_subset: List[int] = [],
+    random_seed: int = 0,
+    num_seed: Optional[int] = None,
+    metadata_file: Optional[Path] = None,
+)
+```
+
+**Description:**
+
+Asynchronous OpenFold folding submission. This command is used to submit a folding job to the OpenFold model for protein structure prediction.
+
+If the source is a CSV or JSON file describing a batch prediction request, all the other options will be overlooked.
+
+### Parameters:
+
+| PARAMETER | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| ------- | ----------- | ---------- | ------------- |
+| source | Path to the data source. Either a fasta file, a directory of fasta files or a csv/json file describing a batch prediction request. | Path |
+| project_code | Project code. If unknown, contact your PM or the Folding Studio team. | str | No default |
+| cache | Use cached experiment results if any. | bool | True |
+| template_mode | Mode of the template features generation. | FeatureMode | FeatureMode.SEARCH |
+| custom_template | Path to a custom template or a directory of custom templates. | List[Path] | [] |
+| custom_template_id | ID of a custom template.  | List[str] | [] |
+| templates_masks_file | Path to a templates masks file. | Path | No default |
+| msa_mode | Mode of the MSA features generation. | FeatureMode | FeatureMode.SEARCH |
+| custom_msa | Path to a custom msa or a directory of custom msas.| List[Path] | [] |
+| max_msa_clusters | Max number of MSA clusters to search. | int | -1 |
+| max_extra_msa | Max extra non-clustered MSA representation to use as source. | int | -1 |
+| gap_trick | Activate gap trick, allowing to model complexes with monomer models. | bool | False |
+| num_recycle | Number of refinement iterations of the predicted structures. | int | 3 |
+| model_subset | Subset of AF2 model ids to use, between 1 and 5 included. | List[int] | [] |
+| random_seed | Random seed used during the MSA sampling. Different random seed values will introduce variations in the predictions. | int | 0 |
+| num_seed | Number of random seeds to use. Creates a batch prediction. | int | No default |
+| metadata_file | Path to the file where the job metadata returned by the server are written. | Path | No default |
+
+---
+
+## `list` (experiment)
+
+**Signature:**
+```{ .python .no-copy }
+list()
+```
+
+**Description:**
+
+Fetches a list of all completed and pending experiments.
+
+---
+
+## `status` (experiment)
+
+**Signature:**
+```{ .python .no-copy }
+status(
+    exp_id: str
+)
+```
+
+**Description:**
+
+Fetches the status of a specific experiment using its ID. The function makes a GET request to the server to retrieve the status of the experiment.
+
+### Parameters:
+
+| PARAMETER | DESCRIPTION | VALUE TYPE |
+| ------- | ----------- | ---------- |
+| exp_id | The experiment ID for which the status needs to be fetched | str |
+
+---
+
+## `cancel` (experiment)
+
+**Signature:**
+```{ .python .no-copy }
+cancel(
+    exp_id: List[str]
+)
+```
+
+**Description:**
+
+Cancels the execution of one or more experiment jobs by their IDs.
+
+### Parameters:
+
+| PARAMETER | DESCRIPTION | VALUE TYPE |
+| ------- | ----------- | ---------- |
+| exp_id | 	A list of experiment IDs to cancel | List[str] |
+
+---
+
+## `results` (experiment)
+
+**Signature:**
+```{ .python .no-copy }
+results(
+    exp_id: str,
+    output: Optional[Path] = None,
+    force: bool = False,
+    unzip: bool = False
+)
+```
+
+**Description:**
+
+Downloads the results of a specified experiment, given its experiment ID.
+
+### Parameters:
+
+| PARAMETER | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| ------- | ----------- | ---------- | ------------- |
+| exp_id | str | The experiment ID of the results to retrieve. |  |
+| output | Optional[Path] | The local path where the zip file will be downloaded. |  |
+| force | bool | Whether to overwrite an existing file at the specified location.| False |
+| unzip | bool | Whether to automatically unzip the downloaded file after the download completes.  | False |
+
+---
+
+## `features` (experiment)
+
+**Signature:**
+```{ .python .no-copy }
+features(
+    exp_id: str,
+    output: Optional[Path] = None,
+    force: bool = False,
+    unzip: bool = False
+)
+```
+
+**Description:**
+
+Downloads the features of a specified experiment, given its experiment ID.
+
+### Parameters:
+
+| PARAMETER | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| ------- | ----------- | ---------- | ------------- |
+| exp_id | str | The experiment ID of the results to retrieve. |  |
+| output | Optional[Path] | The local path where the zip file will be downloaded. |  |
+| force | bool | Whether to overwrite an existing file at the specified location.| False |
+| unzip | bool | Whether to automatically unzip the downloaded file after the download completes.  | False |
+
+
+---
+
+## `search` (multiple sequences alignment - msa)
+
+**Signature:**
+```{ .python .no-copy }
+search(
+    source: Path,
+    project_code: str,
+    cache: bool = True,
+    msa_mode: FeatureMode = FeatureMode.SEARCH,
+)
+
+```
+
+**Description:**
+
+Runs an MSA (Multiple Sequence Alignment).
+
+### Parameters:
+
+| PARAMETER | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| ------- | ----------- | ---------- | ------------- |
+| source | Path to the data source. Either a fasta file, a directory of fasta files or a csv/json file describing a batch prediction request. | Path |
+| project_code | Project code. If unknown, contact your PM or the Folding Studio team. | str | |
+| cache | Use cached experiment results if any. | bool | True |
+| msa_mode | Mode of the MSA features generation. | FeatureMode | FeatureMode.SEARCH |
+
+
+---
+
+## `list` (multiple sequences alignment - msa)
+
+**Signature:**
+```{ .python .no-copy }
+list()
+```
+
+**Description:**
+
+Fetches a list of all completed and pending experiments.
+
+---
+
+## `status` (multiple sequences alignment - msa)
+
+**Signature:**
+```{ .python .no-copy }
+status(
+    msa_exp_id: str
+)
+```
+
+**Description:**
+
+Fetches the status of a specific MSA experiment using its ID.
+
+### Parameters:
+
+| PARAMETER | DESCRIPTION | VALUE TYPE |
+| ------- | ----------- | ---------- |
+| ms_exp_id | The MSA experiment ID for which the status needs to be fetched | str |
+
+
+---
+
+## `features` (multiple sequences alignment - msa)
+
+**Signature:**
+```{ .python .no-copy }
+features(
+    msa_exp_id: str,
+    output: Optional[Path] = None,
+    force: bool = False,
+    unzip: bool = False
+)
+```
+
+**Description:**
+
+Fetches the features of a given MSA (Multiple Sequence Alignment) experiment.
+
+### Parameters:
+
+| PARAMETER | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| ------- | ----------- | ---------- | ------------- |
+| msa_exp_id | str | The MSA experiment ID of the results to retrieve. |  |
+| output | Optional[Path] | The local path where the zip file will be downloaded. |  |
+| force | bool | Whether to overwrite an existing file at the specified location.| False |
+| unzip | bool | Whether to automatically unzip the downloaded file after the download completes.  | False |
+
+
+---
+
+## `Client`
+
+**Signature:**
+```{ .python .no-copy }
+Client(api_key: 'str | None' = None, token_manager: 'TokenManager | None' = None) -> 'None'
+```
+
+**Description:**
+
+The `Client` class is used to send requests to a prediction endpoint. It supports authentication via an API key or a Google Cloud JWT token, and it handles sending queries, managing errors, and receiving responses.
+
+### Parameters:
+
+| PARAMETER | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| --------- | ----------- | ---------- | ------------- |
+| api_key | API key for authentication | str or None | None |
+| token_manager | JWT token manager | TokenManager or None | None |
+
+### Class methods:
+
+#### `from_api_key`
+Creates a Client instance using an API key.
+
+| PARAMETER | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| --------- | ----------- | ---------- | ------------- |
+| api_key | API key for authentication | str or None | None |
+
+#### `from_jwt`
+Creates a Client instance using a Google Cloud JWT token.
+
+
+### Instance methods:
+
+#### `send_request`
+Sends a prediction request to the server.
+
+| PARAMETER | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| --------- | ----------- | ---------- | ------------- |
+| query | A `Query` object containing the prediction data to send. | str or None | None |
+
+---
+
+## `SoloSeqQuery`
+
+**Description:**
+
+The `SoloSeqQuery` class is used to query the SoloSeq prediction API with FASTA data.
+
+### Class methods:
+
+#### `from_protein_sequence`
+Creates a `SoloSeqQuery` instance from a protein sequence given as a string.
+
+| PARAMETER | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| --------- | ----------- | ---------- | ------------- |
+| sequence | Input sequence to make prediction on. | str |  |
+| parameters | Prediction parameters.| SoloSeqParameters | Default values below. |
+
+with
+
+```{ .python .no-copy }
+class SoloSeqParameters(BaseModel):
+    """SoloSeq inference parameters."""
+
+    data_random_seed: int = Field(alias="seed", default=0)
+    skip_relaxation: bool = False
+    subtract_plddt: bool = False
+```
+
+#### `from_file`
+Creates a `SoloSeqQuery` instance from a FASTA file located at the given path.
+
+| PARAMETER | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| --------- | ----------- | ---------- | ------------- |
+| path | Path to the FASTA file. | str or Path |  |
+| parameters | Prediction parameters.| SoloSeqParameters | Default values below. |
+
+with
+
+```{ .python .no-copy }
+class SoloSeqParameters(BaseModel):
+    """SoloSeq inference parameters."""
+
+    data_random_seed: int = Field(alias="seed", default=0)
+    skip_relaxation: bool = False
+    subtract_plddt: bool = False
+```
+
+#### `from_directory`
+Creates a `SoloSeqQuery` instance from a directory containing multiple FASTA files.
+
+| PARAMETER | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| --------- | ----------- | ---------- | ------------- |
+| path |  Path to the directory containing FASTA files.| str or Path|  |
+| parameters | Prediction parameters.| SoloSeqParameters | Default values below. |
+
+with
+
+```{ .python .no-copy }
+class SoloSeqParameters(BaseModel):
+    """SoloSeq inference parameters."""
+
+    data_random_seed: int = Field(alias="seed", default=0)
+    skip_relaxation: bool = False
+    subtract_plddt: bool = False
+```
+
+---
+
+## `BoltzQuery`
+
+**Description:**
+
+The `BoltzQuery` class is used to query the Boltz-1 prediction API with FASTA data.
+
+### Class methods:
+
+#### `from_protein_sequence`
+Creates a `BoltzQuery` instance from a protein sequence given as a string.
+
+| PARAMETER | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| --------- | ----------- | ---------- | ------------- |
+| sequence | Input sequence to make prediction on. | str |  |
+| parameters | Prediction parameters.| BoltzParameters | Default values below. |
+
+with
+
+```{ .python .no-copy }
+class BoltzParameters(BaseModel):
+    """Boltz inference parameters."""
+
+    seed: int = 0
+    recycling_steps: int = 3
+    sampling_steps: int = 200
+    diffusion_samples: int = 1
+    step_scale: float = 1.638
+    msa_pairing_strategy: str = "greedy"
+    write_full_pae: bool = False
+    write_full_pde: bool = False
+    use_msa_server: bool = True
+```
+
+#### `from_file`
+Creates a `BoltzQuery` instance from a FASTA file or a YAML file located at the given path.
+
+| PARAMETER | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| --------- | ----------- | ---------- | ------------- |
+| path | Path to the FASTA or YAML file. | str or Path |  |
+| parameters | Prediction parameters.| BoltzParameters | Default values below. |
+
+with
+
+```{ .python .no-copy }
+class BoltzParameters(BaseModel):
+    """Boltz inference parameters."""
+
+    seed: int = 0
+    recycling_steps: int = 3
+    sampling_steps: int = 200
+    diffusion_samples: int = 1
+    step_scale: float = 1.638
+    msa_pairing_strategy: str = "greedy"
+    write_full_pae: bool = False
+    write_full_pde: bool = False
+    use_msa_server: bool = True
+```
+
+#### `from_directory`
+Creates a `BoltzQuery` instance from a directory containing multiple FASTA and/or YAML files.
+
+| PARAMETER | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| --------- | ----------- | ---------- | ------------- |
+| path |  Path to the directory containing FASTA and/or YAML files.| str or Path|  |
+| parameters | Prediction parameters.| BoltzParameters | Default values below. |
+
+with
+
+```{ .python .no-copy }
+class BoltzParameters(BaseModel):
+    """Boltz inference parameters."""
+
+    seed: int = 0
+    recycling_steps: int = 3
+    sampling_steps: int = 200
+    diffusion_samples: int = 1
+    step_scale: float = 1.638
+    msa_pairing_strategy: str = "greedy"
+    write_full_pae: bool = False
+    write_full_pde: bool = False
+    use_msa_server: bool = True
+```
+
+---
+
+## `ChaiQuery`
+
+**Description:**
+
+The `ChaiQuery` class is used to query the Chai-1 prediction API with FASTA data.
+
+### Class methods:
+
+#### `from_protein_sequence`
+Creates a `ChaiQuery` instance from a protein sequence given as a string.
+
+| PARAMETER | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| --------- | ----------- | ---------- | ------------- |
+| sequence | Input sequence to make prediction on. | str |  |
+| parameters | Prediction parameters.| ChaiParameters | Default values below. |
+
+with
+
+```{ .python .no-copy }
+class ChaiParameters(BaseModel):
+    """Chai inference parameters."""
+
+    seed: int = 0
+    num_trunk_recycles: int = 3
+    num_diffn_timesteps: int = 200
+    recycle_msa_subsample: int = 0
+    num_trunk_samples: int = 1
+    restraints: str | None = None
+    use_msa_server: bool = False
+    use_templates_server: bool = False
+    custom_msa_paths: dict[str, str] | None = None
+```
+
+#### `from_file`
+Creates a `ChaiQuery` instance from a FASTA file located at the given path.
+
+| PARAMETER | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| --------- | ----------- | ---------- | ------------- |
+| path | Path to the FASTA file. | str or Path |  |
+| parameters | Prediction parameters.| ChaiParameters | Default values below. |
+
+with
+
+```{ .python .no-copy }
+class ChaiParameters(BaseModel):
+    """Chai inference parameters."""
+
+    seed: int = 0
+    num_trunk_recycles: int = 3
+    num_diffn_timesteps: int = 200
+    recycle_msa_subsample: int = 0
+    num_trunk_samples: int = 1
+    restraints: str | None = None
+    use_msa_server: bool = False
+    use_templates_server: bool = False
+    custom_msa_paths: dict[str, str] | None = None
+```
+
+#### `from_directory`
+Creates a `ChaiQuery` instance from a directory containing multiple FASTA files.
+
+| PARAMETER | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| --------- | ----------- | ---------- | ------------- |
+| path |  Path to the directory containing FASTA files.| str or Path|  |
+| parameters | Prediction parameters.| ChaiParameters | Default values below. |
+
+with
+
+```{ .python .no-copy }
+class ChaiParameters(BaseModel):
+    """Chai inference parameters."""
+
+    seed: int = 0
+    num_trunk_recycles: int = 3
+    num_diffn_timesteps: int = 200
+    recycle_msa_subsample: int = 0
+    num_trunk_samples: int = 1
+    restraints: str | None = None
+    use_msa_server: bool = False
+    use_templates_server: bool = False
+    custom_msa_paths: dict[str, str] | None = None
+```
+
+---
+
+## `ProtenixQuery`
+
+**Description:**
+
+The `ProtenixQuery` class is used to query the Protenix prediction API with FASTA data.
+
+### Class methods:
+
+#### `from_protein_sequence`
+Creates a `ProtenixQuery` instance from a protein sequence given as a string.
+
+| PARAMETER | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| --------- | ----------- | ---------- | ------------- |
+| sequence | Input sequence to make prediction on. | str |  |
+| parameters | Prediction parameters.| ProtenixParameters | Default values below. |
+
+with
+
+```{ .python .no-copy }
+class ProtenixParameters(BaseModel):
+    """Protenix inference parameters."""
+
+    seeds: str = Field(alias="seed", default="0", coerce_numbers_to_str=True)
+    use_msa_server: bool = True
+```
+
+#### `from_file`
+Creates a `ProtenixQuery` instance from a FASTA file located at the given path.
+
+| PARAMETER | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| --------- | ----------- | ---------- | ------------- |
+| path | Path to the FASTA file. | str or Path |  |
+| parameters | Prediction parameters.| ProtenixParameters | Default values below. |
+
+with
+
+```{ .python .no-copy }
+class ProtenixParameters(BaseModel):
+    """Protenix inference parameters."""
+
+    seeds: str = Field(alias="seed", default="0", coerce_numbers_to_str=True)
+    use_msa_server: bool = True
+```
+
+#### `from_directory`
+Creates a `ProtenixQuery` instance from a directory containing multiple FASTA files.
+
+| PARAMETER | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |
+| --------- | ----------- | ---------- | ------------- |
+| path |  Path to the directory containing FASTA files.| str or Path|  |
+| parameters | Prediction parameters.| ProtenixParameters | Default values below. |
+
+with
+
+```{ .python .no-copy }
+class ProtenixParameters(BaseModel):
+    """Protenix inference parameters."""
+
+    seeds: str = Field(alias="seed", default="0", coerce_numbers_to_str=True)
+    use_msa_server: bool = True
+```
+
+---

folding-studio/docs/docs/tutorials/index.md

@@ -0,0 +1,9 @@
+# Tutorials
+The Tutorials section of the documentation provides step-by-step guides on installing and using Folding Studio for protein structure prediction.
+
+It is structured into the following subsections:
+
+1. [Install Folding Studio](./installation.md)
+1. [Make a single prediction using AlphaFold2](./single_folding_job_af2.md)
+1. [Perform a Multiple Sequence Alignment (MSA) search](./msa_search.md)
+1. [Preview - Run folding jobs with AlphaFold3-like models](./single_folding_job_af3.md)

folding-studio/docs/docs/tutorials/installation.md

@@ -0,0 +1,61 @@
+## Prerequisites
+
+1. Install the `gcloud` CLI following the official Google Cloud [instructions page](https://cloud.google.com/sdk/docs/install).
+1. Create and activate a virtual environment, for example `folding-pipeline`, using your favourite tool (conda, pyenv, venv, ...). **Only Python version `3.11` is supported**.
+1. It is recommended to make `gcloud` use the same Python interpreter as your virtual environment:
+
+    ```bash
+    # Use a Python you have installed in a special location
+    export CLOUDSDK_PYTHON=<path/to/python/interpreter>
+    ```
+
+1. Authenticate to `gcloud`:
+
+    ```bash
+    gcloud auth application-default login
+    ```
+
+1. To simplify the `gcloud` authentication process when you install a Python package from InstaDeep's Google Artifact Registry, install the `keyring.google-artifactregistry-auth` package in your virtual environment:
+
+    ```bash
+    pip install keyrings.google-artifactregistry-auth
+    ```
+
+    It automatically searches for credentials from the environment and authenticates to Artifact Registry. Otherwise, you will have to specify your GCP credentials during the package installation.
+
+1. Provide a project code
+To submit folding jobs, you need to provide a project code. Ensure that you use the project code that corresponds to your project or Statement of Work (SOW).
+
+    - Projects/SOW codes are communicated to PMs.
+    - The project code can be defined as an environment variable or passed as an argument
+    to the CLI
+
+    ```bash
+    export FOLDING_PROJECT_CODE=<your_project_code>
+    ```
+
+1. If you do not possess an InstaDeep account or you intend to use Folding Studio on a server or with a service account, you are able to authenticate using an API key.
+
+    - API keys are generated on demand, please contact the Folding Studio team.
+    - The API key must be defined as an environment variable.
+
+
+    ```bash
+    export FOLDING_API_KEY=<your_api_key>
+    ```
+
+## <a name="folding-cli-lib"></a> CLI and `folding_studio` library
+
+To install the CLI and `folding-studio` library of helper functions, simply use pip in your virtual environment:
+
+```bash
+pip install --extra-index-url https://europe-west4-python.pkg.dev/instadeep/folding-studio/simple folding-studio
+```
+
+This package will install both the CLI, available under the `folding` command, and the `folding_studio` suite of helper functions available in Python.
+
+## Troubleshooting
+
+### While installing the CLI I get prompted `User for http://europe-west4-python.pkg.dev/:`
+
+This message means that the `gcloud` credentials were not found. Please refer to steps 4 and 5 of [Prerequisites](#prerequisites).

folding-studio/docs/docs/tutorials/msa_search.md

@@ -0,0 +1,115 @@
+In this tutorial, we will guide you through the process of submitting an MSA (Multiple Sequence Alignment) search job using the command-line interface (CLI) . You will learn how to prepare your sequence input file and submit the job to retrieve the aligned sequences.
+
+An MSA search helps in finding similar sequences in biological databases, allowing you to analyze protein structures and relationships more effectively. We support two types of sequence submissions: monomer and multimer. The process automatically detects the sequence type, so you can focus on your analysis.
+
+## Input data
+To submit an MSA search job, you need a sequence input file in
+[`FASTA`](https://en.wikipedia.org/wiki/FASTA_format) format containing your
+protein sequence as well as the msa search method. You can use the following monomer.
+
+=== "monomer"
+
+    ```text
+    >SARS-CoV-2|RBD|Omicron variant
+    RVQPTESIVRFPNITNLCPFDEVFNATRFASVYAWNRKRISNCVADYSVLYNLAPFFTFK
+    CYGVSPTKLNDLCFTNVYADSFVIRGDEVRQIAPGQTGNIADYNYKLPDDFTGCVIAWNS
+    NKLDSKVSGNYNYLYRLFRKSNLKPFERDISTEIYQAGNKPCNGVAGFNCYFPLRSYSFR
+    PTYGVGHQPYRVVVLSFELLHAPATVCGPKKSTNLVKNKCVNF
+    ```
+
+## Submit a MSA search job
+You simply use the `msa` command of the CLI to submit your job.
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding msa search path/to/my/file.fasta --project-code "your-project-code"
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from folding_studio.commands.msa import search
+
+    search(source="path/to/my/file.fasta", project_code="your-project-code")
+    ```
+
+## Identify the `experiment_id` of your search job
+
+Your experiment is associated with a unique `experiment_id`.
+
+You get the list of your experiment ids that succeeded or are still pending
+using:
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding msa experiment list
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from folding_studio.commands.msa import list
+
+    list()
+    ```
+
+
+Once you have submitted a folding job, you can get its status at any time.
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding msa experiment status b21b09a6a43dcfb282bdc00ec79bd7ae06de97b9
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from folding_studio.commands.msa import status
+
+    status(msa_exp_id="b21b09a6a43dcfb282bdc00ec79bd7ae06de97b9")
+    ```
+
+The experiment status is the current state of the experiment.
+
+| VALUE       | DESCRIPTION                                                                     |
+| ----------- | ------------------------------------------------------------------------------- |
+| `Done`      | The experiment is done and its features and results are available for download. |
+| `Pending`   | The experiment is still ongoing.                                                |
+| `Failed`    | The experiment has failed.                                                      |
+| `Cancelled` | The experiment was cancelled.
+
+## Download Results
+
+You  download the search job results by running the following command.
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding msa experiment features b21b09a6a43dcfb282bdc00ec79bd7ae06de97b9 --output ./features_exp_b21b09.zip
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from pathlib import Path
+    from folding_studio.commands.msa import features
+
+    features(msa_exp_id="b21b09a6a43dcfb282bdc00ec79bd7ae06de97b9", output=Path("./features_exp_b21b09.zip"))
+    ```
+
+Here is an example of the zip file structure for a monomer :
+
+``` { .shell .no-copy }
+extracted_experiment_features_zip
+├── msas
+│   ├── mgnify_hits.a3m
+│   ├── pdb_hits.hhr
+│   ├── small_bfd_hits.a3m
+│   └── uniref90_hits.a3m
+└── msa_coverage.json
+└── logs.txt
+
+```

folding-studio/docs/docs/tutorials/single_folding_job_af2.md

@@ -0,0 +1,154 @@
+
+In this tutorial, you will learn how to run predictions using the AlphaFold2 model.
+Once the job is submitted, you can track its status, retrieve results, and access various metrics from the generated predictions. To gain a deeper understanding of the different inference parameters and how to fine-tune them for your needs, we recommend reviewing the [How-to guides in the AlphaFold2 and OpenFold section](./../how-to-guides/af2_openfold/provide_input_data.md) for detailed examples and usage tips.
+
+## Input data
+
+To submit a folding job, you need a sequence input file in
+[`FASTA`](https://en.wikipedia.org/wiki/FASTA_format) format containing your
+protein sequence. You can use the following monomer.
+
+=== "monomer"
+
+    ```text
+    >SARS-CoV-2|RBD|Omicron variant
+    RVQPTESIVRFPNITNLCPFDEVFNATRFASVYAWNRKRISNCVADYSVLYNLAPFFTFK
+    CYGVSPTKLNDLCFTNVYADSFVIRGDEVRQIAPGQTGNIADYNYKLPDDFTGCVIAWNS
+    NKLDSKVSGNYNYLYRLFRKSNLKPFERDISTEIYQAGNKPCNGVAGFNCYFPLRSYSFR
+    PTYGVGHQPYRVVVLSFELLHAPATVCGPKKSTNLVKNKCVNF
+    ```
+
+## Submit job
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding predict af2 path/to/my/file.fasta --project-code "your-project-code"
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from pathlib import Path
+    from folding_studio.commands.predict import af2 as af2_predict
+
+    af2_predict(source=Path("path/to/my/file.fasta"), project_code="your-project-code")
+    ```
+
+Using the CLI, you will get the following information once the job was successfully submitted.
+
+``` { .shell .no-copy }
+Single job successfully submitted.
+Experiment submitted successfully !
+The experiment id is b938c1adaec932e8a6ba765c80144492b6a3f1e6
+Prediction job metadata written to simple_prediction_20250305172707.json
+You can query your experiment status with the command:
+
+         folding experiment status b938c1adaec932e8a6ba765c80144492b6a3f1e6
+```
+
+For details about the inference parameters / flags for each model check the [reference section](../reference/cli.md#predict).
+
+## Identify the `experiment_id` of your job
+
+Your experiment is associated with a unique `experiment_id`.
+
+You get the list of the experiment ids that succeeded or are still pending
+using:
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding experiment list
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from folding_studio.commands.experiment import list
+
+    list()
+    ```
+
+You will get a table with the status of the job you just launched:
+
+``` { .shell .no-copy }
+Done and pending experiments list written to None
+            Done and pending experiments
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┓
+┃                            Experiment ID ┃ Status ┃
+┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━┩
+│ b21b09a6a43dcfb282bdc00ec79bd7ae06de97b9 │Pending │
+└──────────────────────────────────────────┴────────┘
+```
+
+## Get your job status
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding experiment status b21b09a6a43dcfb282bdc00ec79bd7ae06de97b9
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from folding_studio.commands.experiment import status
+
+    status(exp_id="b21b09a6a43dcfb282bdc00ec79bd7ae06de97b9")
+    ```
+
+The experiment status is the current state of the experiment.
+
+| VALUE       | DESCRIPTION                                                                     |
+| ----------- | ------------------------------------------------------------------------------- |
+| `Done`      | The experiment is done and its features and results are available for download. |
+| `Pending`   | The experiment is still ongoing.                                                |
+| `Failed`    | The experiment has failed.                                                      |
+| `Cancelled` | The experiment was cancelled.                                                   |
+
+## Download results
+
+After your experiment has finished, you download the results zip file.
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding experiment results b21b09a6a43dcfb282bdc00ec79bd7ae06de97b9 --output ./result_exp_b21b09.zip
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from pathlib import Path
+    from folding_studio.commands.experiment import results
+
+    results(exp_id="b21b09a6a43dcfb282bdc00ec79bd7ae06de97b9", output=Path("./result_exp_b21b09.zip"))
+    ```
+
+You will get the message:
+
+```bash
+File downloaded successfully to result_exp_b21b09.zip.
+```
+
+Here is an example of the zip file structure :
+
+``` { .shell .no-copy }
+results
+├── metrics_per_model.json
+├── msa_coverage.json
+├── relaxed_predictions
+│   ├── model_1_ptm.pdb
+│   ├── model_2_ptm.pdb
+│   ├── model_3_ptm.pdb
+│   ├── model_4_ptm.pdb
+│   └── model_5_ptm.pdb
+├── rmsd_per_model.json
+└── unrelaxed_predictions
+    ├── model_1_ptm.pdb
+    ├── model_2_ptm.pdb
+    ├── model_3_ptm.pdb
+    ├── model_4_ptm.pdb
+    └── model_5_ptm.pdb
+```

folding-studio/docs/docs/tutorials/single_folding_job_af3.md

@@ -0,0 +1,111 @@
+In this tutorial, you will learn how to run the **Boltz-1**, **Chai-1** and **Protenix** models, which are all AlphaFold3-like models. These models features differ slightly from AlphaFold2 and OpenFold models.
+To help you get started, we recommend exploring the other How-to guides in the AlphaFold3-like models section for more detailed examples and usage instructions tailored to each model.
+
+This tutorial focuses on using the Boltz-1 model.
+
+## Input data
+
+To submit a folding job, you need a sequence input file in
+[`FASTA`](https://en.wikipedia.org/wiki/FASTA_format) format containing your
+protein sequence. You can use the following monomer.
+
+=== "monomer"
+
+    ```text
+    >SARS-CoV-2|RBD|Omicron variant
+    RVQPTESIVRFPNITNLCPFDEVFNATRFASVYAWNRKRISNCVADYSVLYNLAPFFTFK
+    CYGVSPTKLNDLCFTNVYADSFVIRGDEVRQIAPGQTGNIADYNYKLPDDFTGCVIAWNS
+    NKLDSKVSGNYNYLYRLFRKSNLKPFERDISTEIYQAGNKPCNGVAGFNCYFPLRSYSFR
+    PTYGVGHQPYRVVVLSFELLHAPATVCGPKKSTNLVKNKCVNF
+    ```
+
+## Submit job and get results
+
+You use the `predict boltz` command of the CLI. You can then add the different inference parameters as flags. In particular, the `--output-path` flag allows you to specify the path of the zip file that will contain the results.
+
+For details about the inference parameters / flags for each model check the [reference section](../reference/cli.md#predict).
+
+=== ":octicons-command-palette-16: CLI"
+
+    ```bash
+    folding predict boltz path/to/my/file.fasta --project-code "your-project-code" --output-path ./output.zip --seed 42
+    ```
+
+=== ":material-language-python: Python"
+
+    ```python
+    from folding_studio.client import Client
+    from folding_studio.query.boltz import BoltzQuery
+
+    inference_parameters = {"project_code": "your-project-code",
+                            "seed":42}
+
+    file_path = "path/to/my/file.fasta"
+
+    # Create client
+    client = Client.from_jwt()
+
+    # Define query
+    query = BoltzQuery.from_file(path=file_path, parameters=inference_parameters)
+
+    # Send request
+    response = client.send_request(query)
+
+    # Download results
+    output_path = "./output.zip"
+    response.download_results(output_path, force=True, unzip=True)
+    ```
+
+Using the CLI, you will get the following information if the job was successfully submitted.
+
+``` { .shell .no-copy }
+╭───────────────────────────────╮
+│ 🧬 Boltz1 Folding submission  │
+╰───────────────────────────────╯
+🔑 Authenticating client ✅
+📦 Generating query ✅
+Generated query: {
+  "fasta_files": {
+    "file": ">A|protein|\nQLEDSEVEAVAKGLEEMYANGVTEDNFKNYVKNNFAQQEISSVEEELNVNISDSCVANKIKDEFFAMISISAIVKAAQKKAWKELAVTVLRFAKANGLKTNAIIVAGQLALWAVQCG"
+  },
+  "yaml_files": {},
+  "parameters": {
+    "seed": 42,
+    "recycling_steps": 3,
+    "sampling_steps": 200,
+    "diffusion_samples": 1,
+    "step_scale": 1.638,
+    "msa_pairing_strategy": "greedy",
+    "write_full_pae": false,
+    "write_full_pde": false
+  }
+}
+🧠 Processing folding job ✅
+```
+
+And you will get the following information once the job is completed and the results are downloaded.
+
+``` { .shell .no-copy }
+Confidence data: {
+  "prot_73bcabf6-54e5-4762-8745-97e6de0f9c22": {
+    "chains_ptm": {
+      "0": 0.7689766883850098
+    },
+    "complex_ipde": 0,
+    "complex_iplddt": 0,
+    "complex_pde": 0.8002958297729492,
+    "complex_plddt": 0.8243614435195923,
+    "confidence_score": 0.8132845163345337,
+    "iptm": 0,
+    "ligand_iptm": 0,
+    "pair_chains_iptm": {
+      "0": {
+        "0": 0.7689766883850098
+      }
+    },
+    "protein_iptm": 0,
+    "ptm": 0.7689766883850098
+  }
+}
+💾 Downloading results to `boltz_results` ✅
+```

folding-studio/docs/generate_cli_docs.py

@@ -0,0 +1,209 @@
+import re
+import types
+from typing import Union, get_args, get_origin, get_type_hints
+
+import typer
+from folding_studio.cli import app
+from typer.models import TyperInfo
+from typer.utils import get_params_from_function
+
+
+def extract_base_type(annotation):
+    """Extract annotation type.
+
+    Handles List[X], Optional[X] and Union[X, Y] cases.
+    """
+    origin = get_origin(annotation)
+
+    if origin is list:
+        inner_type = get_args(annotation)[0]
+        return (
+            f"List[{inner_type.__name__}]"
+            if hasattr(inner_type, "__name__")
+            else "List[Unknown]"
+        )
+
+    if origin is Union or isinstance(origin, types.UnionType):
+        inner_types = [t.__name__ for t in get_args(annotation) if t is not type(None)]
+        return " | ".join(inner_types) if inner_types else "Unknown"
+
+    if isinstance(annotation, types.UnionType):
+        inner_types = [t.__name__ for t in get_args(annotation) if t is not type(None)]
+        return " | ".join(inner_types) if inner_types else "Unknown"
+
+    return annotation.__name__ if hasattr(annotation, "__name__") else "Unknown"
+
+
+def update_params_with_default(param_info: dict[str, str]) -> dict[str, str]:
+    """
+    Update the 'default' value in the params dictionary based on its description.
+
+    Args:
+        param_info (dict): A dictionary describing a parameter.
+
+    Returns:
+        dict: The updated param_info dictionary.
+    """
+    if param_info.get("default") != "No default":
+        return param_info
+    description = param_info.get("description", "")
+    # Regular expression to find a sentence starting with 'Default to ' and ending with a period
+    match = re.search(r"Default to '([^']+)'", description)
+    if not match:
+        return param_info
+    # Extract the default value
+    default_value = match.group(1)
+    # Update the 'description' by removing the 'Default to ' phrase
+    param_info["description"] = re.sub(
+        r"Default to '[^']+'\.\s*", "", description
+    ).strip()
+    # Ensure the description ends with a single period
+    if not param_info["description"].endswith("."):
+        param_info["description"] += "."
+    # Update the 'default' key with the extracted value
+    param_info["default"] = default_value
+    param_info["default"] = param_info["default"].replace("<", "&lt;")
+    param_info["default"] = param_info["default"].replace(">", "&gt;")
+    return param_info
+
+
+def extract_command_info(command: typer.models.CommandInfo):
+    func = command.callback
+    parameters = get_params_from_function(func)
+
+    hints = get_type_hints(func)
+    docstring = func.__doc__ or "No docstring provided."
+    docstring = docstring.replace("\n", " ").replace("\n\n", " ")
+    docstring = re.sub(r"(https?://\S+)", r"<\1>", docstring)
+    command_info = {
+        "docstring": docstring,
+        "name": command.name if command.name else func.__name__,
+        "params": [],
+        "options": [],
+    }
+
+    for name, param in parameters.items():
+        raw_type = hints.get(name, None)
+        base_type = extract_base_type(raw_type)
+        description = str(param.default.help)
+        description = description.replace("\n", " ").replace("\n\n", " ")
+        param_info = {
+            "name": name,
+            "type": base_type,
+            "description": description,
+        }
+
+        if isinstance(param.default, typer.models.OptionInfo):
+            name = name.replace("_", "-")
+            if base_type == "bool":
+                name = name + f" / --no-{name}"
+            name = f"--{name}"
+            param_info["name"] = name
+            default_value = param.default.default
+            if param_info["type"] == "bool":
+                values = param_info["name"].split(" / ")
+                default_value = values[0] if param.default.default else values[1]
+            if default_value is Ellipsis:
+                default_value = "No default"
+            param_info["default"] = default_value
+
+            # if No default, check if default value is in description
+            param_info = update_params_with_default(param_info)
+
+            command_info["options"].append(param_info)
+        else:
+            command_info["params"].append(param_info)
+
+    return command_info
+
+
+def generate_markdown_level_docs(
+    f, group: TyperInfo, cli_name: str, level=1, base_name=None
+):
+    base_level = "#" * level
+    f.write(f"{base_level} `{base_name + ' ' if base_name else ''}{group.name}`\n")
+
+    for subcommand in group.typer_instance.registered_commands:
+        subcommand_info = extract_command_info(subcommand)
+        subcommand_name = (
+            subcommand.name
+            if subcommand.name is not None
+            else subcommand.callback.__name__
+        )
+        command_name = (
+            f"{base_name + ' ' if base_name else ''}{group.name} {subcommand_name}"
+        )
+        f.write(f"{base_level}# `{command_name}`\n\n")
+
+        f.write(f"{subcommand_info['docstring']}\n\n")
+
+        usage = "**Usage**:\n\n"
+        usage += "```console\n"
+        usage += f"{cli_name} {command_name}{' [OPTIONS]' if subcommand_info['options'] else ''}"
+        if subcommand_info["params"]:
+            usage += f" {' '.join(param['name'].upper() for param in subcommand_info['params'])}"
+        usage += "\n```\n\n"
+        f.write(usage)
+
+        if subcommand_info["params"]:
+            # Arguments
+            f.write("**Arguments**:\n\n")
+            f.write("| ARGUMENT | DESCRIPTION | VALUE TYPE |\n")
+            f.write("| -------- | ----------- | ----------- |\n")
+            for param in subcommand_info["params"]:
+                param["description"] = (
+                    param["description"]
+                    if param.get("description")
+                    else "No description"
+                )
+                param["type"] = param["type"] if param["type"] else "No type"
+
+                f.write(
+                    f"| {param['name'].upper()} | {param['description']} | {param['type']} |\n"
+                )
+
+            f.write("\n")
+
+        # Options
+        if subcommand_info["options"]:
+            f.write("**Options**:\n\n")
+            f.write("| OPTIONS | DESCRIPTION | VALUE TYPE | DEFAULT VALUE |\n")
+            f.write("| ------- | ----------- | ---------- | ------------- |\n")
+            for param in subcommand_info["options"]:
+                param["description"] = (
+                    param["description"]
+                    if param.get("description")
+                    else "No description"
+                )
+                param["type"] = param["type"] if param["type"] else "No type"
+                param["default"] = (
+                    param["default"] if param["default"] is not None else "No default"
+                )
+                # if No default, check if default value is in description
+                param = update_params_with_default(param)
+                f.write(
+                    f"| {param['name']} | {param['description']} | {param['type']} | {param['default']} |\n"
+                )
+
+            f.write("\n")
+    for subgroup in group.typer_instance.registered_groups:
+        generate_markdown_level_docs(f, subgroup, cli_name, level + 1, group.name)
+
+
+def generate_markdown_docs() -> None:
+    """
+    Generate markdown documentation for all registered commands and subcommands in the application.
+    The documentation will include descriptions, arguments, and options.
+
+    The generated markdown is saved in the 'docs/reference/cli.md' file.
+    """
+    # Iterate through each group in app.registered_groups
+    with open("docs/reference/cli.md", "w") as f:
+        for group in app.registered_groups:
+            if group.name == "key":
+                continue
+            generate_markdown_level_docs(f, group, "folding", 2)
+
+
+if __name__ == "__main__":
+    generate_markdown_docs()

folding-studio/docs/mkdocs.yml

@@ -0,0 +1,116 @@
+extra_css:
+  - css/main.css
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences:
+      custom_fences:
+        - class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format ''
+          name: mermaid
+  - pymdownx.tabbed:
+      alternate_style: true
+  - attr_list
+  - md_in_html
+  - pymdownx.emoji:
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg ''
+      emoji_index: !!python/name:material.extensions.emoji.twemoji ''
+nav:
+  - index.md
+  - Tutorials:
+      - tutorials/index.md
+      - Install Folding Studio: tutorials/installation.md
+      - Run AlphaFold2 on a protein sequence: tutorials/single_folding_job_af2.md
+      - Perform a Multiple Sequence Alignment (MSA) search: tutorials/msa_search.md
+      - Preview - Run folding jobs with AlphaFold3-like models: tutorials/single_folding_job_af3.md
+  - How-to guides:
+      - how-to-guides/index.md
+      - AlphaFold2/OpenFold:
+          - Provide Input Data: how-to-guides/af2_openfold/provide_input_data.md
+          - Launch a Folding Job using AlphaFold2: how-to-guides/af2_openfold/single_af2_job.md
+          - Launch a Folding Job using OpenFold: how-to-guides/af2_openfold/single_openfold_job.md
+          - Launch a Folding Job with custom parameters: how-to-guides/af2_openfold/set_af_folding_parameters.md
+          - Launch a batch Folding Job from a configuration file: how-to-guides/af2_openfold/batch_job_from_configuration_file.md
+          - Launch a batch Folding Job from a directory of fasta files: how-to-guides/af2_openfold/batch_job_from_directory.md
+          - Check Job Status: how-to-guides/af2_openfold/fetch_folding_job_status.md
+          - Download Job Logs: how-to-guides/af2_openfold/download_logs.md
+          - Cancel a Folding Job submission: how-to-guides/af2_openfold/cancel_experiment.md
+          - Retrieve Features from a Folding Job: how-to-guides/af2_openfold/get_experiment_features.md
+          - Download results of a folding job: how-to-guides/af2_openfold/download_prediction_results.md
+          - Advanced Algorithms:
+              - Launch a Folding Job using MSA subsampling: how-to-guides/af2_openfold/advanced_algorithms/msa_subsampling_job.md
+              - Launch a Folding Job using the Gap Trick for Folding Multimer Complexes: how-to-guides/af2_openfold/advanced_algorithms/gap_trick_job.md
+              - Launch a Folding Job using an Initial Guess Structure in AlphaFold2: how-to-guides/af2_openfold/advanced_algorithms/initial_guess_af2.md
+              - Launch a Folding Job applying Template Masking in Gap Trick Mode: how-to-guides/af2_openfold/advanced_algorithms/template_masking_job.md
+          - Preview - Launch a folding job using SoloSeq model: how-to-guides/af2_openfold/soloseq_job.md
+      - Preview - AlphaFold3-like:
+          - Provide Input Data: how-to-guides/af3/provide_input_data.md
+          - Launch a Single Job using Boltz-1: how-to-guides/af3/single_job_boltz.md
+          - Launch a Single Job using Chai-1: how-to-guides/af3/single_job_chai.md
+          - Launch a Single Job using Protenix: how-to-guides/af3/single_job_protenix.md
+          - Launch a Single Job from a YAML file using Boltz-1: how-to-guides/af3/boltz_single_yaml_job.md
+          - Launch a Batch Job from a directory: how-to-guides/af3/batch_job_from_directory.md
+          - Launch a Single Job from a Protein Sequence: how-to-guides/af3/single_job_from_protein_sequence.md
+      - Post-processing recipes:
+          - Calculate Interface pLDDT and pAE: how-to-guides/other/pLDDT_pAE_calculation.md
+      - Multiple Sequence Alignment Search:
+          - Provide Input Data for MSA: how-to-guides/msa_search/provide_input_data.md
+          - Launch an MSA Search with MMSeqs2: how-to-guides/msa_search/msa_search_mmseqs2.md
+          - Launch an MSA Search ignoring cache: how-to-guides/msa_search/msa_no_cache.md
+          - Check an MSA Job Status: how-to-guides/msa_search/fetch_msa_job_status.md
+          - Download MSA Job Logs: how-to-guides/msa_search/download_msa_logs.md
+          - Download Results of an MSA Search: how-to-guides/msa_search/download_msa_search_results.md
+  - Explanation:
+      - explanation/index.md
+      - Supported models: explanation/supported_models.md
+      - Advanced algorithms: explanation/advanced_algorithms.md
+  - Reference:
+      - CLI: reference/cli.md
+      - Python Library: reference/python_lib_docs.md
+plugins:
+  - swagger-ui-tag
+  - search
+site_name: Folding Studio
+site_url: https://int-bio-foldingstudio-gcp.nw.r.appspot.com
+theme:
+  colormode: auto
+  features:
+    - content.code.select
+    - content.code.copy
+    - navigation.indexes
+    - navigation.tracking
+    - navigation.sections
+    - navigation.top
+  highlightjs: true
+  hljs_languages:
+    - python
+    - bash
+  icon:
+    admonition:
+      abstract: octicons/checklist-16
+      bug: octicons/bug-16
+      danger: octicons/zap-16
+      example: octicons/beaker-16
+      failure: octicons/x-circle-16
+      info: octicons/info-16
+      note: octicons/tag-16
+      question: octicons/question-16
+      quote: octicons/quote-16
+      success: octicons/check-16
+      tip: octicons/squirrel-16
+      warning: octicons/alert-16
+    logo: material/dna
+  name: material
+  nav_style: primary
+  palette:
+    - media: '(prefers-color-scheme: light)'
+      scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: '(prefers-color-scheme: dark)'
+      scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  user_color_mode_toggle: true