BoltzGen

Use BoltzGen to run boltzgen_v1 graph workflows.

Metrics and Artifacts

Task results (GET /v1/workflows/task-results/<workflow_id>)

For task_type == pipeline_run_boltzgen_v1, when a final_designs_metrics_*.csv is present among outputs, parsed_results lists one object per design row (subset of CSV columns). Rows can include a file object with libraryItemId and fileName for the ranked CIF when filenames match the rank{n}_*.cif pattern.

Allowed keys in parsed_results mirror the metrics CSV, for example: id, final_rank, designed_sequence, num_design, design_ptm, design_hydrophobicity, loop, helix, sheet, ligand_iptm, interaction_pae, min_interaction_pae, iptm, ptm, design_iiptm, target_ptm, max_rank, secondary_rank, quality_score, and bindsite_under_3rmsd through bindsite_under_9rmsd.

All tasks also return output_library_items with library-backed artifacts (CSVs, PDF, CIF, etc.).

Declared keys (output-schema)

Call POST /v1/workflows/node/output-schema with workflowTaskTypeId: pipeline_run_boltzgen_v1. The body must include inputPayload.numDesigns and may include budget (top‑K ranks). The response lists availableOutput[] for composer validation.

Metric-like names use designs[<0-based index>].<field> where the index equals final_rank - 1 in the exported CSV.

Declared files (types such as file/CSV):

SDK and CLI

Use the same patterns as in Logs and results below: client.workflows.task_results(workflow_id) or:

fastfold-cli workflows task-results <workflow_id>
fastfold-cli workflows task-results <workflow_id> --json

Composer: If / Else and CEL

The BoltzGen composer (UI: /workflow/composer/...) builds a boltzgen_v1 graph: Design Spec → BoltzGen pipeline → optional If / Else → branches → End nodes.

If / Else node

• Placement: An If / Else node must follow a step with an output schema. The enforced predecessor for branching is BoltzGen (pipeline_run_boltzgen_v1): Design Spec → BoltzGen, then BoltzGen → If / Else.
• Branches: Two outgoing handles — true and false. At most one downstream node per handle.
• YAML: Branching is stored under top-level conditions: each entry has source, target, and sourceHandle ("true" or "false"; YAML booleans are normalized on ingest).

conditions:
  - source: if_else
    target: run_followup
    sourceHandle: true
  - source: if_else
    target: end_early
    sourceHandle: false

The expression string is inputPayload.expressionCEL on the If / Else job.

Common Expression Language (CEL)

CEL expresses boolean conditions over workflow outputs. The composer validates names against the Declared keys list above (via output-schema).

Evaluation context (BoltzGen → If / Else): the worker reads final_designs_metrics_*.csv, builds a context like:

{
  "designs": [
    { "ptm": 0.83, "iptm": 0.71, "final_rank": 1, "designed_sequence": "..." }
  ]
}

Index designs[0] matches final_rank == 1. Field names align with designs[i].<field> from output-schema for pipeline_run_boltzgen_v1.

Examples (CEL):

designs[0].iptm >= 0.7

designs[0].ptm > 0.8 && designs[0].interaction_pae < 12.0

designs[0].quality_score != null && designs[0].quality_score > 0.5

size(designs[0].designed_sequence) > 100

Reference: cel.dev.

The If / Else task must have a non-empty expressionCEL or the worker errors when executing that task.

Scope: output-schema also lists OpenMM / OpenMMDL metric paths for UIs. Graph If / Else execution evaluates CEL on BoltzGen CSV metrics when the immediate predecessor is pipeline_run_boltzgen_v1.

Discovering variables in the UI

1. Select If / Else after BoltzGen.
2. Open the condition editor — keys match output-schema (metrics as designs[i].…, files as file/… types).
3. Use How to in the panel for CEL examples.

Input schemas

BoltzGen workflows involve two nested inputs:

• the outer API request body used to create or update the workflow
• the inner workflow.yml graph spec, including the design-spec YAML referenced by that graph

The one-shot create-from-YAML body is:

{
  "workflow_name": "boltzgen_v1",
  "workflow_yml": "version: 1\njobs:\n  ...",
  "name": "boltzgen_from_yml",
  "create_mode": "",
  "execute": true
}

The packaged sample uses the following workflow.yml shape:

version: 1
jobs:
  start:
    type: start
    position:
      x: 66.67
      y: 133.33
    description: Workflow start point
    label: Start
  design_spec:
    type: input
    subType: design_specification_yml
    workflowTaskTypeId: input_design_spec_boltzgen_v1
    position:
      x: 327.78
      y: 133.33
    inputPayload:
      inputYML: design_spec.example.yaml
      inputYMLLibraryItemId: 11111111-1111-1111-1111-111111111111
      files:
        - libraryItemId: 22222222-2222-2222-2222-222222222222
          fileName: 5cqg.cif
    label: Design Spec
  boltzgen:
    type: pipeline
    subType: boltzgen
    workflowTaskTypeId: pipeline_run_boltzgen_v1
    position:
      x: 588.89
      y: 133.33
    inputPayload:
      protocolName: protein-anything
      numDesigns: 1
      budget: 1
    label: BoltzGen
  end:
    type: end
    position:
      x: 850
      y: 133.33
    description: Workflow end point
    label: End
workflows:
  main:
    jobs:
      - start
      - design_spec:
          requires: [start]
      - boltzgen:
          requires: [design_spec]
      - end:
          requires: [boltzgen]

The following design-spec YAML is referenced by inputPayload.inputYML:

entities:
  - protein:
      id: G
      sequence: 12..20
  - file:
      path: 5cqg.cif
      include:
        - chain:
            id: A
      binding_types:
        - chain:
            id: A
            binding: 343,344,251
      structure_groups: "all"

Field notes:

• workflow_yml is required for the one-shot create endpoint.
• jobs.<node>.position.x and .y are optional editor coordinates, not semantic run settings.
• The design-spec input node must reference a real uploaded design-spec YAML via inputYMLLibraryItemId.
• inputPayload.files[].libraryItemId and fileName must point to real uploaded structure files referenced by the design-spec YAML.
• protocolName, numDesigns, and budget are the core packaged pipeline fields for the sample graph.

Downloadable Preset Files

This section includes the current non-empty BoltzGen example presets so you can download the exact files and run them locally with the SDK or CLI. Keep the original filenames when saving these files locally, because many specs reference neighboring files by name.

Note: BoltzGen presets are not all shaped the same way. Some presets contain a single self-contained design-spec file, while others compose multiple referenced YAML specs and structure files into one run.

1. Vanilla Peptide

• Design-spec YAML: vanilla_target_binding_site.design_spec.yaml
• Target structure: 5cqg.cif

2. Vanilla Protein

• Design-spec YAML: vanilla_protein.design_spec.yaml
• Target structure: 1g13.cif

3. Binding Disordered Peptides

• Design-spec YAML: binding_disordered_peptides.design_spec.yaml
• This starter preset does not require an uploaded target structure file.

4. Protein Binding Small Molecule

• Design-spec YAML: protein_binding_small_molecule.design_spec.yaml
• This starter preset does not require an uploaded target structure file.
• The ligand is encoded directly in the spec as CCD TSA.

5. Small Molecule From File And Smiles

• Design-spec YAML: small_molecule_from_file_and_smiles.design_spec.yaml
• Structure file: 4g37.pdb

6. Cyclic Against HIV Antibody Site

• Design-spec YAML: 9d3d.yaml
• Target structure: 9d3d.cif

7. Nanobody Against Penguinpox (Multi-Spec)

• Main design-spec YAML: penguinpox.yaml
• Main target structure: 9bkq-assembly2.cif
• Scaffold 1: 7eow.yaml and 7eow.cif
• Scaffold 2: 7xl0.yaml and 7xl0.cif
• Scaffold 3: gontivimab.yaml and gontivimab.cif
• Scaffold 4: isecarosmab.yaml and isecarosmab.cif
• Scaffold 5: sonelokimab.yaml and sonelokimab.cif

This preset uses referenced specs. In the workflow composer, each referenced YAML or structure file is uploaded as its own library item, and the main design-spec YAML references those uploaded files by basename:

entities:
  - file:
      path: 9bkq-assembly2.cif
      include:
        - chain:
            id: B
  - file:
      path: 7eow.yaml
  - file:
      path: 7xl0.yaml
  - file:
      path: gontivimab.yaml
  - file:
      path: isecarosmab.yaml
  - file:
      path: sonelokimab.yaml

The composer also persists library references alongside that YAML. For a multi-spec node, the effective node payload follows this pattern:

{
  "inputYML": "penguinpox.yaml",
  "inputYMLLibraryItemId": "<library-item-id-for-penguinpox-yaml>",
  "files": [
    { "libraryItemId": "<library-item-id-for-9bkq-cif>", "fileName": "9bkq-assembly2.cif" },
    { "libraryItemId": "<library-item-id-for-7eow-yaml>", "fileName": "7eow.yaml" },
    { "libraryItemId": "<library-item-id-for-7eow-cif>", "fileName": "7eow.cif" },
    { "libraryItemId": "<library-item-id-for-7xl0-yaml>", "fileName": "7xl0.yaml" },
    { "libraryItemId": "<library-item-id-for-7xl0-cif>", "fileName": "7xl0.cif" }
  ]
}

Note: The YAML itself does not carry library item IDs. Resolution happens through the design-spec node payload: inputYML and inputYMLLibraryItemId identify the main YAML file, and files[] provides the uploaded file mapping for every referenced YAML or structure file.

Tip: In practice, use the uploaded file basename in path values such as 7eow.yaml or 9bkq-assembly2.cif. The backend can fall back to basename matching, but matching files[].fileName directly is the safest published pattern.

Reminder: Referenced scaffold YAML files can themselves point to additional structure files. Upload the full file set, not only the top-level penguinpox.yaml.

For the multi-spec preset, preserve the folder layout when downloading locally:

• nanobody_against_penguinpox/penguinpox.yaml
• nanobody_against_penguinpox/9bkq-assembly2.cif
• nanobody_scaffolds/*.yaml
• nanobody_scaffolds/*.cif

The empty preset is intentionally not listed here because it does not ship example input files.

Create a draft

from fastfold import Client

client = Client()
draft = client.boltzgen.create_draft(name="boltzgen_demo")
print(draft.workflow_id)

fastfold-cli workflows boltzgen create-draft --name boltzgen_demo

Build a minimal workflow.yml

The SDK package ships lightweight example assets:

• fastfold/examples/boltzgen/design_spec.example.yaml
• fastfold/examples/boltzgen/minimal.workflow.yml
• fastfold/examples/boltzgen/replacements.example.json

The packaged example uses the graph-spec shape expected by the workflow YAML endpoints:

• jobs.<job_name> entries define node type, subtype, task type, labels, and inputPayload
• workflows.main.jobs defines execution order and requires
• input_design_spec_boltzgen_v1 needs a design-spec YAML file plus referenced uploaded structure files

position.x and position.y are editor coordinates. Keep them if you want the graph to open nicely in Composer, but they are not the semantic part of the run configuration.

Tip: Start from the packaged minimal graph when you want a clean draft that is easy to reason about. Move to the larger preset bundles only after you are comfortable with the file-linking pattern.

fastfold-cli workflows boltzgen build-spec \
  --template-file fastfold/examples/boltzgen/minimal.workflow.yml \
  --replacements-file fastfold/examples/boltzgen/replacements.example.json \
  --output ./workflow.yml

Required files for the packaged sample after replacement:

• a design-spec YAML such as fastfold/examples/boltzgen/design_spec.example.yaml
• at least one uploaded structure file such as 5cqg.cif
• matching library item IDs for those uploaded files

Note: workflow.yml stores references to uploaded library items, not local filesystem paths. Upload the inputs first, then substitute the resulting library item IDs into the workflow spec.

For additional presets and domain-specific reference bundles, see the published examples in fastfold-skills.

Design-spec example to upload first

The packaged design-spec example uses the following structure:

entities:
  - protein:
      id: G
      sequence: 12..20

  - file:
      path: 5cqg.cif
      include:
        - chain:
            id: A
      binding_types:
        - chain:
            id: A
            binding: 343,344,251
      structure_groups: "all"

Upload the design-spec YAML and the referenced structure file to the library first, then link those uploaded items from the workflow YAML.

Reminder: The path field inside the design-spec YAML still needs to match the referenced filename. If the uploaded structure file is named 5cqg.cif, keep path: 5cqg.cif in the YAML.

from fastfold import Client

client = Client()
design_spec_ref = client.boltzgen.upload_input(
    file_path="fastfold/examples/boltzgen/design_spec.example.yaml",
    file_type="yml",
    item_name="beetletert",
)
structure_ref = client.boltzgen.upload_input(
    file_path="./5cqg.cif",
    file_type="protein",
    item_name="5cqg",
)
print(design_spec_ref.library_item_id, structure_ref.library_item_id)

Those uploaded IDs are what you place into inputYMLLibraryItemId and files[].libraryItemId in the workflow YAML.

Tip: Keep a small mapping file of local filename to library item ID while preparing a workflow. It makes replacement into workflow.yml much less error-prone for multi-file examples.

Upload or replace workflow.yml

from pathlib import Path

from fastfold import Client

client = Client()
workflow_id = "af2473ef-820d-44df-98fe-fa15103157d5"
client.boltzgen.upsert_workflow_yml(workflow_id, Path("./workflow.yml").read_text())
print(client.boltzgen.get_workflow_yml(workflow_id))

fastfold-cli workflows boltzgen set-yml af2473ef-820d-44df-98fe-fa15103157d5 --file ./workflow.yml
fastfold-cli workflows boltzgen get-yml af2473ef-820d-44df-98fe-fa15103157d5

One-shot create from workflow.yml

from pathlib import Path

from fastfold import Client

client = Client()
workflow = client.boltzgen.create_from_workflow_yml(
    Path("./workflow.yml").read_text(),
    name="boltzgen_from_yml",
    execute=True,
)
print(workflow.workflow_id)

fastfold-cli workflows boltzgen create-from-yml --file ./workflow.yml --name boltzgen_from_yml --execute

Logs and results

from fastfold import Client

client = Client()
workflow_id = "af2473ef-820d-44df-98fe-fa15103157d5"
print(client.boltzgen.get_logs(workflow_id))
print(client.workflows.task_results(workflow_id).raw)

Related API docs:

• /workflows/addWorkflowGraph
• /workflows/getWorkflowYml
• /workflows/setWorkflowYml
• /workflows/executeWorkflow