@delta-infra/cli 1.1.19 → 1.1.21

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

@@ -1,68 +1,68 @@
-# LAMMPS reference
-
-Make all calls with `delta-cli science invoke`. LAMMPS does not infer data files, atom types,
-potentials or boundary conditions from a formula, CIF or POSCAR. Successful execution does not
-establish physical convergence or production readiness.
-
-## Health
-
-Operation: `health`; no request body.
-
-Key response fields in `data`: `status`, `service`, `lammps_available`,
-`metadata`, and `limits`.
-
-Call this only when the user explicitly asks for a health check; do not add a health call automatically before simulation.
-
-## Built-In Lennard-Jones Example
-
-Operation: `lj-melt-example`.
-
-Returns a complete `request` payload for the `run` operation, plus workflow notes
-showing where pymatgen and GSAS-II fit around LAMMPS.
-
-## Run
-
-Operation: `run`.
-
-```json
-{
-  "input_script": "<LAMMPS input script>",
-  "files": [
-    {"path": "system.data", "content": "<LAMMPS data file text>", "encoding": "text"}
-  ],
-  "timeout_seconds": 30,
-  "max_thermo_rows": 1000,
-  "log_tail_lines": 200,
-  "output_files": ["dump.lammpstrj", "final.data"],
-  "include_log": true,
-  "include_stdout": false,
-  "include_stderr": false
-}
-```
-
-`files` are written into a fresh job working directory before LAMMPS starts.
-`encoding` can be `text` or `base64`.
-
-The response includes parsed thermo rows, the final thermo row, atom count when
-detectable, log tail, warnings, and requested output files. Text output files
-return `content`; binary output files return `content_base64`.
-
-Notes:
-
-- Use relative file paths only.
-- The service rejects unsafe commands such as `shell`, `python`, `plugin`, and
-  `jump` by default.
-- `include <relative-file>` is allowed when the included file is supplied in
-  `files`; absolute paths, parent-directory traversal, URLs, and `jump` loops
-  are rejected.
-- Dump/data products are returned as raw requested output files, not structured
-  parsed atom-frame objects.
-- The gateway is synchronous; keep interactive runs short.
-- Force-field choice is caller responsibility. The service executes explicit
-  LAMMPS input and does not infer potentials from formulas or structures.
-
-In the final reply, include only `last_thermo`, the final step/temperature/total energy,
-warnings, and a summary of output files requested by the user from the current business response.
-Do not divide total energy by the atom count, substitute steps, convert units, or infer
-convergence or stability. For the minimal example, call `lj-melt-example` first, then pass its
-`request` from the current business response to `run` unchanged; do not pass the outer CLI envelope.
+# LAMMPS reference
+
+Make all calls with `delta-cli science invoke`. LAMMPS does not infer data files, atom types,
+potentials or boundary conditions from a formula, CIF or POSCAR. Successful execution does not
+establish physical convergence or production readiness.
+
+## Health
+
+Operation: `health`; no request body.
+
+Key response fields in `data`: `status`, `service`, `lammps_available`,
+`metadata`, and `limits`.
+
+Call this only when the user explicitly asks for a health check; do not add a health call automatically before simulation.
+
+## Built-In Lennard-Jones Example
+
+Operation: `lj-melt-example`.
+
+Returns a complete `request` payload for the `run` operation, plus workflow notes
+showing where pymatgen and GSAS-II fit around LAMMPS.
+
+## Run
+
+Operation: `run`.
+
+```json
+{
+  "input_script": "<LAMMPS input script>",
+  "files": [
+    {"path": "system.data", "content": "<LAMMPS data file text>", "encoding": "text"}
+  ],
+  "timeout_seconds": 30,
+  "max_thermo_rows": 1000,
+  "log_tail_lines": 200,
+  "output_files": ["dump.lammpstrj", "final.data"],
+  "include_log": true,
+  "include_stdout": false,
+  "include_stderr": false
+}
+```
+
+`files` are written into a fresh job working directory before LAMMPS starts.
+`encoding` can be `text` or `base64`.
+
+The response includes parsed thermo rows, the final thermo row, atom count when
+detectable, log tail, warnings, and requested output files. Text output files
+return `content`; binary output files return `content_base64`.
+
+Notes:
+
+- Use relative file paths only.
+- The service rejects unsafe commands such as `shell`, `python`, `plugin`, and
+  `jump` by default.
+- `include <relative-file>` is allowed when the included file is supplied in
+  `files`; absolute paths, parent-directory traversal, URLs, and `jump` loops
+  are rejected.
+- Dump/data products are returned as raw requested output files, not structured
+  parsed atom-frame objects.
+- The gateway is synchronous; keep interactive runs short.
+- Force-field choice is caller responsibility. The service executes explicit
+  LAMMPS input and does not infer potentials from formulas or structures.
+
+In the final reply, include only `last_thermo`, the final step/temperature/total energy,
+warnings, and a summary of output files requested by the user from the current business response.
+Do not divide total energy by the atom count, substitute steps, convert units, or infer
+convergence or stability. For the minimal example, call `lj-melt-example` first, then pass its
+`request` from the current business response to `run` unchanged; do not pass the outer CLI envelope.

package/skills/delta-science/references/ldm-bo.md

@@ -1,132 +1,132 @@
-# LDM-BO reference
-
-Make all calls with `delta-cli science invoke`; do not use the local PDF2Dock runner. This tool is
-for small-molecule SMILES only. Use the AntBO capability boundary for antibody, CDRH3 or AntBO
-tasks. The server injects the provider, model paths and Vina/ReaSyn/GPU/LLM settings; do not put
-them in the request JSON.
-
-## Health
-
-Operation: `health`; no request body.
-
-The response reports whether the adapter can see the mounted PDF2Dock
-interpreter, `bo_api.py`, Vina binary, ReaSyn repo/interpreter/checkpoints, NN
-model files, cache directory, GPU settings, and LLM configuration. Missing LLM
-settings degrade health because LDM methods need them.
-
-## One-Step Recommend
-
-Operation: `recommend`.
-
-Wraps `bo_api.recommend_next_smiles`.
-
-Typical payload:
-
-```json
-{
-  "method": "bo-tanimoto",
-  "pool": ["CCO", "CCN", "CCC"],
-  "history": [
-    {"smiles": "CCO", "scores": [-7.1]},
-    {"smiles": "CCN", "scores": [-6.8]}
-  ],
-  "batch_size": 1
-}
-```
-
-Typical business response inside the documented gateway `data`:
-
-```json
-{
-  "recommendations": ["CCC"],
-  "acquisition_values": [0.12],
-  "n_objectives": 1
-}
-```
-
-LDM methods may include an `llm` diagnostics object.
-
-Report `acquisition_values` exactly as returned in the business response. Unless the current
-business response explicitly defines the field, do not describe it as predicted Vina, a predicted
-objective, uncertainty, confidence or expected improvement, and do not infer whether higher or
-lower is better. If the service provides no recommendation rationale, state “The service returned
-no recommendation rationale”; do not add an explanation based on molecular scaffolds, heteroatoms
-or model mechanisms.
-
-## Full Trajectory
-
-Operation: `trajectory`.
-
-Wraps `bo_api.run_search_trajectory`.
-
-Small smoke payload:
-
-```json
-{
-  "method": "bo-tanimoto",
-  "seed": 42,
-  "seed-smiles": "CCO,CCN,CCC",
-  "num-evaluations": 4,
-  "batch-size": 1,
-  "objective": "vina+nn"
-}
-```
-
-Typical business response inside the documented gateway `data`:
-
-```json
-{
-  "config": {},
-  "history": [],
-  "summary": {}
-}
-```
-
-LDM methods may include `llm_trajectory`.
-
-## Error Handling
-
-The service maps `bo_api` error JSON to an upstream failure. The gateway
-returns a standard error envelope:
-
-```json
-{
-  "code": 1,
-  "message": "AutoDock Vina executable not found...",
-  "data": {
-    "endpoint": "/v1/trajectory",
-    "ldm_bo_response": {
-      "error": "...",
-      "error_type": "ValueError",
-      "traceback": "Traceback ..."
-    }
-  }
-}
-```
-
-Common causes are missing Vina, missing ReaSyn, wrong Python interpreter, CUDA
-device mismatch, missing LLM credentials for LDM methods, or an unwritable Vina
-cache directory.
-
-## Provider Settings
-
-Do not send provider settings in request JSON. The adapter reads these from
-deployment config and passes them as Python kwargs to `bo_api`:
-
-```text
-vina_bin
-vina_cache_dir
-vina_max_workers
-gp_device
-reasyn_repo
-reasyn_python_bin
-reasyn_model_path
-reasyn_devices
-nn_model_path
-nn_metadata_path
-llm_model
-llm_base_url
-llm_api_key
-```
-
-The CLI forwards the user payload; `bo_api` owns business defaults and schema behavior.
+# LDM-BO reference
+
+Make all calls with `delta-cli science invoke`; do not use the local PDF2Dock runner. This tool is
+for small-molecule SMILES only. Use the AntBO capability boundary for antibody, CDRH3 or AntBO
+tasks. The server injects the provider, model paths and Vina/ReaSyn/GPU/LLM settings; do not put
+them in the request JSON.
+
+## Health
+
+Operation: `health`; no request body.
+
+The response reports whether the adapter can see the mounted PDF2Dock
+interpreter, `bo_api.py`, Vina binary, ReaSyn repo/interpreter/checkpoints, NN
+model files, cache directory, GPU settings, and LLM configuration. Missing LLM
+settings degrade health because LDM methods need them.
+
+## One-Step Recommend
+
+Operation: `recommend`.
+
+Wraps `bo_api.recommend_next_smiles`.
+
+Typical payload:
+
+```json
+{
+  "method": "bo-tanimoto",
+  "pool": ["CCO", "CCN", "CCC"],
+  "history": [
+    {"smiles": "CCO", "scores": [-7.1]},
+    {"smiles": "CCN", "scores": [-6.8]}
+  ],
+  "batch_size": 1
+}
+```
+
+Typical business response inside the documented gateway `data`:
+
+```json
+{
+  "recommendations": ["CCC"],
+  "acquisition_values": [0.12],
+  "n_objectives": 1
+}
+```
+
+LDM methods may include an `llm` diagnostics object.
+
+Report `acquisition_values` exactly as returned in the business response. Unless the current
+business response explicitly defines the field, do not describe it as predicted Vina, a predicted
+objective, uncertainty, confidence or expected improvement, and do not infer whether higher or
+lower is better. If the service provides no recommendation rationale, state “The service returned
+no recommendation rationale”; do not add an explanation based on molecular scaffolds, heteroatoms
+or model mechanisms.
+
+## Full Trajectory
+
+Operation: `trajectory`.
+
+Wraps `bo_api.run_search_trajectory`.
+
+Small smoke payload:
+
+```json
+{
+  "method": "bo-tanimoto",
+  "seed": 42,
+  "seed-smiles": "CCO,CCN,CCC",
+  "num-evaluations": 4,
+  "batch-size": 1,
+  "objective": "vina+nn"
+}
+```
+
+Typical business response inside the documented gateway `data`:
+
+```json
+{
+  "config": {},
+  "history": [],
+  "summary": {}
+}
+```
+
+LDM methods may include `llm_trajectory`.
+
+## Error Handling
+
+The service maps `bo_api` error JSON to an upstream failure. The gateway
+returns a standard error envelope:
+
+```json
+{
+  "code": 1,
+  "message": "AutoDock Vina executable not found...",
+  "data": {
+    "endpoint": "/v1/trajectory",
+    "ldm_bo_response": {
+      "error": "...",
+      "error_type": "ValueError",
+      "traceback": "Traceback ..."
+    }
+  }
+}
+```
+
+Common causes are missing Vina, missing ReaSyn, wrong Python interpreter, CUDA
+device mismatch, missing LLM credentials for LDM methods, or an unwritable Vina
+cache directory.
+
+## Provider Settings
+
+Do not send provider settings in request JSON. The adapter reads these from
+deployment config and passes them as Python kwargs to `bo_api`:
+
+```text
+vina_bin
+vina_cache_dir
+vina_max_workers
+gp_device
+reasyn_repo
+reasyn_python_bin
+reasyn_model_path
+reasyn_devices
+nn_model_path
+nn_metadata_path
+llm_model
+llm_base_url
+llm_api_key
+```
+
+The CLI forwards the user payload; `bo_api` owns business defaults and schema behavior.

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

@@ -1,130 +1,130 @@
-# 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.
+# 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.