@delta-infra/cli 1.1.17 → 1.1.19

package/skills/delta-science/references/materials-design.md

@@ -1,118 +1,130 @@
-# Materials Design 详细规则
-
-Materials Design 用于从实验或计算材料表格中建立 surrogate、验证模型、定义可行候选空间，
-并生成带不确定性的候选排序。推荐是待验证假设，不是已确认材料、合成方案或实验结果。
-
-本 reference 的路由标签是 `materials-design`。`tools.name` 和
-`tool_endpoints.name` 仍以当前 `delta-cli science list` 和
-`delta-cli science endpoints list <tool>` 的返回为准；下列 Gateway 路径只是服务契约，
-不是可以直接拼接或访问的 URL。
-
-## 服务边界
-
-服务提供以下能力：
-
-| 服务路径 | 作用 | 结果边界 |
-| --- | --- | --- |
-| `/chem/materials-design/health` | Gateway 到服务的就绪检查 | `status`、依赖可用性、limits |
-| `/chem/materials-design/v1/capabilities` | 输入格式、模型、验证模式和限制 | 能力目录 |
-| `/chem/materials-design/v1/jobs` | 上传训练/候选表并创建异步作业 | `202`、`job_id`、状态和 links |
-| `/chem/materials-design/v1/jobs/{job_id}` | 查询作业 | `status`、`result_status`、result、warnings |
-| `/chem/materials-design/v1/jobs/{job_id}/cancel` | 请求取消 | 取消请求/终态 |
-| `/chem/materials-design/v1/jobs/{job_id}/artifacts` | 列出产物 | name、size、media_type、SHA-256 |
-| `/chem/materials-design/v1/jobs/{job_id}/artifacts/{path}` | 下载单个产物 | 原始 report/JSON/CSV/figure bytes |
-
-所有 JSON/query 调用都必须走：
-
-```text
-delta-cli science invoke --tool TOOL --endpoint ENDPOINT --data JSON
-```
-
-训练表提交使用受控文件 adapter：
-
-```text
-delta-cli science file invoke --tool materials-design --endpoint job-submit \
-  --file train.xlsx --candidate-file candidates.xlsx --data CONFIG_JSON
-delta-cli science task submit --tool materials-design --operation job-status \
-  --input '{"job_id":"mdjob_..."}' --wait
-delta-cli science file download --tool materials-design --endpoint artifact-download \
-  --params '{"job_id":"mdjob_...","artifact_path":"report.html"}' --output report.html
-```
-
-只读 query operation 才使用 `--params JSON`。如果新工具尚未出现在目录中，或目录没有
-返回足够的请求 schema，停止并报告未暴露；不要猜测 endpoint 名、body 或兼容别名。
-
-## CLI 能力边界
-
-`POST /v1/jobs` 的原始服务请求是 `multipart/form-data`，至少包含：
-
-```text
-file=<training table>
-candidate_file=<optional candidate table>
-config=<serialized JSON object>
-```
-
-`science invoke` 只接受 JSON object body 和 JSON query 参数，不能表达 multipart；因此不能
-把本地路径或 base64 伪装成文件字段。artifact 下载同样是原始 bytes，必须通过
-`science file download` 保存并校验，不能当作普通 JSON 结果。不得调用
-`materials-design-service:8900` 或直连 preflight Gateway。
-
-## 输入与配置
-
-开始建模前必须确认：
-
-- `feature_columns`、`controllable_columns`、`target_column` 或 `objectives`；
-- identifier、metadata、leakage、post-measurement、group/time 列及单位；
-- 目标方向、可行性约束、候选表或候选生成规则；
-- 缺失值、重复样本、测量条件、数据来源和验证切分策略。
-
-单目标配置的核心字段：
-
-```json
-{
-  "feature_columns": ["Bi", "In", "Ti"],
-  "controllable_columns": ["Bi", "In", "Ti"],
-  "identifier_columns": ["sample_id"],
-  "target_column": "T",
-  "target_direction": "maximize",
-  "validation": {"strategy": "kfold", "n_splits": 5},
-  "model_names": ["ExtraTrees", "GPR", "Ridge"],
-  "random_state": 42,
-  "recommendation_count": 10
-}
-```
-
-多目标使用 `objectives: [{"target_column": "...", "direction": "maximize|minimize"}]`
-和显式的 Pareto/EHVI 配置。优先传入用户的 `candidate_file`；若服务按观测范围生成
-候选，必须显式保留 steps、hard constraints、composition closure、`max_candidates` 和
-`allow_extrapolation`。禁止优化 identifier、测量后变量、泄漏列或未获授权的域外点，禁止
-为填充候选数而任意外推。
-
-## 结果处理
-
-作业 `status` 与 `result_status` 必须分开判断：
-
-- `status`：`pending`、`running`、`completed`、`failed`、`cancelled`；
-- `result_status`：`complete`、`exploratory`、`readiness_only` 或 `failed`。
-
-`202` 只表示服务已接收/排队，不表示模型训练完成；`completed` 也不表示排序可靠。
-只有在 `result_status` 为 `complete` 时才能说数据和验证支持候选排序；`exploratory` 只能
-作为学习假设；`readiness_only` 要读取 readiness 信息并请求缺失输入；`failed` 原样报告。
-始终保留服务返回的 validation、ranking、warnings 和 error。
-
-预测结果必须和观测值、交叉验证预测区分。报告至少说明数据覆盖、切分、模型比较、
-不确定性校准、候选可行性、域内/域外状态、EI/PI/UCB 或 Pareto 设置，以及后续实验验证
-计划；不要用模型方差冒充实验误差或把候选预测写成实测值。
-
-## Artifact 与错误
-
-只有用户要求或工作流需要时才读取 artifacts。按 listing 返回的 `size`、`media_type` 和
-SHA-256 校验下载内容；不能凭文件名猜格式。服务可能产生 `report.html`、`result.json`、
-`data_dictionary.json`、`model_comparison.csv`、OOF/残差/校准文件、`search_space.json`、
-`candidate_predictions.csv`、`shortlist.csv`、`recommendation_views.csv`、
-`pareto_front.csv` 和 `figures/*`。
-
-常见终止条件包括配置/文件格式错误、缺目标或候选空间、超出上传/行数/候选数限制、
-后端未就绪、作业不存在和 artifact 不存在。提交超时或连接中断时不要盲目重试：multipart
-上传可能已经创建作业，先检查是否已经得到 `job_id`。失败或空推荐不得用本地回归、GP、
-随机数或人工排序替代。
+# Materials Design reference
+
+Materials Design builds surrogate models from experimental or computational materials tables,
+validates models, defines feasible candidate spaces, and ranks candidates with uncertainty
+estimates. Recommendations are hypotheses to validate, not confirmed materials, synthesis routes
+or experimental results.
+
+The routing label for this reference is `materials-design`. Use the current output of
+`delta-cli science list` and `delta-cli science endpoints list <tool>` as the authority for
+`tools.name` and `tool_endpoints.name`. The Gateway paths below describe the service contract;
+they are not URLs to construct or access directly.
+
+## Service boundary
+
+The service provides the following capabilities:
+
+| Service path | Purpose | Result boundary |
+| --- | --- | --- |
+| `/chem/materials-design/health` | Gateway-to-service readiness check | `status`, dependency availability, limits |
+| `/chem/materials-design/v1/capabilities` | Input formats, models, validation modes and limits | Capability catalogue |
+| `/chem/materials-design/v1/jobs` | Upload training/candidate tables and create an asynchronous job | `202`, `job_id`, status and links |
+| `/chem/materials-design/v1/jobs/{job_id}` | Read job status | `status`, `result_status`, result, warnings |
+| `/chem/materials-design/v1/jobs/{job_id}/cancel` | Request cancellation | Cancellation request/final state |
+| `/chem/materials-design/v1/jobs/{job_id}/artifacts` | List artifacts | name, size, media_type, SHA-256 |
+| `/chem/materials-design/v1/jobs/{job_id}/artifacts/{path}` | Download one artifact | Raw report/JSON/CSV/figure bytes |
+
+Route all JSON/query calls through:
+
+```text
+delta-cli science invoke --tool TOOL --endpoint ENDPOINT --data JSON
+```
+
+Submit training tables through the controlled file adapter:
+
+```text
+delta-cli science file invoke --tool materials-design --endpoint job-submit \
+  --file train.xlsx --candidate-file candidates.xlsx --data CONFIG_JSON
+delta-cli science task submit --tool materials-design --operation job-status \
+  --input '{"job_id":"mdjob_..."}' --wait
+delta-cli science file download --tool materials-design --endpoint artifact-download \
+  --params '{"job_id":"mdjob_...","artifact_path":"report.html"}' --output report.html
+```
+
+Use `--params JSON` only for read-only query operations. If a new tool is absent from the
+catalogue, or the catalogue does not return enough request-schema detail, stop and report that it
+is not exposed. Do not guess endpoint names, bodies or compatibility aliases.
+
+## CLI capability boundaries
+
+The raw service request for `POST /v1/jobs` is `multipart/form-data` and contains at least:
+
+```text
+file=<training table>
+candidate_file=<optional candidate table>
+config=<serialized JSON object>
+```
+
+`science invoke` accepts only a JSON object body and JSON query parameters; it cannot express
+multipart data. Do not disguise a local path or base64 as a file field. Artifact downloads are
+also raw bytes: save and verify them with `science file download`, and do not treat them as
+ordinary JSON results. Do not call `materials-design-service:8900` or connect directly to the
+preflight Gateway.
+
+## Inputs and configuration
+
+Before modelling, confirm:
+
+- `feature_columns`, `controllable_columns`, `target_column` or `objectives`;
+- identifier, metadata, leakage, post-measurement and group/time columns, and their units;
+- objective direction, feasibility constraints, candidate table or candidate-generation rules;
+- missing values, duplicate samples, measurement conditions, data sources and validation split strategy.
+
+Core fields for a single-objective configuration:
+
+```json
+{
+  "feature_columns": ["Bi", "In", "Ti"],
+  "controllable_columns": ["Bi", "In", "Ti"],
+  "identifier_columns": ["sample_id"],
+  "target_column": "T",
+  "target_direction": "maximize",
+  "validation": {"strategy": "kfold", "n_splits": 5},
+  "model_names": ["ExtraTrees", "GPR", "Ridge"],
+  "random_state": 42,
+  "recommendation_count": 10
+}
+```
+
+For multiple objectives, use `objectives: [{"target_column": "...", "direction": "maximize|minimize"}]`
+and explicit Pareto/EHVI settings. Prefer the user's `candidate_file`. If the service generates
+candidates from observed ranges, explicitly preserve steps, hard constraints, composition
+closure, `max_candidates` and `allow_extrapolation`. Do not optimise identifier, post-measurement
+or leakage columns, or out-of-domain points without authorisation. Do not extrapolate arbitrarily
+to fill the candidate count.
+
+## Results handling
+
+Assess job `status` and `result_status` separately:
+
+- `status`: `pending`, `running`, `completed`, `failed` or `cancelled`;
+- `result_status`: `complete`, `exploratory`, `readiness_only` or `failed`.
+
+`202` means only that the service accepted or queued the job; it does not mean model training is
+complete. `completed` does not mean the ranking is reliable. Say that the data and validation
+support candidate ranking only when `result_status` is `complete`. Treat `exploratory` only as a
+learning hypothesis; for `readiness_only`, read the readiness information and request missing
+inputs; report `failed` as returned. Always preserve the returned validation, ranking, warnings
+and error.
+
+Keep predictions distinct from observations and cross-validation predictions. At minimum, report
+data coverage, the split, model comparisons, uncertainty calibration, candidate feasibility,
+in-domain/out-of-domain status, EI/PI/UCB or Pareto settings, and the plan for experimental
+validation. Do not present model variance as experimental error or candidate predictions as
+measured values.
+
+## Artifacts and errors
+
+Read artifacts only when the user asks for them or the workflow requires them. Verify downloaded
+content against the `size`, `media_type` and SHA-256 returned by the listing; do not infer formats
+from filenames. The service may produce `report.html`, `result.json`,
+`data_dictionary.json`, `model_comparison.csv`, OOF/residual/calibration files,
+`search_space.json`, `candidate_predictions.csv`, `shortlist.csv`, `recommendation_views.csv`,
+`pareto_front.csv` and `figures/*`.
+
+Common terminal conditions include configuration/file-format errors, a missing target or
+candidate space, upload/row/candidate-count limits being exceeded, an unready backend, or a
+missing job or artifact. Do not retry blindly after a submission timeout or disconnection: a
+multipart upload may already have created a job, so first check whether a `job_id` was returned.
+Do not replace a failure or empty recommendation with local regression, GP, random numbers or a
+manual ranking.

package/skills/delta-science/references/pubchem.md

@@ -1,126 +1,128 @@
-# PubChem 详细规则
-
-只能通过 `delta-cli science invoke` 调用。本文件中的业务响应位于 CLI 顶层 `data`；
-只按本文件说明读取字段，不得递归搜索。本文件中的 URL 只用于说明 endpoint schema，
-不授权直接 HTTP。普通名称基础查询只调用一次 `compound-summary`；多个名称
-只调用一次 `compound-batch-summary`，默认 body 仅包含 `identifiers` 和
-`namespace:"name"`，不得先调用 health/schema。
-
-结果直接从 `data` 投影。批量记录位于 `data.results[*]`，原始标签在 `input`，
-属性在嵌套 `properties`。SMILES 回退顺序固定为
-`CanonicalSMILES -> ConnectivitySMILES -> SMILES -> IsomericSMILES`。
-PubChem `XLogP` 与 RDKit `MolLogP` 不得互换；not_found 不得用本地计算补值。
-
-Namespaces: `cid`, `name`, `smiles`, `inchi`, `inchikey`, `formula`.
-
-## Health
-
-operation：`health`，无 body。
-
-## Resolve CIDs
-
-operation：`compound-resolve-cids`。
-
-```json
-{"identifier": "aspirin", "namespace": "name", "max_records": 20}
-```
-
-`max_records`: 1-100.
-
-## Properties
-
-operation：`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
-
-operation：`compound-synonyms`。
-
-```json
-{"identifier": "2244", "namespace": "cid", "max_synonyms": 50}
-```
-
-`max_synonyms`: 1-500.
-
-## Summary
-
-operation：`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
-
-operation：`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
-}
-```
+# PubChem reference
+
+Call this tool only through `delta-cli science invoke`. Business responses are in the top-level
+CLI `data`; read only the fields described here and do not search recursively. URLs in this file
+explain the endpoint schema and do not authorise direct HTTP access. For a basic lookup by a
+single common name, call `compound-summary` once. For multiple names, call
+`compound-batch-summary` once with a default body containing only `identifiers` and
+`namespace:"name"`; do not call health or schema first.
+
+Project results directly from `data`. Batch records are in `data.results[*]`, the original label
+is in `input`, and properties are nested under `properties`. Use this fixed SMILES fallback
+order: `CanonicalSMILES -> ConnectivitySMILES -> SMILES -> IsomericSMILES`. Do not treat PubChem
+`XLogP` and RDKit `MolLogP` as interchangeable; do not fill a `not_found` result with local
+calculations.
+
+Namespaces: `cid`, `name`, `smiles`, `inchi`, `inchikey`, `formula`.
+
+## Health
+
+Operation: `health`; no request body.
+
+## Resolve CIDs
+
+Operation: `compound-resolve-cids`.
+
+```json
+{"identifier": "aspirin", "namespace": "name", "max_records": 20}
+```
+
+`max_records`: 1-100.
+
+## Properties
+
+Operation: `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
+
+Operation: `compound-synonyms`.
+
+```json
+{"identifier": "2244", "namespace": "cid", "max_synonyms": 50}
+```
+
+`max_synonyms`: 1-500.
+
+## Summary
+
+Operation: `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
+
+Operation: `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
+}
+```