Boltz YAML Combiner¶
Combines sequences, constraints, templates, and properties into a single Boltz YAML configuration and assembles all auxiliary files referenced by that YAML. It validates chain ID uniqueness and schema requirements, rewrites inlined MSA/template contents to file references, and returns both the YAML object and a keyed map of file contents.
Usage¶
Use this node after building lists of items with the Boltz Sequence/Protein/Ligand, Constraint, Template, and Property builder nodes (optionally merged via Boltz List Combiner). Connect the resulting lists into this node to generate a valid Boltz YAML and associated files. Feed its outputs into Boltz Predict or Boltz Partial Diffusion to run inference.
Inputs¶
| Field | Required | Type | Description | Example |
|---|---|---|---|---|
| sequences | True | * | List (or single item) of sequence objects describing proteins, DNA/RNA, or ligands. Typically produced by Boltz Sequence Builder or its specialized variants and merged via Boltz List Combiner. | [{"protein": {"id": "A", "sequence": "MKT...", "msa": "empty", "_sequence_name": "seqA"}}, {"ligand": {"id": "L", "smiles": "CCO"}}] |
| constraints | False | * | List (or single item) of constraint objects (bond, pocket, contact) to guide modeling. Optional; typically from Boltz Constraint Builder combined via Boltz List Combiner. | [{"pocket": {"binder": "L", "contacts": [["A", 10], ["A", 15]], "max_distance": 6.0}}] |
| templates | False | * | List (or single item) of template objects with structure content. Optional; typically from Boltz Template Builder combined via Boltz List Combiner. | [{"pdb": "ATOM ...\nEND"}] |
| properties | False | * | List (or single item) of property requests, e.g., affinity prediction specifications. Optional; typically from Boltz Property Builder. | [{"affinity": {"binder": "L"}}] |
Outputs¶
| Field | Type | Description | Example |
|---|---|---|---|
| boltz_yaml | BOLTZ_YAML | The assembled Boltz YAML configuration as a dictionary object, including sequences and optional constraints/templates/properties. MSA and template fields are converted to file references. | {"version": 1, "sequences": [{"protein": {"id": "A", "sequence": "MKT...", "msa": "msa_1.a3m", "_sequence_name": "seqA"}}, {"ligand": {"id": "L", "smiles": "CCO"}}], "templates": [{"pdb": "template_2.pdb"}], "properties": [{"affinity": {"binder": "L"}}]} |
| boltz_files | BOLTZ_FILES | A map of auxiliary filenames to their contents. Includes generated MSA files (e.g., msa_1.a3m) and template files (e.g., template_2.pdb or template_3.cif). | {"msa_1.a3m": ">seqA\nMKT...", "template_2.pdb": "ATOM ...\nEND"} |
Important Notes¶
- Chain ID uniqueness: All chain IDs across all sequences must be unique. The node will raise an error if duplicates are detected.
- Schema validation: Ensures version is set (defaults to 1) and that each sequence has required fields (id and sequence for protein/dna/rna; either smiles or ccd for ligands, but not both).
- MSA handling: For protein sequences with non-empty MSA content, the node writes MSA contents to generated filenames (msa_X.a3m) and replaces inline content with the filename. If multiple chains have identical sequences, they share a single MSA file.
- Template handling: Template PDB/CIF contents are written to generated filenames (template_X.pdb or template_X.cif) and the template entries are updated to reference those filenames.
- Flexible inputs: Each input can be a single object or a list; the node normalizes to lists internally.
- Intended pipeline: Outputs should be passed to Boltz Predict or Boltz Partial Diffusion nodes.
Troubleshooting¶
- Error: Duplicate chain ID found: Ensure each chain ID across all sequences is unique. If duplicating a chain, use different IDs or configure multiple_chains appropriately when building sequences.
- Error: At least one sequence is required: Provide at least one sequence object as input.
- Error: Missing 'sequence' field in protein/dna/rna: Verify sequence builders produced objects containing 'sequence' and 'id'.
- Error: Ligand must have either 'smiles' or 'ccd' (not both): Provide only one of these fields in ligand entries.
- MSA not applied as expected: Confirm the protein entry's 'msa' is not 'empty' and contains valid A3M content. The node will convert content to a file reference in the YAML and add the file into boltz_files.
- Templates not referenced: Ensure each template object includes 'pdb' or legacy 'cif' content. The node will create a corresponding file and update the YAML reference.
- Unexpected list vs single item behavior: If providing a single object instead of a list, the node will wrap it to a list automatically. Use Boltz List Combiner to merge multiple sources consistently.