ChemGlyph

ChemGlyph

面向 AI Agent 的出版级化学结构和反应渲染。 ChemGlyph 是化学领域的 KaTeX：一个渲染层、一个验证层，以及一个构建于 RDKit 之上的 MCP 接口。

安装

pip install chemglyph

渲染分子

import chemglyph

result = chemglyph.render_molecule("c1ccccc1")  # benzene
open("benzene.svg", "w").write(result.data)

render_molecule 接受 SMILES、InChI 或 molblock，并返回 SVG（或 PNG），以及 canonical_smiles、mol_formula、mol_weight 和 warnings。

样式

三种样式，呈现相同的分子（苯甲酸、咖啡因、(S)-布洛芬）：

chemglyph.render_molecule(smiles)  # screen: coloured O, N, S, Cl for screens and chat
chemglyph.render_molecule(smiles, style="acs1996")  # black, ACS journal sizes
chemglyph.render_molecule(smiles, style="textbook")  # heavier lines for teaching

每种样式都按同一物理比例绘制。acs1996 遵循 ACS Document 1996 设置：键长 14.4 pt、线宽 0.6 pt、标签 10 pt，且键端与标签相距 1.6 pt。使用相同样式绘制的两个结构具有相同的键长和标签大小，因此可以在论文中对齐。screen 保持这种几何尺寸，并为 O、N、S 和 Cl 着色（经典 CPK）；textbook 使用 0.8 pt 线宽和 12 pt 标签。

除非设置 transparent=False，否则 SVG 的尺寸以点为单位，背景透明。fmt="png" 接受 dpi 参数，fmt="pdf" 输出供 LaTeX 使用的矢量 PDF，fmt="mol" 则输出包含绘制坐标的 molfile，供结构编辑器使用。

result = chemglyph.render_molecule("CC(=O)Oc1ccccc1C(=O)O", style="acs1996")
result.report  # {'bond_length_pt': [14.4, 14.4], 'label_clearance_pt': 1.6, ...}
png = chemglyph.render_molecule(smiles, style="acs1996", fmt="png", dpi=600)

0.1 版本中的样式名称（acs、modern、textbook-cn）仍可使用，分别映射到 acs1996、screen 和 textbook，并会给出弃用警告；这些名称将在 1.0 版本中移除。

这些数值由测试套件在渲染输出中测得（tests/test_profiles.py）。

化合物编号

chemglyph.render_molecule(smiles, style="acs1996", number="12a")

编号以粗体、标签大小显示，并居中放置在结构下方半个键长处，与 ACS 期刊中的排版一致。编号也会存储在嵌入式结构中（molfile 标题行），因此重新读取时，图中仍会标明所示化合物。

缩写

chemglyph.render_molecule(smiles, abbreviate=True)  # Boc, Ts, TBS, OAc, NHBoc, ...
chemglyph.render_molecule(smiles, abbreviate=["Ph", "t-Bu", "CO2Me"])

abbreviate=True 会将保护基和活化基绘制为标签，采用 J. Org. Chem. 标准缩写列表中的拼写。酰基、氨基甲酸酯和苄基仅在杂原子上缩写，因此苄基侧链仍显示为 CH2 和一个环；甲硅烷基和磺酰基也会在碳原子上缩写。连接到末端 O 或 NH 的基团会与其标签合并（OTs、BocHN）。如果标签会与其他标签或键重叠，则会改为完整绘制。

这只会改变绘图。嵌入式结构、化合物身份和名称检查都会使用所有原子；fmt="mol" 会将缩写保留为 SUP 基团，结构编辑器会将其显示为标签，并且可以展开。

已检查的图形

使用这些配置文件生成的图形会自行检查并携带其结构：

result = chemglyph.render_molecule(smiles, style="acs1996", name="cholesterol")
result.report["verified"]  # bonds and labels drawn, wedges right, structure reads back
result.report["name_check"]["status"]  # match, stereo_differs, mismatch, or unchecked
chemglyph.read_structure(result.data)  # the RDKit molecule embedded in the SVG or PNG

如果名称对应的是另一种结构，就会发出警告，从而在图形进入稿件之前捕获 AI 模型生成的错误 SMILES。名称可通过内置中文词典或 OPSIN 离线解析。

反应

spec = {
    "steps": [
        {
            "reactants": ["OC(=O)c1ccccc1O", "CC(=O)OC(C)=O"],
            "products": ["CC(=O)Oc1ccccc1C(=O)O", "CC(=O)O"],
            "conditions": {"above": "H₂SO₄ (cat.)", "below": "rt, 15 min"},
            "yield": "89%",
            "arrow": "forward",
        }
    ],
    "style": "screen",
}
svg = chemglyph.render_reaction(spec)

反应式目前尚未按固定比例绘制；这将在路线图的反应阶段实现。

反应条件是预先格式化的 Unicode 文本，因此应传入 H₂SO₄，而不是 H2SO4。ChemGlyph 不会从文本中解析化学式。完整架构（多步链、平衡箭头和逆合成箭头、自动换行）见 docs/reaction_schema.md。

阿司匹林示例会写入一条两步路线：

python examples/aspirin_synthesis.py  # writes examples/aspirin_synthesis.svg

验证

validate_structure 会报告解析错误，并应用四种快速修复：未匹配的括号和环闭合（只报告，不猜测）、小写芳香原子的凯库勒化失败，以及通过形式电荷 [N+] 处理的氮价态错误。其他所有信息都会原样传递 RDKit 的消息。

report = chemglyph.validate_structure("c1cccc1")
report.fixes[0].description  # 'lowercase aromatic atoms could not be kekulized...'
report.fixes[0].fixed_smiles  # 'C1CCCC1'

命名

chemglyph.parse_name("aspirin")  # 'CC(=O)Oc1ccccc1C(=O)O'

英文 IUPAC 名称和常用名称可通过 OPSIN 离线解析 （pip install 'chemglyph[opsin]'，并需要 Java 运行时）。中文名称使用 内置词典；对于词典中没有的名称，库 API 接受一个翻译器可调用对象：

chemglyph.parse_name("阿司匹林")  # 'CC(=O)Oc1ccccc1C(=O)O'
chemglyph.parse_name("六甲基苯", translator=to_english)

ChemGlyph 本身绝不会调用在线服务，包括翻译服务。

MCP 服务

运行捆绑的控制台脚本（stdio 传输）：

chemglyph-mcp

Claude Desktop 注册配置（macOS： ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "chemglyph": {
      "command": "chemglyph-mcp"
    }
  }
}

工具	适用场景	返回内容
render_molecule	用户要求从 SMILES/InChI/molblock 绘制一个结构	PNG 图像以及分子式、MW、警告（可按需提供 SVG 源文件）
render_reaction	用户要求绘制反应或合成路线	反应方案的 PNG 图像
validate_structure	SMILES 可能格式错误，需要修复	验证报告 JSON
parse_name	用户提供了类似 "aspirin" 的名称，而不是 SMILES	规范 SMILES 或错误信息

关于客户端，有一点需要了解。包括 LM Studio 在内的某些 MCP 客户端只会将工具结果中的文本部分传递给模型，绝不会显示附加图像。渲染工具会将 PNG 写入 ~/Downloads/chemglyph/，并在文本中返回该路径，因此你始终可以自行打开文件。如果模型声称已渲染图像，但没有任何内容显示，请让它提供保存路径，而不是让它手动重绘结构。

基准测试

benchmarks/ 包含固定的 20 个分子盲测，以及一个生成器，可生成经过打乱并带编号的 PNG/SVG 图像和 answer_key.json：

python benchmarks/generate_blind_test.py --seed 1234

测试协议、A/B 图集生成器、运行手册和评分器均位于 benchmarks/；通过门槛和测试流程见 benchmarks/RUNBOOK.md。任何人都可以运行测试并贡献结果。

目前尚未针对 ChemDraw 进行盲测，因此不声称有任何对比结果。每次渲染都会在生成时进行检查（参见“已检查的图像”），并且每次提交都会运行 tests/test_corpus.py，渲染一个包含 416 个结构的语料库。

已知限制

• 416 个语料库结构中有 14 个存在布局问题，并会报告警告：helicene 和 fullerene（无法平面绘制）；BINAP、morphine、codeine、paclitaxel、vinblastine、tetrodotoxin（多环结构拥挤）；以及 cyclodextrins、amphotericin B、forskolin、rifampicin、sitagliptin（标签位置拥挤）。传入带有自定义坐标的 molfile 可避免这些问题。列表见 tests/test_corpus.py。
• 反应方案仍使用 0.1 渲染器，而非固定比例。
• 尚未实现完整的中文名称到结构的自动解析；中文名称通过小型内置词典和可选的翻译器钩子解析。英文名称通过 OPSIN 解析。

路线图

工作分阶段推进；每个阶段满足退出标准后，都会作为次要版本发布。计划、ChemGlyph 遵循的标准以及质量门槛见 docs/SPEC.md；发行说明见 CHANGELOG.md。

• 0.1.3：修复问题并规范发布流程。
• 0.2（已发布）：正确绘制分子。所有绘图采用统一的固定物理比例；依据已发布标准测定样式配置文件（首先采用 ACS Document 1996 设置）；每次渲染均附带验证报告；自动布局检查；支持缩写、化合物编号、PDF 和 MOL 输出。
• 0.3：支持 mhchem 语法的分子式和方程式，并检查原子和电荷平衡。
• 0.4：反应方案采用统一比例，并提供用于化合物和图形的对象 API。
• 0.5：将机理（弯曲）箭头锚定到原子和键上。

非目标

不提供结构编辑器 GUI（不与 Ketcher/ChemDraw 竞争）、不提供 3D 可视化、不提供逆合成或性质预测、不查询在线数据库，也不自动生成机理。完整列表见项目规范。

开发

python -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/ruff check . && .venv/bin/ruff format . && .venv/bin/pytest

Python 3.11+、RDKit 2024.9+，MIT 许可证。所有错误均继承自 chemglyph.errors.ChemGlyphError。