tooluniverse-chemical-compound-retrieval

化合物信息检索

通过正确消歧和跨数据库验证，检索全面的化合物数据。

查证，不要猜测：绝不臆测 CID、ChEMBL ID 或分子属性值。始终从 PubChem/ChEMBL 检索。

优先使用英语：在工具调用中始终使用英文化合物名称。用用户的语言回复。

领域推理：消歧

“Aspirin”指一种化合物。“Vitamin D”则有多种形式（D2/D3/活性代谢物）。对于类名（如类固醇、维生素、酸），请列出候选项，并在继续前确认。

---

工作流

Phase 0: Clarify (only if highly ambiguous -- skip for unambiguous names or specific IDs)
Phase 1: Disambiguate → resolve PubChem CID + ChEMBL ID
Phase 2: Retrieve data (silent)
Phase 3: Report compound profile

阶段 1：消歧

# By name
result = tu.tools.PubChem_get_CID_by_compound_name(compound_name=name)
# By SYSTEMATIC (IUPAC) name -> structure, deterministic parser (no DB lookup)
opsin = tu.tools.OPSIN_name_to_structure(name="2-acetoxybenzoic acid")
# Returns {parsed, smiles, inchi, inchikey}; use the SMILES/InChIKey to anchor a
# PubChem_get_CID_by_SMILES lookup. Trade/trivial names give parsed=false -> fall
# back to PubChem_get_CID_by_compound_name for those.
# By SMILES
result = tu.tools.PubChem_get_CID_by_SMILES(smiles=smiles)
# Cross-reference
chembl_result = tu.tools.ChEMBL_search_molecules(query=name, limit=5)

验证：CID + ChEMBL ID + canonical SMILES + 立体化学 + 盐形式。

阶段 2：数据检索

PubChem：PubChem_get_compound_properties_by_CID、PubChemBioAssay_get_assay_summary、PubChemTox_get_acute_effects、PubChem_get_compound_2D_image_by_CID

ChEMBL：ChEMBL_get_compound_record_activities、ChEMBL_get_molecule_targets、ChEMBL_get_assay_activities

可选：PubChem_get_associated_patents_by_CID、PubChem_search_compounds_by_similarity

阶段 3：报告

化合物概况应包含：身份信息（CID、ChEMBL ID、IUPAC、SMILES）、化学性质（MW、LogP、HBD、HBA、PSA、Lipinski）、生物活性（靶点、IC50/Ki）、药物信息（如已获批）、数据来源。

---

回退链

首选	回退
PubChem 名称查询（系统名称）	OPSIN_name_to_structure → SMILES/InChIKey → PubChem_get_CID_by_SMILES
PubChem 名称查询	ChEMBL 搜索 → SMILES → PubChem_get_CID_by_SMILES
ChEMBL 生物活性	PubChem 生物测定摘要
药品标签	注明“不可用”

---

证据评级

评级	标准
已确认	CID + ChEMBL 交叉匹配，InChI/SMILES 一致
很可能	找到 CID，ChEMBL 部分匹配
不确定	仅有单一数据库，或存在多个 CID
未经验证	无交叉引用，仅有单一来源

生物活性：对于经过整理的数据，ChEMBL 优于 PubChem BioAssay。IC50/Ki < 100nM = 强效，100nM-1uM = 中等效力，>10uM = 弱效。违反 Lipinski 规则会降低口服生物利用度，但不构成否决条件。

---

SMILES 验证

始终验证新 SMILES：python3 src/tooluniverse/tools/smiles_verifier.py --smiles "SMILES_STRING"。无效 SMILES 会导致错误结果或难以理解的错误。

---

标识符解析与跨数据库引用

除了 PubChem/ChEMBL，还有两个工具可在名称无法在 PubChem 中匹配，或需要跨其他化学数据库进行交叉引用时解析标识符：

• NCICACTUS_resolve（NCI CACTUS 解析器）——可在化学名称（IUPAC 或常用名称）、SMILES、InChI、InChIKey、CAS 号和分子式之间转换。已实时验证：NCICACTUS_resolve(identifier="ibuprofen", representation="smiles") → CC(C)Cc1ccc(cc1)C(C)C(O)=O；也可将 CAS 号（"50-78-2"）直接解析为 IUPAC 名称（"2-acetyloxybenzoic acid"，即阿司匹林），或将 InChIKey 解析为分子式。可作为 OPSIN_name_to_structure 和 PubChem_get_CID_by_compound_name 之外的第二条名称解析途径——CACTUS 能处理 OPSIN 无法解析的 CAS 号和俗名。
• UniChem_search_compound / UniChem_connectivity_search——给定 InChIKey（或来源数据库中的化合物 ID），返回 UniChem 注册的 25 个以上来源数据库（ChEMBL、DrugBank、PubChem、Wikipedia、ChEBI 等）中的交叉引用。已通过 UniChem_list_sources 实时验证。connectivity_search 还会查找共享同一连接层的化合物（骨架相同，但立体化学/盐/同位素不同）——当你想查找“任意名称/形式下的同一分子”而非精确匹配时，可使用此工具。已在阿司匹林的 InChIKey（BSYNRYMUTXBXSQ-UHFFFAOYSA-N）上实时验证：两个工具都返回了真实的跨数据库记录，其中包括 Wikipedia 链接。

串联标识符工作流（真实值）： NCICACTUS_resolve(identifier="aspirin", representation="smiles") → CC(=O)Oc1ccccc1C(O)=O → 使用 representation="stdinchikey" 解析同一标识符 → 返回真实结果 "InChIKey=BSYNRYMUTXBXSQ-UHFFFAOYSA-N"（注意 InChIKey= 前缀——已实时验证；将不带前缀的键传给其他工具前，请先去掉此前缀）→ 将不带前缀的 BSYNRYMUTXBXSQ-UHFFFAOYSA-N 传入 UniChem_search_compound，获取跨数据库 ID → 如有需要，使用 PubChem_get_CID_by_SMILES 重新关联到 PubChem。

化学信息学计算与结构可视化

如需进行属性查询之外的计算和渲染：

• RDKit_pharmacophore_features——通过 SMARTS 匹配从 SMILES 中提取药效团特征中心（HBD、HBA、芳香性、疏水性等）。已在阿司匹林（CC(=O)Oc1ccccc1C(=O)O）上实时验证：返回 1 个 HBD 及其原子索引，方法说明为 "SMARTS-based pharmacophore features"。
• RDKit_matched_molecular_pair——给定两个 SMILES，查找二者之间的单切 MMP 转换（Hussain-Rea 算法），并计算它们的 Tanimoto 相似度——适用于分析“哪一个单一取代基会将化合物 A 转变为化合物 B”（SAR 分析）。
• visualize_molecule_2d——将 2D 结构（来源可以是 SMILES、InChI 或分子名称）渲染为 PNG/SVG/交互式 HTML。已实时验证：成功时会返回嵌入式 HTML 可视化结果。
• visualize_molecule_3d——通过 RDKit + py3Dmol 渲染 3D 结构。需要安装 py3Dmol——已实时验证，未安装时，工具会返回明确的 {"status": "error", ...: "py3Dmol is not installed. Please install it with: pip install py3Dmol"}，而不会崩溃；在断定可视化请求因其他原因失败前，请先检查这一点。

工具参考

PubChem：PubChem_get_CID_by_compound_name、PubChem_get_CID_by_SMILES、PubChem_get_compound_properties_by_CID、PubChem_get_compound_2D_image_by_CID、PubChemBioAssay_get_assay_summary、PubChemTox_get_acute_effects、PubChem_get_associated_patents_by_CID、PubChem_search_compounds_by_similarity、PubChem_search_compounds_by_substructure

ChEMBL：ChEMBL_search_drugs、ChEMBL_get_molecule、ChEMBL_get_activity、ChEMBL_get_target、ChEMBL_search_targets、ChEMBL_search_assays

名称解析：OPSIN_name_to_structure（参数 name）——可确定性地将 IUPAC／系统名称解析为 SMILES／InChI／InChIKey；无需往返查询数据库，即可将系统名称解析为结构，是首选方法。商品名和俗名会返回 parsed=false（此类名称请使用 PubChem 名称查询）。

标识符解析与交叉引用：NCICACTUS_resolve、UniChem_search_compound、UniChem_connectivity_search、UniChem_list_sources

化学信息学与可视化：RDKit_pharmacophore_features、RDKit_matched_molecular_pair、visualize_molecule_2d、visualize_molecule_3d