@delta-agentcloud/cli 0.0.0-stage → 1.1.22

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

@@ -0,0 +1,69 @@
+# pymatgen reference
+
+Make all calls with `delta-cli science invoke`. Prefer pymatgen for inorganic formulae,
+composition and formula weight; do not use PubChem or a local element table as a substitute.
+Structure operations require the complete structure text, not a local file path. Supported formats
+are `cif`, `poscar`, `json`, `cssr` and `xsf`; LAMMPS data and dump files are not accepted.
+
+## Health
+
+Operation: `health`; no request body.
+
+## Composition Parse
+
+Operation: `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
+
+Operation: `structure-parse` or `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
+
+Operation: `structure-convert`.
+
+```json
+{
+  "input": "<CIF text>",
+  "input_format": "cif",
+  "output_format": "poscar",
+  "primitive": false
+}
+```
+
+Output formats: `cif`, `poscar`, `json`, `cssr`, `xsf`.
+
+## Symmetry
+
+Operation: `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/delta-science/references/qe.md

@@ -0,0 +1,134 @@
+# Quantum ESPRESSO DFT reference
+
+Use QE to run traceable, asynchronous Quantum ESPRESSO workflows through Chemistry Gateway.
+The agent interacts only with the Gateway/Science Server contract: it does not run local `pw.x`,
+call internal QE containers, or submit shell commands, scheduler scripts, `pseudo_dir`, `outdir`
+or host paths.
+
+The actual CLI tool for this reference is `qe`. Copy `tools.name` and `tool_endpoints.name`
+exactly from the current CLI catalogue. The paths below describe the QE service contract; they
+are not URLs to access directly or endpoint aliases that may be rewritten automatically.
+
+## Capability groups
+
+| Service path | Purpose | Type |
+| --- | --- | --- |
+| `/chem/qe/health`, `/healthz`, `/readyz` | Runtime, scheduler, storage and PP readiness | Read-only |
+| `/chem/qe/v1/qe/workflow-types` | Workflow catalogue and support status | Read-only |
+| `/chem/qe/v1/pp-sets`, `/pp-locks/{digest}` | Published PP profiles/locks | Read-only |
+| `/chem/qe/v1/pp-sets:resolve` | Resolve PP candidates for the complete set of campaign elements | Read-only/validation |
+| `/chem/qe/v1/artifacts` | Upload, query and download structure/fixed-coordinate artifacts | File/binary |
+| `/chem/qe/v1/qe/jobs` | Submit asynchronous calculations and query jobs | Remote mutation |
+| `/chem/qe/v1/qe/jobs/{job_id}/events`, `steps`, `logs`, `artifacts` | Read job progress and results | Read-only |
+| `/chem/qe/v1/qe/jobs/{job_id}:cancel`, `:retry`, `:review` | Cancel, retry and scientifically review a job | Remote mutation |
+
+When selecting a new operation, first run:
+
+```text
+delta-cli science list
+delta-cli science endpoints list <exact tool name>
+```
+
+Then call it using the exact names returned by the catalogue. If the catalogue has no schema, do
+not guess the operation, path parameters, headers or body.
+
+## CLI file and idempotency boundaries
+
+Structure artifact uploads require `application/octet-stream` and query metadata; QE job
+submission requires a stable `Idempotency-Key`. `science invoke` remains for JSON/query only;
+send files through `science file` and persistent jobs through `science task`:
+
+- `delta-cli science file invoke --tool qe --endpoint artifact-upload --file <path>` uploads
+  a structure artifact; for `custom-pp-upload`, also provide `custom_pp_id` in `--data`;
+- `delta-cli science task submit --tool qe --operation job-submit --input JSON
+  --idempotency-key KEY` submits a durable QE job; the worker passes the idempotency key to Gateway;
+- `delta-cli science file download --tool qe --endpoint artifact-content --params JSON
+  --output <path>` downloads a raw artifact;
+- Do not send structure text, file paths, base64, `Idempotency-Key` or QE service credentials as
+  ordinary business fields, and do not call public or private Gateway URLs or `qe-cloud-compute:18020`.
+
+## Correct sequence for a new job
+
+1. Read health. Read readiness only when diagnosing the deployment, and choose a currently
+   `supported` task from the workflow catalogue.
+2. Determine the complete `campaign_elements` set and use `pp-sets:resolve` to obtain a profile.
+   Production jobs must use the returned `pp_set_id` and immutable `lock_id`; do not infer the
+   lock from the profile name alone.
+3. Ask the service to validate the structure artifact. The job must reference only the returned
+   `sha256:<digest>` artifact ID.
+4. Submit to `qe/jobs` with stable idempotency semantics. A `202` response means accepted/queued,
+   not that QE has converged.
+5. Poll the job, events, steps, logs and artifacts; read the `execution`, `solver` and
+   `scientific` states independently.
+6. Verify each artifact's SHA-256 when downloading results. Report the selected backend, resource
+   telemetry, solver state, scientific review state and warnings separately.
+
+The minimum business-data shape for PP resolution is shown below. Values must come from the
+current service/catalogue; do not insert a fabricated production lock:
+
+```json
+{
+  "campaign_id": "si-bulk-scf-v1",
+  "campaign_elements": ["Si", "O"],
+  "workflows": ["qe.pw.scf"],
+  "explicit_mode": null
+}
+```
+
+The core job structure is shown below. `workflow_inputs` must follow the current task schema:
+
+```json
+{
+  "task": "qe.pw.scf",
+  "schema_version": "1.1",
+  "campaign_id": "si-bulk-scf-v1",
+  "campaign_elements": ["Si"],
+  "structure": {"format": "artifact", "artifact_id": "sha256:<64-hex>"},
+  "physics": {
+    "parameter_set": "<approved-parameter-set>",
+    "pp_policy": {
+      "mode": "sssp_single",
+      "pp_set_id": "<approved-pp-set>",
+      "lock_id": "sha256:<64-hex>"
+    },
+    "kpoints": [4, 4, 4]
+  },
+  "resources": {
+    "profile": "standard",
+    "nodes": 1,
+    "mpi_ranks_per_node": 1,
+    "omp_threads_per_rank": 1,
+    "walltime_seconds": 3600,
+    "gpu_policy": "cpu"
+  },
+  "client_request_id": "si-scf-v1",
+  "workflow_inputs": {}
+}
+```
+
+## CPU/GPU and state interpretation
+
+CPU is the default, particularly for small or medium interactive jobs, PP/structure/audit/archive
+jobs, and cost-sensitive work. Use `gpu` only when the user explicitly requests it or the project
+already has a GPU budget, and the live catalogue returns `gpu_support_status: "verified"`. Do not
+silently fall back to CPU when GPU is required. Claim that GPU was used only when the result
+explicitly returns `selected_backend: "gpu"`; `auto` does not prove GPU use.
+
+Keep the three state channels separate:
+
+- `execution`: prepared/submitted/queued/running/scheduler completion/cancelled/failed;
+- `solver`: not started/running/converged/not converged/failed/unknown;
+- `scientific`: unreviewed, scientifically accepted, accepted with limitations, needs
+  recalculation, not assessable, failed or archived.
+
+scheduler completion does not mean solver convergence, and solver convergence does not mean
+scientific acceptance. Branch on stable error codes rather than messages. Key codes include
+`PP_SET_INCOMPLETE`, `PP_POLICY_INCOMPATIBLE`,
+`PP_CAPABILITY_UNKNOWN`, `ARTIFACT_MISSING`, `SOLVER_NOT_CONVERGED`,
+`SCIENTIFIC_GATE_FAILED`, `RESTART_INCOMPATIBLE`, `IDEMPOTENCY_CONFLICT`,
+`EXECUTION_BACKEND_NOT_READY`, `GPU_UNSUPPORTED` and `GPU_UNAVAILABLE`.
+
+Submission, cancellation, retry and review are remote mutations and require the user's explicit
+authorisation. Do not retry when the outcome is unknown. Do not describe a GPU smoke test,
+scheduler log or parseable QE output as a scientific conclusion or a customer-level performance
+guarantee.

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

@@ -0,0 +1,141 @@
+# RDKit 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. This document
+records operation schemas and does not authorise direct HTTP access.
+
+Make only the calls needed to meet the request. To validate, canonicalise and calculate basic
+descriptors in one request, use `batch-parse-describe` with the `molecules:[{id,smiles}]` payload;
+do not split it into parse and descriptors calls. For all-pairs similarity across multiple
+molecules, use one `similarity-matrix` call. Its fixed ranking fields are `a`, `b` and
+`similarity`, not `i`, `j` or `score`.
+
+Report only descriptors actually present in the business response. When rendering a PNG, decode
+only the field specified in the documentation and verify that the bytes begin with
+`89 50 4e 47 0d 0a 1a 0a`; do not save a JSON envelope as an image.
+
+## Health
+
+Operation: `health`; no request body.
+
+## Parse
+
+Operation: `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
+
+Operation: `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
+
+Operation: `batch-descriptors`.
+
+```json
+{"smiles": ["CCO", "c1ccccc1"], "descriptor_set": "basic", "sanitize": true}
+```
+
+Limits: 1-500 SMILES.
+
+## Batch Parse Describe
+
+Operation: `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
+
+Operation: `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
+
+Operation: `fingerprint`.
+
+```json
+{"smiles": "CCO", "radius": 2, "n_bits": 2048}
+```
+
+Morgan fingerprint parameters: `radius` 1-6, `n_bits` 128-8192.
+
+## Similarity
+
+Operation: `similarity`.
+
+```json
+{"query_smiles": "CCO", "target_smiles": "CCCO", "radius": 2, "n_bits": 2048}
+```
+
+Returns Tanimoto similarity.
+
+## Similarity Matrix
+
+Operation: `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
+
+Operation: `substructure`.
+
+```json
+{"query_smarts": "c1ccccc1", "target_smiles": ["c1ccccc1", "CCO"]}
+```
+
+Limits: SMARTS max length 5000; target list size 1-500.

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

@@ -0,0 +1,95 @@
+# STRBO reference
+
+STRBO performs generative multi-objective optimisation for the server-fixed **KRAS G12D**
+target. The objective order is fixed as `[vina, activity]`: lower Vina is better and higher
+activity is better. `task` guides candidate generation but does not change the target; do not
+claim that user-defined receptors are supported.
+
+Use `tool="strbo"` for every call. Generation, suggestion, evaluation and job submission consume
+remote resources, so call them only when the user actually asks for the relevant research task.
+Do not retry if the outcome is unknown or the request times out.
+
+## Initialisation
+
+- Synchronous operation: `molecules-init`
+- Asynchronous operation: `molecules-init-job`
+- Validation-only operation: `molecules-init-validate`
+
+```json
+{
+  "task": "Generate candidate small molecules for KRAS G12D that balance binding and activity",
+  "num_initial": 3,
+  "seed": 42
+}
+```
+
+Use validate only when you need to check parameters. For a full run, do not validate before
+submitting; that would make an unnecessary call. A successful result should contain the same
+number of candidate SMILES as `num_initial`.
+
+## Suggest the next batch of candidates
+
+- Synchronous operation: `molecules-suggest`
+- Asynchronous operation: `molecules-suggest-job` (prefer it for heavy tasks)
+- Validation-only operation: `molecules-suggest-validate`
+
+```json
+{
+  "task": "Continue improving binding and activity for KRAS G12D",
+  "history_xs": ["CCO", "CCN", "CCC"],
+  "history_ys": [
+    [-6.8, 0.31],
+    [-7.1, 0.42],
+    [-6.5, 0.28]
+  ],
+  "num_suggestions": 2,
+  "seed": 42
+}
+```
+
+`history_xs` and `history_ys` must have the same length. Each `history_ys` item must contain two
+finite numbers in the exact order `[vina, activity]`. Do not present predictions as wet-lab results.
+
+## Evaluate candidates
+
+- Synchronous operation: `molecules-evaluate`
+- Asynchronous operation: `molecules-evaluate-job`
+- Validation-only operation: `molecules-evaluate-validate`
+
+```json
+{
+  "designs": ["CCO", "CCN"]
+}
+```
+
+The number of scores in a successful result must match the number of designs, with exactly two
+finite numbers per row. If any item explicitly fails, treat the entire run as failed; do not
+report only the successful subset.
+
+## Asynchronous jobs
+
+After submitting an asynchronous operation, read a non-empty `job_id` from the current business
+response, then poll:
+
+```text
+delta-cli science invoke --tool strbo --endpoint job-status --params JSON
+```
+
+Read the result only once the status changes to `succeeded`:
+
+```text
+delta-cli science invoke --tool strbo --endpoint job-result --params JSON
+```
+
+`queued` and `running` do not mean the job is complete; stop immediately on `failed`. Status
+queries may be repeated at intervals of about five seconds, but never repeat the submission
+operation. The total wait for one user task is limited to 15 minutes. If that limit is reached,
+report that the job is still incomplete and retain its `job_id`; do not claim it was cancelled
+remotely.
+
+## Complete research workflow
+
+When the user explicitly asks for a complete iteration, run `initialise → evaluate → suggest →
+evaluate` sequentially. Use only verified business responses from the current calls as inputs to
+the next step. If the user asks only for initial candidates or evaluation of supplied SMILES, do
+not expand the task into a full loop.

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

@@ -0,0 +1,201 @@
+# SynBO operation reference
+
+Make all online calls with `delta-cli science invoke`; the service address comes from the CLI's
+standard `base_url` configuration (`{base_url}/science_tool`). The paths here describe business
+operations only and do not authorise direct HTTP access.
+
+Use this section when the user asks to optimise reaction conditions, recommend the next batch of
+experiments, continue a coupling reaction, or provides solvents, temperatures, catalysts, bases,
+ligands and historical yields—even if they do not mention SynBO, BO, the CLI or field names. Make
+at most one SynBO business call per user task. Stop immediately after success; for validation
+errors, 502, 504, timeouts, disconnections or empty recommendations, do not change parameters or
+models, or retry.
+
+## Health
+
+Operation: `health`; no request body.
+
+Reports SynBO import status, Torch/CUDA runtime availability, service limits,
+default device and visible CUDA devices.
+
+Important fields inside gateway `data`:
+
+```json
+{
+  "status": "ok",
+  "synbo_available": true,
+  "metadata": {
+    "service": "synbo-service",
+    "engine": "synbo",
+    "version": "0.1.0",
+    "synbo_version": "0.1.0",
+    "default_device": "cpu",
+    "cuda_visible_devices": ""
+  },
+  "limits": {
+    "max_batch_size": 128,
+    "max_reaction_space_size": 200000,
+    "max_previous_rows": 10000
+  },
+  "runtime": {
+    "torch_available": true,
+    "cuda_available": false,
+    "cuda_device_count": 0,
+    "cuda_device_names": []
+  },
+  "warnings": []
+}
+```
+
+## Initialize
+
+Operation: `initialize`.
+
+Use for initial condition sampling when no measured previous results exist.
+
+Request body:
+
+```json
+{
+  "condition_dict": {
+    "catalyst": ["Pd(OAc)2", "Pd(PPh3)4", "Pd2(dba)3"],
+    "solvent": ["THF", "Dioxane", "Toluene"],
+    "base": ["K2CO3", "NaOEt", "DBU"]
+  },
+  "opt_metrics": ["yield"],
+  "opt_metric_settings": [
+    {"opt_direct": "max", "opt_range": [0, 100], "metric_weight": 1.0}
+  ],
+  "batch_size": 3,
+  "sampling_method": "random",
+  "desc_normalize": "minmax",
+  "random_seed": 42
+}
+```
+
+Supported `sampling_method` values: `sobol`, `random`, `lhs`, `kmeans`.
+
+## Optimize
+
+Operation: `optimize`.
+
+Use after measured experiment rows are available. Each previous row must contain
+all condition columns and all objective metric columns.
+
+Request body:
+
+```json
+{
+  "condition_dict": {
+    "catalyst": ["Pd(OAc)2", "Pd(PPh3)4", "Pd2(dba)3"],
+    "solvent": ["THF", "Dioxane", "Toluene"],
+    "base": ["K2CO3", "NaOEt", "DBU"]
+  },
+  "opt_metrics": ["yield"],
+  "previous_results": [
+    {"batch": 0, "catalyst": "Pd(OAc)2", "solvent": "THF", "base": "K2CO3", "yield": 42.0},
+    {"batch": 0, "catalyst": "Pd(PPh3)4", "solvent": "Dioxane", "base": "NaOEt", "yield": 55.0},
+    {"batch": 0, "catalyst": "Pd2(dba)3", "solvent": "Toluene", "base": "DBU", "yield": 63.0}
+  ],
+  "batch_size": 2,
+  "accuracy": "tiny",
+  "surrogate_model": "RF",
+  "acq_func": "UCB",
+  "device": "cpu",
+  "random_seed": 42
+}
+```
+
+### Discretise numeric conditions first
+
+SynBO's `condition_dict` accepts explicit lists only; it does not accept continuous range
+objects. For a task with a temperature range of 40–100°C and catalyst loading of 0.5–2.0%, with
+historical values at 60/70/80/90°C and 0.5/1.0/1.5/2.0%, use:
+
+```json
+{
+  "condition_dict": {
+    "solvent": ["ethanol", "acetonitrile", "DMSO"],
+    "temperature_C": ["40", "60", "70", "80", "90", "100"],
+    "catalyst_loading_pct": ["0.5", "1.0", "1.5", "2.0"]
+  },
+  "opt_metrics": ["yield"],
+  "previous_results": [
+    {
+      "batch": 0,
+      "solvent": "ethanol",
+      "temperature_C": "60",
+      "catalyst_loading_pct": "1.0",
+      "yield": 55.0
+    }
+  ],
+  "batch_size": 3,
+  "accuracy": "tiny",
+  "surrogate_model": "RF",
+  "acq_func": "UCB",
+  "device": "cpu",
+  "random_seed": 42
+}
+```
+
+Constraints:
+
+- Represent every condition value as a string and keep objective metrics numeric.
+- Every condition value in each `previous_results` row must appear in the corresponding `condition_dict` list.
+- The discretised grid for a continuous range must include the user's lower and upper bounds and all historical observations. State the actual grid in the final answer.
+- Serialise condition values explicitly as strings, and ensure each historical row uses only values listed in `condition_dict`. For a small-data CPU configuration, pass `accuracy:"tiny"`, `surrogate_model:"RF"`, `acq_func:"UCB"` and `device:"cpu"` explicitly; do not assume the client supplies defaults.
+
+Useful optional fields:
+
+- `accuracy`: `tiny`, `low`, `medium`, `high`, or `ultra`.
+- `acq_func`: `EHVI`, `UCB`, `ParEGO`, or `NEI`.
+- `surrogate_model`: `GP`, `RF`, `BNN`, or `BayesianLinear`.
+- `device`: `cpu`, `auto`, `cuda`, or `cuda:0`.
+- `cuda_visible_devices`: request-level CUDA visibility hint. Use only when the
+  user explicitly asks for it and `/health` indicates a CUDA-capable runtime.
+- `constraints`: map condition type to prohibited values.
+
+## Descriptors
+
+If omitted, SynBO uses generated OneHot descriptors. To provide descriptors:
+
+```json
+{
+  "descriptors": {
+    "solvent": [
+      {"name": "THF", "polarity": 0.207, "boiling_point_C": 66.0},
+      {"name": "Toluene", "polarity": 0.099, "boiling_point_C": 110.6}
+    ]
+  },
+  "descriptor_index_col": "name"
+}
+```
+
+`descriptors` must contain exactly the same keys as `condition_dict`. Descriptor
+rows must include the configured index column and numeric descriptor columns.
+
+## Error Handling
+
+Gateway errors have the standard envelope:
+
+```json
+{
+  "code": 1,
+  "message": "SynBO service returned HTTP 400",
+  "data": {
+    "endpoint": "/synbo/optimize",
+    "synbo_response": {
+      "detail": "previous_results is missing metric columns: ['yield']"
+    }
+  }
+}
+```
+
+Common causes include an oversized condition space, duplicate condition values, historical
+condition values absent from `condition_dict`, non-numeric descriptors, missing columns in
+historical rows, non-numeric metrics, and a CUDA request when no GPU is available.
+
+The server has a per-request timeout independent of the client. GP, EHVI, high accuracy or busy
+shared resources may cause a timeout. Do not automatically change parameters and retry during an
+ordinary user task. Report “no recommendations were produced”, preserve the error, and let the
+user decide whether to start a separate, explicitly requested regression test.