Chemistry Query Agent v1.4.1

概述

全栈化学工具包，整合 PubChem 数据检索与 RDKit 分子处理、可视化、分析、逆合成分析及合成路线规划能力。所有输出均为结构化 JSON 格式，便于下游任务链式调用。支持按需生成 PNG/SVG 图像。

核心能力：

• PubChem 化合物查询（基本信息、结构、合成参考文献、相似性搜索）
• RDKit 分子性质计算（分子量 MW、logP、极性表面积 TPSA、氢键供体/受体数 HBD/HBA、可旋转键数、芳香环数）
• 2D 分子结构可视化（PNG/SVG 格式）
• 基于 BRICS 的递归逆合成分析（支持深度控制）
• 多步合成路线规划
• 基于 SMARTS 模板的正向反应模拟
• Morgan 指纹生成及相似性/子结构搜索
• 21 种命名反应模板（Suzuki、Heck、Grignard、Wittig、Diels-Alder 等）

快速上手

# PubChem 化合物信息查询
exec python scripts/query_pubchem.py --compound "aspirin" --type info

# 从 SMILES 计算分子性质
exec python scripts/rdkit_mol.py --smiles "CC(=O)Oc1ccccc1C(=O)O" --action props

# 逆合成分析
exec python scripts/rdkit_mol.py --target "CC(=O)Oc1ccccc1C(=O)O" --action retro --depth 2

# 完整链式调用（名称 → 性质 + 绘图 + 逆合成）
exec python scripts/chain_entry.py --input-json '{"name": "caffeine", "context": "user"}'

脚本说明

scripts/query_pubchem.py

调用 PubChem REST API，支持自动将化合物名解析为 CID，并内置超时处理机制。

--compound  --type  [--format smiles|inchi|image|json] [--threshold 80]

• info：返回分子式、分子量、IUPAC 名称、InChIKey（JSON 格式）
• structure：返回 SMILES、InChI、图像 URL 或完整 JSON
• synthesis：返回化合物的同义词及合成相关参考文献
• similar：基于 2D 指纹匹配的相似化合物（返回 Top 20）

scripts/rdkit_mol.py

基于 RDKit 的化学信息学引擎，自动通过 PubChem 解析化合物名称。

--smiles  --action 

scripts/chain_entry.py

标准 Agent 链式接口，接受 {"smiles": "...", "context": "..."} 或 {"name": "...", "context": "..."} 输入，统一返回包含分子性质、可视化图像及逆合成结果的 JSON 对象。

python scripts/chain_entry.py --input-json '{"name": "sotorasib", "context": "user"}'

输出 Schema：

{
  "agent": "chemistry-query",
  "version": "1.4.0",
  "smiles": "",
  "status": "success|error",
  "report": {"props": {...}, "draw": {...}, "retro": {...}},
  "risks": [],
  "viz": ["path/to/image.png"],
  "recommend_next": ["pharmacology", "toxicology"],
  "confidence": 0.95,
  "warnings": [],
  "timestamp": "ISO8601"
}

scripts/templates.json

包含 21 种命名反应模板的 JSON 文件，每个模板均含 SMARTS 表达式、预期收率、反应条件及参考文献。涵盖 Suzuki、Heck、Buchwald-Hartwig、Grignard、Wittig、Diels-Alder、Click、Sonogashira、Negishi 等反应。

链式调用示例

1. 名称 → 完整分子档案：使用 chain_entry.py 输入 {"name": "ibuprofen"}，获取分子性质、结构图与逆合成路径
2. 化学 → 药理学：输出可直接作为 pharma-pharmacology-agent 的输入
3. 逆合成 + 可视化：获取前体分子后，逐一绘制其 2D 结构
4. Suzuki 反应测试：--action react --reactants "c1ccccc1Br c1ccccc1B(O)O" --smarts "[c:1][Br:2].[c:3][B]([c:4])(O)O>>[c:1][c:3]"

已验证环境

所有功能均已通过 RDKit 2024.03+ 全流程端到端验证：

资源

• references/api_endpoints.md — PubChem API 接口文档与速率限制说明
• scripts/rdkit_reaction.py — 已弃用的反应模块（遗留）
• scripts/chembl_query.py、scripts/pubmed_search.py、scripts/admet_predict.py — 扩展查询模块

scripts/advanced_chem.py

高级化学信息学引擎，提供 6 项 Tier 1 级能力。

--action  --smiles  [options]

使用示例：

# 标准化盐形式
python scripts/advanced_chem.py --action standardize --smiles "[Na+].CC(=O)[O-]"

# 计算全部描述符（217+ 项）
python scripts/advanced_chem.py --action descriptors --smiles "CC(=O)Oc1ccccc1C(=O)O" --descriptor_set all

# 分析一组分子的支架多样性
python scripts/advanced_chem.py --action scaffold --target_smiles "CC(=O)Oc1ccccc1C(=O)O,CN1C=NC2=C1C(=O)N(C(=O)N2C)C,CC(C)Cc1ccc(cc1)C(C)C(=O)O"

# 计算阿司匹林与水杨酸的最大公共子结构（MCS）
python scripts/advanced_chem.py --action mcs --target_smiles "CC(=O)Oc1ccccc1C(=O)O,c1ccccc1C(=O)O"

# 匹配分子对分析（MMPA）
python scripts/advanced_chem.py --action mmpa --target_smiles "c1ccc(CC(=O)O)cc1,c1ccc(CCC(=O)O)cc1"

# 化学空间 PCA 可视化
python scripts/advanced_chem.py --action chemspace --target_smiles "CC(=O)Oc1ccccc1C(=O)O,CN1C=NC2=C1C(=O)N(C(=O)N2C)C,c1ccccc1" --method pca --output space.png

更新日志

v2.0.0（2026-02-28）

• 新增：advanced_chem.py，集成 6 项 Tier 1 级化学信息学能力
  • 分子标准化与互变异构体枚举（盐去除、电荷归一化、规范互变异构体）
  • 扩展描述符（217+ RDKit 描述符、QED、SA Score、Lipinski、Veber 规则）
  • 支架分析（Murcko 支架、通用支架、多样性比率、R-基团分解）
  • 最大公共子结构（rdFMCS，支持每分子覆盖率统计）
  • 匹配分子对分析（rdMMPA 片段化与变换检测）
  • 化学空间可视化（PCA/t-SNE/UMAP，基于 matplotlib 的散点图）
• 依赖项：新增 scikit-learn、matplotlib

v1.4.1（2026-02-25）

• 安全加固：对所有子进程调用（SMILES、化合物名、输出路径等）实施输入净化
• 新增 _sanitize_input() —— 对所有用户输入施加长度限制并拒绝空字节
• 新增 _sanitize_output_path() —— 阻止路径遍历、限制文件扩展名、禁止任意文件写入
• 在 resolve_target() 中增加 shell 元字符过滤
• 在 chem_ui.py 中于子进程调用前，使用 RDKit 对 SMILES 进行校验
• 在 query_pubchem.py 中增加化合物输入校验（长度与空字节检查）
• 为 resolve_target() 中的 PubChem 子进程调用添加超时机制
• 修复 VirusTotal 将参数注入向量标记为“可疑”的问题

v1.4.0（2026-02-14）

• 修复 PubChem SMILES/InChI 接口（property/CanonicalSMILES/TXT）
• 修复 chain_entry.py 中 HTML 实体损坏问题
• 修复 brics_retro 对 BRICSDecompose 字符串输出的解析逻辑
• 为所有 PubChem 请求添加 15 秒超时限制
• 增强对无效 SMILES 和空输入的容错错误处理
• 更新 chain 输出版本号与 Schema 定义
• 完成全流程端到端测试

v1.3.0

• 修复 RDKit 分子性质计算中可能出现的 NoneType 异常；对无效 SMILES 返回优雅错误
• 修复 react 功能：修正 ReactionFromSmarts 导入逻辑
• 所有 RDKit 操作均支持通过 PubChem 自动解析化合物名称

v1.2.0

• 新增 BRICS 逆合成分析能力 + 21 种命名反应模板库
• 新增多步合成路线规划功能