boltz-structure-and-binding

Workflow

If boltz-api is missing from PATH, use boltz-cli-setup for install/update guidance before retrying. If a command reports missing or expired authentication, use boltz-cli-setup to start boltz-api auth login --device-code before retrying; do not ask permission first. If the agent host sandbox blocks boltz-api install/auth/API calls, use boltz-cli-setup to request the host sandbox bypass/escalation needed for user-wide CLI install, browser login, credential storage, temp files, or API access before retrying.

Use this skill for one defined complex, not a library workflow.

1. Normalize the inputs into entities. Each entity is {type, chain_ids, value} — note plural chain_ids (an array, even for one chain) and the field is value, not sequence:

   {"entities": [{"type": "protein", "chain_ids": ["A"], "value": "MKTAYIAKQRQISFVKSHFSRQ"}]}
   

   type is one of protein | rna | dna | ligand_smiles | ligand_ccd. Chain IDs go in entity order (A, B, C, …) unless the user specifies otherwise. Read references/api.md for per-type field variants (cyclic, modifications, ligand CCD codes, etc.) before authoring your first payload — agent guesses like sequence: or chain_id: "A" (singular) fail with unclear 400 errors.

2. If the user wants binding metrics, add a flat binding block with an explicit type field. For ligand-protein binding use:

   binding:
     type: ligand_protein_binding
     binder_chain_id: B
   

   For protein-protein binding use:

   binding:
     type: protein_protein_binding
     binder_chain_ids: [B]
   

   Do not nest the variant name under binding (for example, no binding.ligand_protein_binding object).

3. Supported optional features include constraints, bonds, modifications, model_options, and binding metrics; only add them if the user asks. Read references/api.md for exact shapes and examples.

4. Author the payload YAML or JSON, run estimate-cost, show the USD cost, wait for explicit confirmation.

5. start to submit (synchronous). Capture the ID.

6. Launch download-results through the runtime's long-running or non-blocking command facility so polling + download continue without blocking the agent session. Use the mechanism the runtime documents; consult boltz-cli-setup if unsure. After launching the downloader, always report the job ID, run name, and output directory. If the runtime can schedule follow-up checks, schedule a download-status check and state the cadence; otherwise include the download-status command.