@delta-infra/cli 1.0.73 → 1.0.74

package/skills/pubchem/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: pubchem
+description: 当用户给出化学品、分子、药物名称并询问 CID、同义词、分子式、分子量、SMILES、InChI、IUPAC 名、XLogP、TPSA 或供受体数量时使用；也用于在 RDKit 前批量把名称解析为 SMILES。所有实时请求只走 Delta CLI wrapper，并以当前 WORKSPACE_ROOT 下的有界 JSON 作为权威交接产物。
+---
+
+# PubChem 服务
+
+## 强制执行规则
+
+1. 第一个且唯一实时执行工具是 `python_repl`，直接执行
+   `$SKILLS_ROOT/delta-science/scripts/invoke.py`。
+   调用 `python_repl` 时工具参数对象只能包含 `code`；禁止传入 `deps`、
+   `dependencies`、`packages` 或其他参数。
+2. `SKILLS_ROOT` 只通过 `os.environ["SKILLS_ROOT"]` 读取；禁止 Bash、
+   `list_dir/read_file/which/where/ls`、wrapper 检查和路径探测。
+3. 禁止执行字面命令 `CLI/cli/delta-cli`，禁止 curl、requests、httpx、浏览器、
+   PUG-REST 和本地替代。
+4. wrapper 已解包所有 envelope，业务结果直接位于 `r["native"]`；禁止
+   `native.data` 和递归找值。
+5. 不先调用 health/schema，不为“验证”重复同一请求。
+
+## 单化合物默认模板
+
+```python
+import json, os, subprocess, sys
+from pathlib import Path
+wrapper=os.path.join(os.environ["SKILLS_ROOT"],"delta-science","scripts","invoke.py")
+payload={"identifier":"aspirin","namespace":"name"}
+p=subprocess.run([sys.executable,wrapper,"--tool","pubchem","--endpoint","compound-summary",
+                  "--data-json",json.dumps(payload)],capture_output=True,text=True,
+                 encoding="utf-8",errors="replace",shell=False,timeout=150)
+if p.returncode != 0: raise RuntimeError(p.stderr or p.stdout)
+r=json.loads(p.stdout)
+if r.get("ok") is not True or r.get("transport")!="delta-cli": raise RuntimeError(r)
+n=r["native"]; x=n["properties"]
+out={"transport":r["transport"],"endpoint":r["endpoint"],"valid":n["valid"],
+     "cid":n.get("cid") or x.get("CID"),"canonical_smiles":x.get("CanonicalSMILES"),
+     "molecular_formula":x.get("MolecularFormula"),
+     "molecular_weight":x.get("MolecularWeight")}
+output_path=Path(os.environ["WORKSPACE_ROOT"])/"pubchem_result.json"
+output_path.write_text(json.dumps(out,ensure_ascii=False,indent=2),encoding="utf-8")
+print(json.dumps({"output_ref":str(output_path),"result":out},ensure_ascii=False))
+```
+
+`out` 只保留用户要求的字段。逐字复制返回值：不得改写等价 SMILES、给公式加排版、
+给数值加单位、添加 URL/链接/用途/机制或未请求属性。
+
+## operation 选择
+
+- 一个名称的基础信息：一次 `compound-summary`。
+- 两个及以上名称：一次 `compound-batch-summary`，body 只用
+  `{"identifiers":[...],"namespace":"name"}`。
+- 只解析 CID、只查属性或同义词：分别使用 `compound-resolve-cids`、
+  `compound-properties`、`compound-synonyms`。
+- 每个 operation 的准确情景、payload 和投影见
+  `references/operations.md`；复杂字段再看 `references/endpoints.md`。
+
+批量结果从 `native.results[*]` 读取，原标签是 `input`，化合物字段在嵌套
+`properties`。SMILES 回退顺序固定为：
+
+```text
+CanonicalSMILES || ConnectivitySMILES || SMILES || IsomericSMILES
+```
+
+无机材料化学式、组成和式量路由 pymatgen；PubChem not_found 原样保留，不编造 CID
+或本地补算。PubChem `XLogP` 与 RDKit `MolLogP` 不得互换。
+
+成功写入有界 JSON 后，用其中的原始字符串和数值构造无 Markdown、无单位的最终文本，
+并立即调用 `step_finish` 恰好一次。例如：
+
+```text
+【最终答案，必须逐字转发】
+CID: 2244
+规范 SMILES: CC(=O)OC1=CC=CC=C1C(=O)O
+分子式: C9H8O4
+分子量: 180.16
+```
+
+`status="done"`，`summary` 第一行必须逐字为 `【最终答案，必须逐字转发】`，其余行
+逐字使用当前 out；`output_ref` 必须是刚写入的绝对 `pubchem_result.json` 路径。
+不得使用示例固定值。缺少首行或 output_ref 时不得结束步骤。
+Skill 自身的 final_response 和外层 Memento 都必须逐字复制 summary，包括大小写和标点，
+不得改成 Markdown/LaTeX、另一种等价 SMILES、添加单位、链接或说明。失败时调用
+`step_finish(status="failed", summary=<原始错误短摘要>)`。调用后禁止自由文本和工具。
+
+具名 Skill 返回后，外层若需要核验只能对 `output_ref` 使用一次原子 `read_file`；禁止
+`python_repl`、`list_dir`、路径探测或再次调用 PubChem/Science。该文件只是当前会话的
+内部证据交接，不是用户要求的额外交付物。

package/skills/pubchem/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "PubChem ?????"
+  short_description: "?? Delta CLI ????????????????"
+  default_prompt: "?? $pubchem ????????????????"

package/skills/pubchem/references/endpoints.md

@@ -0,0 +1,122 @@
+# PubChem Endpoint Reference
+
+在 Memento 中只能通过 `delta-science/scripts/invoke.py` 调用。wrapper 已解包服务
+信封，因此以下文档所说的业务 `data` 在 wrapper 结果中就是 `result["native"]`
+顶层；禁止再读取 `result["native"]["data"]`。本文件中的 URL 只用于说明 endpoint
+schema，不授权直接 HTTP。
+
+All paths are relative to `http://111.2.199.31:52317/api/v1`.
+
+Namespaces: `cid`, `name`, `smiles`, `inchi`, `inchikey`, `formula`.
+
+## Health
+
+`GET /chem/pubchem/health`
+
+## Resolve CIDs
+
+`POST /chem/pubchem/compound/resolve-cids`
+
+```json
+{"identifier": "aspirin", "namespace": "name", "max_records": 20}
+```
+
+`max_records`: 1-100.
+
+## Properties
+
+`POST /chem/pubchem/compound/properties`
+
+```json
+{
+  "identifier": "2244",
+  "namespace": "cid",
+  "properties": ["MolecularFormula", "MolecularWeight", "CanonicalSMILES", "IUPACName"]
+}
+```
+
+Allowed properties include `MolecularFormula`, `MolecularWeight`,
+`CanonicalSMILES`, `IsomericSMILES`, `SMILES`, `ConnectivitySMILES`,
+`IUPACName`, `InChI`, `InChIKey`, `XLogP`, `TPSA`, `HBondDonorCount`,
+`HBondAcceptorCount`, `RotatableBondCount`, `ExactMass`, `MonoisotopicMass`,
+`Charge`, `HeavyAtomCount`, `Complexity`, `CovalentUnitCount`,
+`DefinedAtomStereoCount`, `UndefinedAtomStereoCount`, `DefinedBondStereoCount`,
+`UndefinedBondStereoCount`, and `IsotopeAtomCount`.
+
+## Synonyms
+
+`POST /chem/pubchem/compound/synonyms`
+
+```json
+{"identifier": "2244", "namespace": "cid", "max_synonyms": 50}
+```
+
+`max_synonyms`: 1-500.
+
+## Summary
+
+`POST /chem/pubchem/compound/summary`
+
+```json
+{
+  "identifier": "aspirin",
+  "namespace": "name",
+  "properties": ["MolecularFormula", "MolecularWeight", "CanonicalSMILES", "IUPACName"],
+  "synonym_limit": 20
+}
+```
+
+`synonym_limit`: 0-100. Use this endpoint for general compound lookup because
+it resolves CID, selected properties, and synonyms in one call.
+
+Response fields include `valid`, `cid`, `properties`, `properties_raw`,
+`aliases`, `synonyms`, and `metadata`. Numeric properties are coerced to JSON
+numbers when possible. Requested SMILES aliases are filled when PubChem returns
+an equivalent key such as `ConnectivitySMILES`.
+
+## Batch Summary
+
+`POST /chem/pubchem/compound/batch-summary`
+
+```json
+{
+  "identifiers": ["aspirin", "ibuprofen", "caffeine"],
+  "namespace": "name",
+  "properties": ["MolecularFormula", "MolecularWeight", "CanonicalSMILES", "XLogP", "TPSA"],
+  "synonym_limit": 5
+}
+```
+
+Limits: 1-100 identifiers. The response preserves input order and includes
+per-item errors:
+
+```json
+{
+  "valid": false,
+  "namespace": "name",
+  "properties_requested": ["CanonicalSMILES"],
+  "results": [
+    {
+      "input": "aspirin",
+      "valid": true,
+      "cid": 2244,
+      "properties": {
+        "CanonicalSMILES": "CC(=O)Oc1ccccc1C(=O)O",
+        "ConnectivitySMILES": "CC(=O)Oc1ccccc1C(=O)O",
+        "_aliases": {"CanonicalSMILES": "ConnectivitySMILES"},
+        "properties_raw": {}
+      },
+      "properties_raw": {},
+      "aliases": {"CanonicalSMILES": "ConnectivitySMILES"},
+      "synonyms": []
+    },
+    {
+      "input": "bad-name",
+      "valid": false,
+      "error": "not found"
+    }
+  ],
+  "count": 2,
+  "failed_count": 1
+}
+```

package/skills/pubchem/references/operations.md

@@ -0,0 +1,41 @@
+# PubChem operation 契约
+
+先使用 `SKILL.md` 的唯一 wrapper 模板。下面每行都是对应 operation 的最小设置；
+wrapper 成功后的业务结果均为 `r["native"]`，不是 `native.data`。执行一次后调用
+`step_finish`，不得重复调用。
+
+## health
+
+- 情景：用户明确询问 PubChem 服务是否可用。
+- 代码：`endpoint="health"; data=None; params=None`
+- 投影：只保留 `status`、可用性、metadata、limits、warnings 中实际存在的字段。
+
+## compound-resolve-cids
+
+- 情景：把名称、SMILES、InChI 等标识符解析为 CID 列表。
+- 代码：`endpoint="compound-resolve-cids"; data={"identifier":"aspirin","namespace":"name","max_records":20}; params=None`
+- 投影：输入标签、有效性、CID 列表和错误。
+
+## compound-properties
+
+- 情景：已有标识符，只要求指定 PubChem 属性。
+- 代码：`endpoint="compound-properties"; data={"identifier":"aspirin","namespace":"name","properties":["MolecularFormula","MolecularWeight"]}; params=None`
+- 投影：只复制本次返回的 CID、请求属性、aliases、valid/error。
+
+## compound-synonyms
+
+- 情景：查询一个化合物的同义词。
+- 代码：`endpoint="compound-synonyms"; data={"identifier":"aspirin","namespace":"name","max_synonyms":5}; params=None`
+- 投影：CID、有效性和最多用户要求数量的 synonyms。
+
+## compound-summary
+
+- 情景：一个已命名分子的 CID、SMILES、分子式、分子量等基础属性。
+- 代码：`endpoint="compound-summary"; data={"identifier":"aspirin","namespace":"name"}; params=None`
+- 投影：`native.valid`、`native.cid` 与 `native.properties` 中用户要求的键。
+
+## compound-batch-summary
+
+- 情景：一次解析两个或更多名称，供后续比较或 RDKit 使用。
+- 代码：`endpoint="compound-batch-summary"; data={"identifiers":["aspirin","caffeine"],"namespace":"name"}; params=None`
+- 投影：`native.results[*]` 的 `input`、valid/error 及嵌套 `properties`；不得加 `properties` 或 `synonym_limit` 请求字段。

package/skills/pymatgen/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: pymatgen
+description: 当用户需要解析材料化学式与组成、计算式量、解析或总结 CIF/POSCAR/JSON/CSSR/XSF 晶体结构、转换结构格式或分析空间群和对称性时使用。所有实时请求只走 Delta CLI wrapper；无机化学式优先使用本 Skill，不用 PubChem 或本地元素表替代。
+---
+
+# pymatgen 服务
+
+## 强制规则
+
+- 第一个且唯一实时执行工具是 `python_repl`；直接执行
+  `$SKILLS_ROOT/delta-science/scripts/invoke.py`，tool 固定为 `pymatgen`。
+- `python_repl` 工具参数只能包含 `code`，禁止 `deps/dependencies/packages`。
+- `SKILLS_ROOT` 只通过 `os.environ` 读取。禁止 Bash、目录/路径探测、字面 CLI
+  命令、直接 HTTP 和本地 pymatgen。
+- wrapper 成功后的业务结果是 `r["native"]` 顶层，禁止 `native.data`。
+- 结构接口必须发送完整结构文本，不能发送本地文件路径；只支持
+  `cif/poscar/json/cssr/xsf`，不接收 LAMMPS data/dump。
+
+## wrapper 模板
+
+```python
+import json, os, subprocess, sys
+wrapper=os.path.join(os.environ["SKILLS_ROOT"],"delta-science","scripts","invoke.py")
+p=subprocess.run([sys.executable,wrapper,"--tool","pymatgen","--endpoint",endpoint,
+                  "--data-json",json.dumps(payload)],capture_output=True,text=True,shell=False)
+if p.returncode != 0: raise RuntimeError(p.stderr or p.stdout)
+r=json.loads(p.stdout)
+if r.get("ok") is not True or r.get("transport")!="delta-cli": raise RuntimeError(r)
+n=r["native"]
+print(json.dumps(out,ensure_ascii=False))
+```
+
+`out` 必须从 `n` 投影，不得用记忆补值。
+
+## operation 选择
+
+- `health`：明确健康检查；省略 `--data-json`。
+- `composition-parse`：`{"formula":"LiFePO4","format":"formula"}`。
+- `structure-parse`：`{"input":结构文本,"format":"cif","primitive":false}`。
+- `structure-summary`：同上，用于 formula、density、volume、lattice、species。
+- `structure-convert`：`{"input":结构文本,"input_format":"cif","output_format":"poscar","primitive":false}`。
+- `structure-symmetry`：`{"input":结构文本,"format":"cif","primitive":false,"symprec":0.01,"angle_tolerance":5.0}`。
+
+详细 native 字段见 `references/endpoints.md`。一个请求只调用所需 operation；无机式量
+只报告当前 native 的 `weight`，PubChem not_found 不得改写或本地补算。
+
+成功打印有界 JSON 后立即调用 `step_finish(status="done", summary=<同一 JSON>)`
+恰好一次；失败时调用 `step_finish(status="failed", summary=<原始错误短摘要>)`。
+调用后不得输出自由文本或使用其他工具。

package/skills/pymatgen/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "pymatgen ????"
+  short_description: "?? Delta CLI ???????????????"
+  default_prompt: "?? $pymatgen ??????????????"

package/skills/pymatgen/references/endpoints.md

@@ -0,0 +1,68 @@
+# pymatgen Endpoint Reference
+
+All paths are relative to `http://111.2.199.31:52317/api/v1`.
+
+## Health
+
+`GET /chem/pymatgen/health`
+
+## Composition Parse
+
+`POST /chem/pymatgen/composition/parse`
+
+```json
+{"formula": "LiFePO4", "format": "formula"}
+```
+
+Key response fields in `data`: `valid`, `formula`, `reduced_formula`,
+`alphabetic_formula`, `anonymous_formula`, `chemical_system`,
+`number_of_atoms`, `weight`, `element_amounts`, `atomic_fractions`,
+`weight_fractions`, `error`.
+
+## Structure Parse / Summary
+
+`POST /chem/pymatgen/structure/parse`
+
+`POST /chem/pymatgen/structure/summary`
+
+```json
+{"input": "<CIF text>", "format": "cif", "primitive": false}
+```
+
+Input formats: `cif`, `poscar`, `json`, `cssr`, `xsf`.
+
+Summary fields include `formula`, `reduced_formula`, `chemical_system`,
+`nsites`, `nelements`, `density`, `volume`, `lattice`, `element_amounts`, and
+`species`.
+
+## Structure Convert
+
+`POST /chem/pymatgen/structure/convert`
+
+```json
+{
+  "input": "<CIF text>",
+  "input_format": "cif",
+  "output_format": "poscar",
+  "primitive": false
+}
+```
+
+Output formats: `cif`, `poscar`, `json`, `cssr`, `xsf`.
+
+## Symmetry
+
+`POST /chem/pymatgen/structure/symmetry`
+
+```json
+{
+  "input": "<CIF text>",
+  "format": "cif",
+  "primitive": false,
+  "symprec": 0.01,
+  "angle_tolerance": 5.0
+}
+```
+
+Returns `space_group_symbol`, `space_group_number`, `crystal_system`,
+`point_group_symbol`, `hall`, and `nsites`.

package/skills/rdkit/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: rdkit
+description: 当用户需要通过已部署的 Delta Science 服务校验或规范化 SMILES/InChI、计算 RDKit 描述符、指纹、相似度、渲染或子结构筛选时使用。所有实时请求只能由 python_repl 直接执行 delta-science Skill 的 invoke.py；禁止 Bash、目录探测、直接 HTTP、本地 RDKit 和 native.data 路径。
+---
+
+# RDKit 服务
+
+## 不可违反的执行规则
+
+1. 第一个且唯一允许用于实时 Science 调用的工具是 `python_repl`。
+   `python_repl` 的工具参数对象只能包含 `code`；禁止 `deps`、`dependencies`、
+   `packages` 或其他参数。
+2. 在 `python_repl` 中直接执行同级 Skill 的
+   `$SKILLS_ROOT/delta-science/scripts/invoke.py`。`SKILLS_ROOT` 只能通过
+   `os.environ["SKILLS_ROOT"]` 读取，不能把 `@SKILLS_ROOT` 当成目录。
+3. 禁止使用 Bash、`list_dir`、`read_file`、`which`、`where`、`ls`，禁止检查
+   wrapper 或寻找 CLI，禁止执行字面命令 `CLI`、`cli`、`delta-cli`。
+4. 禁止 `curl`、`requests`、`httpx`、浏览器和本地 RDKit 回退。
+5. wrapper 成功后，业务结果就在 `result["native"]` 顶层；绝不读取
+   `result["native"]["data"]`。
+6. 一个请求只执行完成任务所需的最少调用。失败后不得自行探测路径、改走 HTTP
+   或改用本地计算。
+
+## 唯一调用模板
+
+```python
+import json, os, subprocess, sys
+wrapper = os.path.join(os.environ["SKILLS_ROOT"], "delta-science", "scripts", "invoke.py")
+payload = {
+    "molecules": [{"id": "aspirin", "smiles": "CC(=O)OC1=CC=CC=C1C(=O)O"}],
+    "descriptor_set": "basic",
+    "sanitize": True,
+}
+p = subprocess.run(
+    [sys.executable, wrapper, "--tool", "rdkit", "--endpoint", "batch-parse-describe",
+     "--data-json", json.dumps(payload)],
+    capture_output=True, text=True, shell=False,
+)
+if p.returncode != 0:
+    raise RuntimeError(p.stderr or p.stdout)
+r = json.loads(p.stdout)
+if r.get("ok") is not True or r.get("transport") != "delta-cli":
+    raise RuntimeError(r)
+n = r["native"]
+item = n["results"][0]
+answer = {
+    "endpoint": r["endpoint"],
+    "valid": item["valid"],
+    "canonical_smiles": item.get("canonical_smiles"),
+    "descriptors": item.get("descriptors"),
+    "warnings": item.get("warnings", []),
+}
+print(json.dumps(answer, ensure_ascii=False))
+```
+
+只替换 payload 和逻辑 endpoint。不要先调用 health，也不要增加第二次 parse 或
+descriptors 调用。只要进程退出码、`ok`、`transport` 和解析均成功，本次调用就已
+完成；不得因为界面未显示 Python 表达式值而重复调用，不得通过打印 stdout、stderr
+或完整 native 调试。
+
+成功打印有界 JSON 后，立即调用 `step_finish(status="done", summary=<该 JSON>)`
+恰好一次，不设置 `output_ref`，随后不得输出自由文本或调用工具。失败时调用
+`step_finish(status="failed", summary=<原始错误的短摘要>)`，禁止重试、调试打印或
+路径探测。
+
+## 端点选择
+
+- 同时要求解析和基础描述符：只调用一次 `batch-parse-describe`，payload 必须使用
+  `molecules`，每项使用 `id` 和 `smiles`；`descriptor_set` 为 `basic`，
+  `sanitize` 为 `true`。
+- 只解析或规范化一个输入：`parse`，payload 为
+  `{"input":"...","format":"smiles"}` 或相应 InChI 格式。
+- 只计算描述符：`descriptors`；批量只计算描述符：`batch-descriptors`。
+- 两个分子的相似度：`similarity`；多个分子的全对相似度：
+  `similarity-matrix`。
+- 渲染：`render`；指纹：`fingerprint`；SMARTS 筛选：`substructure`。
+
+非默认 operation 先读 `references/operations.md` 中对应小节；完整字段和允许值再见
+`references/endpoints.md`。不要根据其他服务相似端点猜 schema。
+
+## 多分子相似度
+
+名称必须先由 PubChem Skill 得到 SMILES，再执行一次 `similarity-matrix`：
+
+```python
+payload = {
+    "molecules": [{"id": name, "smiles": smiles} for name, smiles in resolved],
+    "fingerprint": {"type": "morgan", "radius": 2, "n_bits": 2048},
+    "sanitize": True,
+}
+```
+
+结果从 `n["matrix"]` 和 `n["ranked_pairs"]` 读取。每个排名项固定为
+`{"a": 名称, "b": 名称, "similarity": 数值}`；禁止读取 `i`、`j`、
+`score`，禁止自行重算或添加阈值解释。
+
+## 结果与失败边界
+
+- 只报告本次 `native` 返回的字段、数值和警告，不用记忆补值。
+- 描述符只能逐项复制 `item["descriptors"]` 中实际存在的键和值；不得补充
+  `NumAromaticRings`、形式电荷、官能团、手性、结构原因、单位或解释，除非这些字段
+  确实由本次 native 返回且用户明确要求。
+- `valid: false` 是化学输入校验失败，原样报告 `error`/`warnings`。
+- wrapper、CLI 或后端失败时，报告实际阶段和错误；不要继续探测或回退。
+- 渲染结果只有在解码后的字节以 PNG magic bytes 开头时才能保存为 `.png`；禁止
+  把 JSON envelope 保存成图片。
+- PubChem 的 `XLogP` 与 RDKit 的 `MolLogP` 不是同一来源，不得互相替代。

package/skills/rdkit/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "RDKit ?????"
+  short_description: "?? Delta CLI ?????????????????"
+  default_prompt: "?? $rdkit ???????????????????"

package/skills/rdkit/references/endpoints.md

@@ -0,0 +1,133 @@
+# RDKit Endpoint Reference
+
+在 Memento 中只能通过 `delta-science/scripts/invoke.py` 调用。wrapper 已解包服务
+信封，因此以下业务响应在 wrapper 结果中位于 `result["native"]` 顶层；禁止读取
+`result["native"]["data"]`。本文件中的 URL 只说明 schema，不授权直接 HTTP。
+
+All paths are relative to `http://111.2.199.31:52317/api/v1`.
+
+## Health
+
+`GET /chem/rdkit/health`
+
+## Parse
+
+`POST /chem/rdkit/parse`
+
+```json
+{"input": "CCO", "format": "smiles", "sanitize": true}
+```
+
+Formats: `smiles`, `inchi`, `molblock`.
+
+Key response fields in `data`: `valid`, `canonical_smiles`, `formula`,
+`molecular_weight`, `exact_molecular_weight`, `inchi_key`, `atom_count`,
+`heavy_atom_count`, `bond_count`, `warnings`, `error`.
+
+## Descriptors
+
+`POST /chem/rdkit/descriptors`
+
+```json
+{"smiles": "CCO", "descriptor_set": "basic", "sanitize": true}
+```
+
+`descriptor_set` currently supports `basic`. Descriptor keys include `Formula`,
+`MolWt`, `ExactMolWt`, `HeavyAtomMolWt`, `TPSA`, `MolLogP`, `NumHDonors`,
+`NumHAcceptors`, `NumRotatableBonds`, `RingCount`, `FractionCSP3`,
+`HeavyAtomCount`, `AtomCount`, and `BondCount`.
+
+## Batch Descriptors
+
+`POST /chem/rdkit/batch-descriptors`
+
+```json
+{"smiles": ["CCO", "c1ccccc1"], "descriptor_set": "basic", "sanitize": true}
+```
+
+Limits: 1-500 SMILES.
+
+## Batch Parse Describe
+
+`POST /chem/rdkit/batch-parse-describe`
+
+```json
+{
+  "molecules": [
+    {"id": "aspirin", "smiles": "CC(=O)Oc1ccccc1C(=O)O"},
+    {"id": "caffeine", "smiles": "Cn1cnc2c1c(=O)n(C)c(=O)n2C"}
+  ],
+  "descriptor_set": "basic",
+  "fingerprint": {"type": "morgan", "radius": 2, "n_bits": 2048},
+  "sanitize": true
+}
+```
+
+Limits: 1-500 molecules. Returns per-item `valid`, `canonical_smiles`, parse
+fields, `descriptors`, optional `fingerprint_metadata`, `on_bits`, `bit_count`,
+`warnings`, and `error`.
+
+## Render
+
+`POST /chem/rdkit/render`
+
+```json
+{"smiles": "CCO", "image_format": "svg", "width": 450, "height": 320}
+```
+
+Image formats: `svg`, `png`. SVG returns text; PNG returns base64.
+Width/height range: 150-2000.
+
+## Fingerprint
+
+`POST /chem/rdkit/fingerprint`
+
+```json
+{"smiles": "CCO", "radius": 2, "n_bits": 2048}
+```
+
+Morgan fingerprint parameters: `radius` 1-6, `n_bits` 128-8192.
+
+## Similarity
+
+`POST /chem/rdkit/similarity`
+
+```json
+{"query_smiles": "CCO", "target_smiles": "CCCO", "radius": 2, "n_bits": 2048}
+```
+
+Returns Tanimoto similarity.
+
+## Similarity Matrix
+
+`POST /chem/rdkit/similarity-matrix`
+
+```json
+{
+  "molecules": [
+    {"id": "aspirin", "smiles": "CC(=O)Oc1ccccc1C(=O)O"},
+    {"id": "ibuprofen", "smiles": "CC(C)Cc1ccc(cc1)[C@@H](C)C(=O)O"}
+  ],
+  "fingerprint": {"type": "morgan", "radius": 2, "n_bits": 2048},
+  "sanitize": true
+}
+```
+
+Returns `matrix` in input order and `ranked_pairs` sorted by descending
+Tanimoto similarity. Each ranked record is named, not index-based:
+
+```json
+{"a":"aspirin","b":"ibuprofen","similarity":0.195122}
+```
+
+Do not expect `i`, `j`, or `score` fields.
+
+## Substructure
+
+`POST /chem/rdkit/substructure`
+
+```json
+{"query_smarts": "c1ccccc1", "target_smiles": ["c1ccccc1", "CCO"]}
+```
+
+Limits: SMARTS max length 5000; target list size 1-500.