boltz-api 0.44.0 → 0.45.0

package/src/resources/predictions/structure-and-binding.ts

@@ -131,6 +131,40 @@ export class StructureAndBinding extends APIResource {
   ): APIPromise<StructureAndBindingStartResponse> {
     return this._client.post('/compute/v1/predictions/structure-and-binding', { body, ...options });
   }
+
+  /**
+   * Returns the total token count for a prospective Boltz2 complex along with the
+   * maximum token count the caller's compute config will accept. Pure introspection
+   * — never rejects when the complex is too large; still rejects on malformed inputs
+   * the model could not interpret. Use the sandbox prediction endpoint if you need
+   * the cap enforced.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.predictions.structureAndBinding.tokenCount({
+   *     input: {
+   *       entities: [
+   *         {
+   *           chain_ids: ['string'],
+   *           type: 'protein',
+   *           value: 'value',
+   *         },
+   *       ],
+   *     },
+   *     model: 'boltz-2.1',
+   *   });
+   * ```
+   */
+  tokenCount(
+    body: StructureAndBindingTokenCountParams,
+    options?: RequestOptions,
+  ): APIPromise<StructureAndBindingTokenCountResponse> {
+    return this._client.post('/compute/v1/predictions/structure-and-binding/token-count', {
+      body,
+      ...options,
+    });
+  }
 }
 
 export type StructureAndBindingListResponsesCursorPage = CursorPage<StructureAndBindingListResponse>;
@@ -2057,6 +2091,20 @@ export namespace StructureAndBindingStartResponse {
   }
 }
 
+export interface StructureAndBindingTokenCountResponse {
+  /**
+   * Maximum token count the caller's compute config will accept for a sandbox
+   * prediction.
+   */
+  max_token_count: number;
+
+  /**
+   * Total token count for the complex, after applying the affinity model's internal
+   * crop when relevant.
+   */
+  total_token_count: number;
+}
+
 export interface StructureAndBindingRetrieveParams {
   /**
    * Workspace ID. Only used with admin API keys. Ignored (or validated) for
@@ -3324,6 +3372,631 @@ export namespace StructureAndBindingStartParams {
   }
 }
 
+export interface StructureAndBindingTokenCountParams {
+  input: StructureAndBindingTokenCountParams.Input;
+
+  /**
+   * Model to use for prediction
+   */
+  model: 'boltz-2.1';
+
+  /**
+   * Client-provided key to prevent duplicate submissions on retries
+   */
+  idempotency_key?: string;
+
+  /**
+   * Target workspace ID (admin keys only; ignored for workspace keys)
+   */
+  workspace_id?: string;
+}
+
+export namespace StructureAndBindingTokenCountParams {
+  export interface Input {
+    /**
+     * Entities (proteins, RNA, DNA, ligands) forming the complex to predict. Order
+     * determines chain assignment.
+     */
+    entities: Array<
+      | Input.Boltz2ProteinEntity
+      | Input.RnaEntity
+      | Input.DnaEntity
+      | Input.LigandCcdEntity
+      | Input.LigandSmilesEntity
+    >;
+
+    binding?: Input.LigandProteinBinding | Input.ProteinProteinBinding;
+
+    /**
+     * Bond constraints between atoms. Atom-level ligand references currently support
+     * ligand_ccd only; ligand_smiles is unsupported.
+     */
+    bonds?: Array<Input.Bond>;
+
+    /**
+     * Structural constraints (pocket and contact). Atom-level ligand references
+     * currently support ligand_ccd only; ligand_smiles is unsupported.
+     */
+    constraints?: Array<Input.PocketConstraint | Input.ContactConstraint>;
+
+    model_options?: Input.ModelOptions;
+
+    /**
+     * Number of structure samples to generate
+     */
+    num_samples?: number;
+
+    /**
+     * Template structure files to guide protein-chain prediction. Supports up to 4 CIF
+     * or PDB templates from HTTPS URLs or base64 uploads. Use template_chains to map
+     * request chains to template-file chains.
+     */
+    templates?: Array<Input.Template>;
+  }
+
+  export namespace Input {
+    export interface Boltz2ProteinEntity {
+      /**
+       * Chain IDs for this entity
+       */
+      chain_ids: Array<string>;
+
+      type: 'protein';
+
+      /**
+       * Amino acid sequence (one-letter codes)
+       */
+      value: string;
+
+      /**
+       * Whether the sequence is cyclic
+       */
+      cyclic?: boolean;
+
+      /**
+       * CCD post-translational modifications. Optional; defaults to an empty list when
+       * omitted. SMILES modifications are not supported.
+       */
+      modifications?: Array<Boltz2ProteinEntity.Modification>;
+
+      /**
+       * Optional protein MSA control. Omit msa on all protein entities to use automatic
+       * MSA generation. Use custom for user-provided A3M/CSV files, or empty for
+       * single-sequence mode. Custom MSA and automatic MSA cannot be mixed in one
+       * request.
+       */
+      msa?: Boltz2ProteinEntity.Boltz2CustomMsa | Boltz2ProteinEntity.Boltz2EmptyMsa;
+    }
+
+    export namespace Boltz2ProteinEntity {
+      /**
+       * Polymer residue modification. Only CCD codes are supported; SMILES modifications
+       * are not accepted.
+       */
+      export interface Modification {
+        /**
+         * 0-based index of the residue to modify
+         */
+        residue_index: number;
+
+        /**
+         * Modification format. Only CCD polymer modifications are supported.
+         */
+        type: 'ccd';
+
+        /**
+         * CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for
+         * phosphoserine)
+         */
+        value: string;
+      }
+
+      /**
+       * Use a user-provided MSA for this protein entity. If any protein entity uses a
+       * custom MSA, every other protein entity must use either custom or empty MSA;
+       * automatic MSA generation cannot be mixed with custom MSAs in the same request.
+       */
+      export interface Boltz2CustomMsa {
+        /**
+         * Custom MSA file format. Base64 uploads must use media_type text/x-a3m for A3M or
+         * text/csv for CSV.
+         */
+        format: 'a3m' | 'csv';
+
+        /**
+         * How to provide a file to the API
+         */
+        source: Boltz2CustomMsa.URLSource | Boltz2CustomMsa.Base64Source;
+
+        type: 'custom';
+      }
+
+      export namespace Boltz2CustomMsa {
+        export interface URLSource {
+          type: 'url';
+
+          url: string;
+        }
+
+        export interface Base64Source {
+          /**
+           * Base64-encoded file contents
+           */
+          data: string;
+
+          /**
+           * MIME type (e.g., text/csv)
+           */
+          media_type: string;
+
+          type: 'base64';
+        }
+      }
+
+      /**
+       * Run this protein entity in single-sequence mode without an MSA. Use this for
+       * chains that should not use automatic MSA generation, including non-homologous
+       * chains in a request that also includes custom MSAs.
+       */
+      export interface Boltz2EmptyMsa {
+        type: 'empty';
+      }
+    }
+
+    export interface RnaEntity {
+      /**
+       * Chain IDs for this entity
+       */
+      chain_ids: Array<string>;
+
+      type: 'rna';
+
+      /**
+       * RNA nucleotide sequence (A, C, G, U, N)
+       */
+      value: string;
+
+      /**
+       * Whether the sequence is cyclic
+       */
+      cyclic?: boolean;
+
+      /**
+       * CCD chemical modifications. Optional; defaults to an empty list when omitted.
+       * SMILES modifications are not supported.
+       */
+      modifications?: Array<RnaEntity.Modification>;
+    }
+
+    export namespace RnaEntity {
+      /**
+       * Polymer residue modification. Only CCD codes are supported; SMILES modifications
+       * are not accepted.
+       */
+      export interface Modification {
+        /**
+         * 0-based index of the residue to modify
+         */
+        residue_index: number;
+
+        /**
+         * Modification format. Only CCD polymer modifications are supported.
+         */
+        type: 'ccd';
+
+        /**
+         * CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for
+         * phosphoserine)
+         */
+        value: string;
+      }
+    }
+
+    export interface DnaEntity {
+      /**
+       * Chain IDs for this entity
+       */
+      chain_ids: Array<string>;
+
+      type: 'dna';
+
+      /**
+       * DNA nucleotide sequence (A, C, G, T, N)
+       */
+      value: string;
+
+      /**
+       * Whether the sequence is cyclic
+       */
+      cyclic?: boolean;
+
+      /**
+       * CCD chemical modifications. Optional; defaults to an empty list when omitted.
+       * SMILES modifications are not supported.
+       */
+      modifications?: Array<DnaEntity.Modification>;
+    }
+
+    export namespace DnaEntity {
+      /**
+       * Polymer residue modification. Only CCD codes are supported; SMILES modifications
+       * are not accepted.
+       */
+      export interface Modification {
+        /**
+         * 0-based index of the residue to modify
+         */
+        residue_index: number;
+
+        /**
+         * Modification format. Only CCD polymer modifications are supported.
+         */
+        type: 'ccd';
+
+        /**
+         * CCD code from RCSB PDB (e.g. 'MSE' for selenomethionine, 'SEP' for
+         * phosphoserine)
+         */
+        value: string;
+      }
+    }
+
+    export interface LigandCcdEntity {
+      /**
+       * Chain IDs for this ligand
+       */
+      chain_ids: Array<string>;
+
+      type: 'ligand_ccd';
+
+      /**
+       * CCD code (e.g., ATP, ADP)
+       */
+      value: string;
+    }
+
+    export interface LigandSmilesEntity {
+      /**
+       * Chain IDs for this ligand
+       */
+      chain_ids: Array<string>;
+
+      type: 'ligand_smiles';
+
+      /**
+       * SMILES string representing the ligand
+       */
+      value: string;
+    }
+
+    export interface LigandProteinBinding {
+      /**
+       * Chain ID of the ligand binder (must have exactly 1 copy, <50 atoms, and only
+       * ligands+proteins in entities)
+       */
+      binder_chain_id: string;
+
+      type: 'ligand_protein_binding';
+    }
+
+    export interface ProteinProteinBinding {
+      /**
+       * Chain IDs of the protein binders
+       */
+      binder_chain_ids: Array<string>;
+
+      type: 'protein_protein_binding';
+    }
+
+    /**
+     * Bond between two atoms. Atom-level ligand references currently support
+     * ligand_ccd entities only; ligand_smiles is unsupported.
+     */
+    export interface Bond {
+      /**
+       * Ligand atom reference. Atom-level ligand references currently support ligand_ccd
+       * entities only; ligand_smiles is unsupported.
+       */
+      atom1: Bond.LigandAtom | Bond.PolymerAtom;
+
+      /**
+       * Ligand atom reference. Atom-level ligand references currently support ligand_ccd
+       * entities only; ligand_smiles is unsupported.
+       */
+      atom2: Bond.LigandAtom | Bond.PolymerAtom;
+    }
+
+    export namespace Bond {
+      /**
+       * Ligand atom reference. Atom-level ligand references currently support ligand_ccd
+       * entities only; ligand_smiles is unsupported.
+       */
+      export interface LigandAtom {
+        /**
+         * Standardized atom name (verifiable in CIF file on RCSB). Atom-level references
+         * to ligand_smiles entities are currently unsupported; use ligand_ccd instead.
+         */
+        atom_name: string;
+
+        /**
+         * Chain ID containing the atom
+         */
+        chain_id: string;
+
+        type: 'ligand_atom';
+      }
+
+      export interface PolymerAtom {
+        /**
+         * Standardized atom name (verifiable in CIF file on RCSB)
+         */
+        atom_name: string;
+
+        /**
+         * Chain ID containing the atom
+         */
+        chain_id: string;
+
+        /**
+         * 0-based residue index
+         */
+        residue_index: number;
+
+        type: 'polymer_atom';
+      }
+
+      /**
+       * Ligand atom reference. Atom-level ligand references currently support ligand_ccd
+       * entities only; ligand_smiles is unsupported.
+       */
+      export interface LigandAtom {
+        /**
+         * Standardized atom name (verifiable in CIF file on RCSB). Atom-level references
+         * to ligand_smiles entities are currently unsupported; use ligand_ccd instead.
+         */
+        atom_name: string;
+
+        /**
+         * Chain ID containing the atom
+         */
+        chain_id: string;
+
+        type: 'ligand_atom';
+      }
+
+      export interface PolymerAtom {
+        /**
+         * Standardized atom name (verifiable in CIF file on RCSB)
+         */
+        atom_name: string;
+
+        /**
+         * Chain ID containing the atom
+         */
+        chain_id: string;
+
+        /**
+         * 0-based residue index
+         */
+        residue_index: number;
+
+        type: 'polymer_atom';
+      }
+    }
+
+    /**
+     * Constrains the binder to interact with specific pocket residues on the target.
+     */
+    export interface PocketConstraint {
+      /**
+       * Chain ID of the binder molecule
+       */
+      binder_chain_id: string;
+
+      /**
+       * Binding pocket residues keyed by chain ID. Each key is a chain ID (e.g. "A") and
+       * the value is an array of 0-indexed residue indices that define the pocket on
+       * that chain.
+       */
+      contact_residues: { [key: string]: Array<number> };
+
+      /**
+       * Maximum allowed distance in Angstroms between binder and pocket residues.
+       * Typical range: 4-8 A.
+       */
+      max_distance_angstrom: number;
+
+      type: 'pocket';
+
+      /**
+       * Whether to force the constraint
+       */
+      force?: boolean;
+    }
+
+    /**
+     * Contact constraint between two tokens. Atom-level ligand references currently
+     * support ligand_ccd entities only; ligand_smiles is unsupported.
+     */
+    export interface ContactConstraint {
+      /**
+       * Maximum distance in Angstroms
+       */
+      max_distance_angstrom: number;
+
+      /**
+       * Ligand contact token. Atom-level ligand references currently support ligand_ccd
+       * entities only; ligand_smiles is unsupported.
+       */
+      token1: ContactConstraint.PolymerContactToken | ContactConstraint.LigandContactToken;
+
+      /**
+       * Ligand contact token. Atom-level ligand references currently support ligand_ccd
+       * entities only; ligand_smiles is unsupported.
+       */
+      token2: ContactConstraint.PolymerContactToken | ContactConstraint.LigandContactToken;
+
+      type: 'contact';
+
+      /**
+       * Whether to force the constraint
+       */
+      force?: boolean;
+    }
+
+    export namespace ContactConstraint {
+      export interface PolymerContactToken {
+        /**
+         * Chain ID
+         */
+        chain_id: string;
+
+        /**
+         * 0-based residue index
+         */
+        residue_index: number;
+
+        type: 'polymer_contact';
+      }
+
+      /**
+       * Ligand contact token. Atom-level ligand references currently support ligand_ccd
+       * entities only; ligand_smiles is unsupported.
+       */
+      export interface LigandContactToken {
+        /**
+         * Atom name. Atom-level references to ligand_smiles entities are currently
+         * unsupported; use ligand_ccd instead.
+         */
+        atom_name: string;
+
+        /**
+         * Chain ID
+         */
+        chain_id: string;
+
+        type: 'ligand_contact';
+      }
+
+      export interface PolymerContactToken {
+        /**
+         * Chain ID
+         */
+        chain_id: string;
+
+        /**
+         * 0-based residue index
+         */
+        residue_index: number;
+
+        type: 'polymer_contact';
+      }
+
+      /**
+       * Ligand contact token. Atom-level ligand references currently support ligand_ccd
+       * entities only; ligand_smiles is unsupported.
+       */
+      export interface LigandContactToken {
+        /**
+         * Atom name. Atom-level references to ligand_smiles entities are currently
+         * unsupported; use ligand_ccd instead.
+         */
+        atom_name: string;
+
+        /**
+         * Chain ID
+         */
+        chain_id: string;
+
+        type: 'ligand_contact';
+      }
+    }
+
+    export interface ModelOptions {
+      /**
+       * The number of recycling steps to use for prediction. Default is 3.
+       */
+      recycling_steps?: number;
+
+      /**
+       * The number of sampling steps to use for prediction. Default is 200.
+       */
+      sampling_steps?: number;
+
+      /**
+       * Diffusion step scale (temperature). Controls sampling diversity — higher values
+       * produce more varied structures. Default is 1.638.
+       */
+      step_scale?: number;
+    }
+
+    /**
+     * Template structure used as an inference-time guide for Boltz-2.1 protein-chain
+     * geometry. Provide a CIF or PDB file from an HTTPS URL or base64 upload.
+     */
+    export interface Template {
+      /**
+       * Request-to-template chain mappings. Each input_chain_id and template_chain_id
+       * must be unique within this template.
+       */
+      template_chains: Array<Template.TemplateChain>;
+
+      /**
+       * How to provide a template structure file. URLs must point to a CIF or PDB file;
+       * base64 uploads must use chemical/x-cif or chemical/x-pdb.
+       */
+      template_structure: Template.URLSource | Template.TemplateStructureBase64Source;
+
+      /**
+       * Force the template reference potential with this distance threshold in
+       * angstroms. Omit to use the template without force.
+       */
+      force_threshold_angstroms?: number;
+    }
+
+    export namespace Template {
+      /**
+       * Mapping from one request chain to the corresponding chain in the template
+       * structure file.
+       */
+      export interface TemplateChain {
+        /**
+         * Chain ID in this prediction request
+         */
+        input_chain_id: string;
+
+        /**
+         * Corresponding chain ID in the template structure file
+         */
+        template_chain_id: string;
+      }
+
+      export interface URLSource {
+        type: 'url';
+
+        url: string;
+      }
+
+      export interface TemplateStructureBase64Source {
+        /**
+         * Base64-encoded template structure file contents
+         */
+        data: string;
+
+        /**
+         * Template structure MIME type
+         *
+         * - `chemical/x-cif` - CIF template structure
+         * - `chemical/x-pdb` - PDB template structure
+         */
+        media_type: 'chemical/x-cif' | 'chemical/x-pdb';
+
+        type: 'base64';
+      }
+    }
+  }
+}
+
 export declare namespace StructureAndBinding {
   export {
     type StructureAndBindingRetrieveResponse as StructureAndBindingRetrieveResponse,
@@ -3331,10 +4004,12 @@ export declare namespace StructureAndBinding {
     type StructureAndBindingDeleteDataResponse as StructureAndBindingDeleteDataResponse,
     type StructureAndBindingEstimateCostResponse as StructureAndBindingEstimateCostResponse,
     type StructureAndBindingStartResponse as StructureAndBindingStartResponse,
+    type StructureAndBindingTokenCountResponse as StructureAndBindingTokenCountResponse,
     type StructureAndBindingListResponsesCursorPage as StructureAndBindingListResponsesCursorPage,
     type StructureAndBindingRetrieveParams as StructureAndBindingRetrieveParams,
     type StructureAndBindingListParams as StructureAndBindingListParams,
     type StructureAndBindingEstimateCostParams as StructureAndBindingEstimateCostParams,
     type StructureAndBindingStartParams as StructureAndBindingStartParams,
+    type StructureAndBindingTokenCountParams as StructureAndBindingTokenCountParams,
   };
 }