ChemGlyph

ChemGlyph

AI エージェント向けの、出版品質の化学構造式および反応式の描画です。 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 を返します。

スタイル

3 種類のスタイルを、同じ分子（安息香酸、カフェイン、（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 手前で止まります。同じスタイルで描いた 2 つの構造は、結合の長さとラベルのサイズが同じなので、論文上で位置が揃います。screen はこの形状を維持しながら O、N、S、Cl に色を付けます（クラシック CPK）。textbook は線幅が 0.8 pt、ラベルが 12 pt です。

SVG のサイズはポイント単位で指定され、transparent=False でない限り背景は透明です。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 テキストとして整形されているため、H2SO4 ではなく H₂SO₄ を渡してください。ChemGlyph はテキストから化学式を解析しません。スキーマ全体（複数段階の連鎖、平衡矢印と逆反応矢印、折り返し）については、docs/reaction_schema.md を参照してください。

アスピリンのデモでは、2 段階の合成経路を出力します。

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

検証

validate_structure は解析エラーを報告し、4 種類の簡易修正を適用します。不一致の括弧と環の閉じ忘れについては（推測で補わず）報告し、小文字の芳香族原子のケクレ化失敗と、形式上の [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から1つの構造を描画するよう求められた場合	PNG画像と、分子式、MW、警告（リクエストがあればSVGソース）
render_reaction	反応または合成経路について尋ねられた場合	反応スキームのPNG画像
validate_structure	SMILESの形式が不正な可能性があり、修正が必要な場合	検証レポートのJSON
parse_name	SMILESではなく、「aspirin」のような名称が入力された場合	正準SMILESまたはエラー

クライアントについて知っておくべきことが1つあります。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個にはレイアウト上の問題があり、警告として報告されます。 ヘリセンとフラーレン（平面図を作成できない）、BINAP、モルヒネ、コデイン、 パクリタキセル、ビンブラスチン、テトロドトキシン（縮合環が密集）、および シクロデキストリン、アムホテリシンB、フォルスコリン、リファンピシン、 シタグリプチン（ラベルの配置が混み合う）です。独自の座標を含む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を継承します。