Proto is not affiliated with PDBe, EMBL-EBI, and wwPDB. This toolkit is open source and builds on the implementations produced by these organizations. Product names, logos, and trademarks are the property of their respective owners.

### CCD Lookup (`ccd-lookup`) Enriches wwPDB Chemical Component Dictionary entries. Accepts CCD codes (such as `"ATP"`) or SMILES strings, in mixed batches, and returns a `CcdLookupOutput` containing a `Ligands` collection plus parallel `CcdEnrichment` records: formula, descriptors, parent component, RDKit physicochemical properties, optional UniChem cross-references, and optional PDB usage. #### API Reference

Source CCD codes (e.g. `"ATP"`) or SMILES strings. A single string is normalized to a list.

Source Fetch UniChem cross-references (DrugBank/ChEMBL/PubChem/etc. IDs). Requires network. Default: False. Fetch PDB structures containing each ligand from the RCSB search API. Requires network. Default: False. Sanitize the parsed RDKit molecule. Disable only for CCD entries with unusual valences. Default: True. Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`. Device to run the tool on. Maximum execution time in seconds. `None` waits indefinitely. Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.

Source One entry per input identifier, in input order, each holding the resolved `Fragment` and its CCD-specific metadata (formula, descriptors, release status, optional network data). The ligand built for this identifier, carrying the CCD code when one could be resolved to a usable structure. `fragment.ccd_code` is the single source of truth for which CCD entry this is. Chemical formula (e.g. `"C10 H16 N5 O13 P3"`). Formula weight in Daltons. InChI string as recorded in the CCD. InChIKey as recorded in the CCD. True iff release status is `REL`. Raw `pdbx_release_status` value. CCD code of the canonical parent (`mon_nstd_parent_comp_id`), if this component is a derivative. Snake\_case RDKit descriptors (`molecular_weight`, `logp`, `tpsa`, `num_h_donors`, etc.). UniChem cross-references keyed by source database (e.g. `{"chembl": ["CHEMBL14249"], ...}`). Populated only when `include_cross_references=True`; requires network. PDB IDs of structures containing this ligand. Populated only when `include_pdb_usage=True`; requires network. True when the identifier matched a CCD entry whose structure could not be rebuilt. The CCD metadata below is populated, but `fragment.ccd_code` is None and the entry counts as unresolved. Non-fatal warnings emitted while reading the entry. Errors that prevented full parsing.

#### Applications Use this for user-facing enrichment workflows such as notebooks, scripts, dashboards, and ligand reports. Resolve a CCD code or SMILES to a canonical `Fragment` with formula, descriptors, and physicochemical properties before structure prediction or docking, map a ligand to external chemistry databases via UniChem, or discover which experimental structures contain a ligand before structure-based work. The returned `Ligands` collection feeds directly into tools that take ligands as input, and PDB identifiers from `pdb_structures` pair naturally with the [PDB](https://bio-pro.mintlify.app/tools/database-retrieval/pdb) tool. #### Usage Tips * **For per-fragment SMILES-to-CCD lookups, use `proto_tools.entities.ligands.ccd_utils.map_smiles_to_ccd_code` instead.** It runs the same lookup in the current Python process, without the subprocess startup this tool incurs, so when you are not using the persistent tool context it can be much faster. * **A SMILES with no CCD match returns `ccd_code=None` rather than an error.** Check `enrichment.ccd_code is not None` before treating an entry as found. `result.num_unresolved` gives the batch-level count. * **`parent_ccd_code` is populated only when the CCD entry declares a canonical parent component.** Modified residues like `SEP` (phosphoserine, parent `SER`), `MSE` (selenomethionine, parent `MET`), or `PTR` (phosphotyrosine, parent `TYR`) carry a parent code. Most small-molecule ligands have no parent and return `None`. * **`pdb_structures` can be very large.** For common cofactors and ions (`HEM`, `ATP`, `NAG`, `MG`, `ZN`) the list runs to many thousands of PDB IDs. It may be helpful to process it in chunks rather than loading every entry at once when you pass it to a downstream step.