@delta-agentcloud/cli 0.0.0-stage → 1.1.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/README.md +511 -2
  2. package/checksums.txt +5 -0
  3. package/package.json +47 -4
  4. package/scripts/install-wizard.js +683 -0
  5. package/scripts/install.js +435 -0
  6. package/scripts/run.js +65 -0
  7. package/skills/delta-protein/AGENTS.md +73 -0
  8. package/skills/delta-protein/SKILL.md +389 -0
  9. package/skills/delta-protein/agents/openai.yaml +4 -0
  10. package/skills/delta-protein/references/bfitter.md +64 -0
  11. package/skills/delta-protein/references/catapro_predict.md +63 -0
  12. package/skills/delta-protein/references/catpred_predict.md +65 -0
  13. package/skills/delta-protein/references/caver_tunnel_analyze.md +63 -0
  14. package/skills/delta-protein/references/consensus_mutation.md +61 -0
  15. package/skills/delta-protein/references/consurf_predict.md +67 -0
  16. package/skills/delta-protein/references/crop_sequence.md +69 -0
  17. package/skills/delta-protein/references/dock.md +82 -0
  18. package/skills/delta-protein/references/dock_score.md +70 -0
  19. package/skills/delta-protein/references/easifa_predict_active_site.md +70 -0
  20. package/skills/delta-protein/references/ephod_predict_mutation.md +66 -0
  21. package/skills/delta-protein/references/ephod_predict_protein.md +61 -0
  22. package/skills/delta-protein/references/esmfold2_predict.md +67 -0
  23. package/skills/delta-protein/references/evcouplings_mutation.md +64 -0
  24. package/skills/delta-protein/references/fasta_to_sequence.md +59 -0
  25. package/skills/delta-protein/references/foldseek.md +61 -0
  26. package/skills/delta-protein/references/generate_msa.md +61 -0
  27. package/skills/delta-protein/references/interpro_analyze.md +63 -0
  28. package/skills/delta-protein/references/mpnn_design_sequence.md +71 -0
  29. package/skills/delta-protein/references/multievolve.md +73 -0
  30. package/skills/delta-protein/references/pisa_query.md +70 -0
  31. package/skills/delta-protein/references/plip_analyze.md +65 -0
  32. package/skills/delta-protein/references/pocket_prediction.md +63 -0
  33. package/skills/delta-protein/references/protein_design.md +65 -0
  34. package/skills/delta-protein/references/protein_evolution.md +77 -0
  35. package/skills/delta-protein/references/protein_sol_predict_mutation.md +66 -0
  36. package/skills/delta-protein/references/protein_sol_predict_protein.md +61 -0
  37. package/skills/delta-protein/references/protenix.md +66 -0
  38. package/skills/delta-protein/references/protrek_search.md +90 -0
  39. package/skills/delta-protein/references/pubchem_search.md +68 -0
  40. package/skills/delta-protein/references/pubmed_search.md +79 -0
  41. package/skills/delta-protein/references/reap_design_primer.md +69 -0
  42. package/skills/delta-protein/references/rfd3_design.md +65 -0
  43. package/skills/delta-protein/references/structure_to_sequence.md +61 -0
  44. package/skills/delta-protein/references/summarize_result.md +68 -0
  45. package/skills/delta-protein/references/surface_charge.md +84 -0
  46. package/skills/delta-protein/references/uniprot_batch_query.md +63 -0
  47. package/skills/delta-protein/references/uniprot_query.md +64 -0
  48. package/skills/delta-protein/references/zero_shot_mutant_candidates.md +76 -0
  49. package/skills/delta-protein/scripts/gen_references.py +167 -0
  50. package/skills/delta-protein/scripts/output_metadata.json +275 -0
  51. package/skills/delta-sandbox/SKILL.md +388 -0
  52. package/skills/delta-sandbox/agents/openai.yaml +4 -0
  53. package/skills/delta-sandbox/references/commands.md +58 -0
  54. package/skills/delta-sandbox/references/lifecycle.md +100 -0
  55. package/skills/delta-sandbox/references/recipes.md +138 -0
  56. package/skills/delta-science/AGENTS.md +47 -0
  57. package/skills/delta-science/SKILL.md +227 -0
  58. package/skills/delta-science/agents/openai.yaml +4 -0
  59. package/skills/delta-science/references/antbo.md +105 -0
  60. package/skills/delta-science/references/delta-bo.md +92 -0
  61. package/skills/delta-science/references/gsasii.md +118 -0
  62. package/skills/delta-science/references/lammps.md +68 -0
  63. package/skills/delta-science/references/ldm-bo.md +132 -0
  64. package/skills/delta-science/references/materials-design.md +130 -0
  65. package/skills/delta-science/references/pubchem.md +128 -0
  66. package/skills/delta-science/references/pymatgen.md +69 -0
  67. package/skills/delta-science/references/qe.md +134 -0
  68. package/skills/delta-science/references/rdkit.md +141 -0
  69. package/skills/delta-science/references/strbo.md +95 -0
  70. package/skills/delta-science/references/synbo.md +201 -0
  71. package/skills/delta-science/references/xrd.md +704 -0
  72. package/skills/delta-science/scripts/catalog.py +92 -0
  73. package/skills/delta-science/scripts/generated_catalog.py +69 -0
  74. package/skills/delta-science/scripts/invoke.py +346 -0
  75. package/skills/delta-shared/SKILL.md +113 -0
  76. package/skills/delta-shared/agents/openai.yaml +4 -0
  77. package/skills/manifest.json +20 -0
@@ -0,0 +1,92 @@
1
+ # Delta-BO reference
2
+
3
+ Make all online calls with `delta-cli science invoke`; the tool is always `delta-bo`. The current
4
+ CLI catalogue exposes only `commands` and `generate`. Do not infer operations from old HTTP
5
+ documentation or call the stateful command API directly.
6
+
7
+ ## commands
8
+
9
+ Use case: The user asks which Delta-BO commands are supported by the current deployment.
10
+
11
+ ```text
12
+ delta-cli science invoke --tool delta-bo --endpoint commands
13
+ ```
14
+
15
+ No request body. Report only the command list in the current business response; do not fill it in from historical documentation.
16
+
17
+ ## generate
18
+
19
+ Use case: Generate random-search or Bayesian-optimisation suggestions for numeric, integer or categorical experimental variables.
20
+
21
+ When there is no real history, or fewer than five historical observations and the user has not explicitly requested BO, use bounded random search:
22
+
23
+ ```json
24
+ {
25
+ "params": [
26
+ {"name": "x", "type": "numeric", "low": 0.0, "high": 1.0}
27
+ ],
28
+ "num_suggestions": 3,
29
+ "algorithm": "random-search",
30
+ "seed": 42
31
+ }
32
+ ```
33
+
34
+ When real history is available and the user explicitly requests BO, you may use:
35
+
36
+ ```json
37
+ {
38
+ "params": [
39
+ {"name": "temperature", "type": "numeric", "low": 20.0, "high": 120.0},
40
+ {"name": "catalyst", "type": "categorical", "choices": ["A", "B", "C"]}
41
+ ],
42
+ "objectives": [{"name": "yield", "minimize": false}],
43
+ "num_suggestions": 2,
44
+ "algorithm": "bo",
45
+ "model": {"name": "gp", "min_samples": 2, "train_steps": 50},
46
+ "acq_target": {"name": "ucb", "beta": 2.0},
47
+ "solver": {"name": "ga", "pop_size": 40, "n_gen": 10},
48
+ "histories": {
49
+ "decisions": [
50
+ {"temperature": 40.0, "catalyst": "A"},
51
+ {"temperature": 80.0, "catalyst": "B"}
52
+ ],
53
+ "observations": [
54
+ {"yield": 0.42},
55
+ {"yield": 0.61}
56
+ ]
57
+ },
58
+ "seed": 7
59
+ }
60
+ ```
61
+
62
+ Supported parameter types are `numeric`, `integer` and `categorical`. Prefer object-form history
63
+ to avoid ambiguity about the order of array columns. Do not invent observations, objective values
64
+ or purported optima.
65
+
66
+ Optional deduplication and constraints:
67
+
68
+ ```json
69
+ {
70
+ "diversity": {
71
+ "deduplicate": true,
72
+ "min_numeric_distance": {"temperature": 5.0},
73
+ "prefer_unique_categories": true
74
+ },
75
+ "constraints": [
76
+ {"type": "unique_batch"},
77
+ {"type": "avoid_seen_decisions"}
78
+ ]
79
+ }
80
+ ```
81
+
82
+ Report only fields actually present in the business response: `suggestions`,
83
+ `suggestion_metadata`, `warnings`, `generated_candidate_count` and `diversity`. Do not replace
84
+ empty suggestions or a failure with local GP, UCB or random-number results.
85
+
86
+ ## Known legacy capabilities that are not exposed
87
+
88
+ The old service included stateful commands such as session, space, objective, policy, suggest,
89
+ observe, loop, status and best, but they are not current Delta CLI operations. This Skill records
90
+ only that capability boundary: it includes no URL or curl examples and does not run those
91
+ operations. To extend the interface, first expose the operation and request schema through Science
92
+ Server, then update this reference.
@@ -0,0 +1,118 @@
1
+ # GSAS-II reference
2
+
3
+ Make all calls with `delta-cli science invoke`. Simulation requires a real CIF; refinement
4
+ requires real powder data, instrument parameters and phase CIFs. Never fill in a failed result
5
+ with synthetic data. If the input is not a CIF, first use a successful pymatgen
6
+ `structure-convert` result from the current task.
7
+
8
+ ## Health
9
+
10
+ Operation: `health`; no request body.
11
+
12
+ Key response fields in `data`: `status`, `service`, `gsasii_available`,
13
+ `metadata`, and `limits`.
14
+
15
+ Call this only when the user explicitly asks for a health check; do not add a health call automatically before simulation or refinement.
16
+
17
+ ## Powder Simulation
18
+
19
+ Operation: `powder-simulate`.
20
+
21
+ ```json
22
+ {
23
+ "cif": "<CIF text>",
24
+ "phase_name": "phase",
25
+ "instrument_parameters": "<GSAS-II instrument parameter text>",
26
+ "histogram_name": "simulation",
27
+ "t_min": 10.0,
28
+ "t_max": 80.0,
29
+ "t_step": 0.02,
30
+ "include_profile": true,
31
+ "max_profile_points": 1000,
32
+ "include_reflections": true,
33
+ "max_reflections": 1000,
34
+ "return_refined_cif": false,
35
+ "return_project": false
36
+ }
37
+ ```
38
+
39
+ Use either `t_step` or `n_points`, not both. Optional fields include
40
+ `wavelength`, `radiation`, `scale`, `include_profile`, `max_profile_points`,
41
+ `include_reflections`, `max_reflections`, `return_refined_cif`, and
42
+ `return_project`.
43
+
44
+ The response includes `profile` points with `x`, `y_calc`, optional background,
45
+ bounded `reflections` with hkl/d-spacing/2theta where available, and metadata.
46
+ If `return_project` is true, `project_base64` contains the GSAS-II `.gpx`
47
+ project. If `return_refined_cif` is true, `refined_cif` contains exported CIF
48
+ text for pymatgen handoff when GSAS-II supports export for the phase.
49
+
50
+ Notes:
51
+
52
+ - `cif` should be valid CIF text. If the input is POSCAR/JSON/CSSR/XSF, use
53
+ pymatgen `structure-convert` first with `output_format: "cif"`.
54
+ - `instrument_parameters` should be GSAS-II instrument parameter text such as
55
+ `INST_XRY.PRM` when instrument-specific simulation is needed.
56
+ - For quick simulation only, `instrument_parameters` may be omitted. The service
57
+ then generates a simple CW X-ray instrument model from `wavelength` or
58
+ `radiation` (`CuKa` by default; also supports aliases such as `MoKa`, `CoKa`,
59
+ `CrKa`, and explicit numeric wavelength).
60
+ - Refinement still requires real `instrument_parameters`.
61
+ - `max_profile_points` controls response sampling. Use small values for smoke
62
+ tests and larger values for profile comparison.
63
+ - Older deployed gateway images may require `max_profile_points >= 10`.
64
+
65
+ ## Powder Refinement
66
+
67
+ Operation: `powder-refine`.
68
+
69
+ ```json
70
+ {
71
+ "powder_data": "<two-column or three-column powder data text>",
72
+ "powder_format": "xy",
73
+ "instrument_parameters": "<GSAS-II instrument parameter text>",
74
+ "phases": [
75
+ {"name": "phase", "cif": "<CIF text>"}
76
+ ],
77
+ "refinement_mode": "rietveld",
78
+ "refinement_steps": [],
79
+ "max_cycles": 3,
80
+ "histogram_name": "powder",
81
+ "include_profile": true,
82
+ "max_profile_points": 1000,
83
+ "include_reflections": true,
84
+ "max_reflections": 1000,
85
+ "return_refined_cif": false,
86
+ "return_project": false
87
+ }
88
+ ```
89
+
90
+ Supported `powder_format` values: `xy`, `xye`, `fxye`, `gsas`, and `csv`.
91
+
92
+ `refinement_mode: "rietveld"` is currently implemented. `pawley` and `lebail`
93
+ return a clear not-implemented response until the service wires the
94
+ mode-specific GSAS-II setup.
95
+
96
+ The response includes fit `residuals` when available, phase summaries, sampled
97
+ profile points, bounded `reflections`, warnings, optional `refined_cif`, and
98
+ the optional `.gpx` project.
99
+
100
+ Notes:
101
+
102
+ - Use `xy` for simple whitespace-delimited `x y` rows, `xye` for `x y esd`,
103
+ `csv` for numeric comma-separated rows, or `gsas`/`fxye` for GSAS-like powder
104
+ formats.
105
+ - `max_cycles: 0` is useful for project-construction smoke tests. Increase it
106
+ only when the powder data, phase model, instrument file, and refinement steps
107
+ are realistic.
108
+ - `refinement_steps` is passed to `G2Project.do_refinements`. Keep recipes
109
+ incremental and inspect `warnings`, `residuals`, and `lst` output.
110
+ - Refinement may return `valid: false` with partial phase/profile information
111
+ if GSAS-II constructed the project but a refinement step failed.
112
+
113
+ ## Cross-tool hand-off
114
+
115
+ Complete structure conversion, diffraction simulation and refinement step by step through the
116
+ CLI within this Skill: `pymatgen structure-convert -> gsasii powder-simulate/powder-refine`.
117
+ Use downstream only the structure text or profile from the preceding successful business response;
118
+ do not run local scripts or call the service directly.
@@ -0,0 +1,68 @@
1
+ # LAMMPS reference
2
+
3
+ Make all calls with `delta-cli science invoke`. LAMMPS does not infer data files, atom types,
4
+ potentials or boundary conditions from a formula, CIF or POSCAR. Successful execution does not
5
+ establish physical convergence or production readiness.
6
+
7
+ ## Health
8
+
9
+ Operation: `health`; no request body.
10
+
11
+ Key response fields in `data`: `status`, `service`, `lammps_available`,
12
+ `metadata`, and `limits`.
13
+
14
+ Call this only when the user explicitly asks for a health check; do not add a health call automatically before simulation.
15
+
16
+ ## Built-In Lennard-Jones Example
17
+
18
+ Operation: `lj-melt-example`.
19
+
20
+ Returns a complete `request` payload for the `run` operation, plus workflow notes
21
+ showing where pymatgen and GSAS-II fit around LAMMPS.
22
+
23
+ ## Run
24
+
25
+ Operation: `run`.
26
+
27
+ ```json
28
+ {
29
+ "input_script": "<LAMMPS input script>",
30
+ "files": [
31
+ {"path": "system.data", "content": "<LAMMPS data file text>", "encoding": "text"}
32
+ ],
33
+ "timeout_seconds": 30,
34
+ "max_thermo_rows": 1000,
35
+ "log_tail_lines": 200,
36
+ "output_files": ["dump.lammpstrj", "final.data"],
37
+ "include_log": true,
38
+ "include_stdout": false,
39
+ "include_stderr": false
40
+ }
41
+ ```
42
+
43
+ `files` are written into a fresh job working directory before LAMMPS starts.
44
+ `encoding` can be `text` or `base64`.
45
+
46
+ The response includes parsed thermo rows, the final thermo row, atom count when
47
+ detectable, log tail, warnings, and requested output files. Text output files
48
+ return `content`; binary output files return `content_base64`.
49
+
50
+ Notes:
51
+
52
+ - Use relative file paths only.
53
+ - The service rejects unsafe commands such as `shell`, `python`, `plugin`, and
54
+ `jump` by default.
55
+ - `include <relative-file>` is allowed when the included file is supplied in
56
+ `files`; absolute paths, parent-directory traversal, URLs, and `jump` loops
57
+ are rejected.
58
+ - Dump/data products are returned as raw requested output files, not structured
59
+ parsed atom-frame objects.
60
+ - The gateway is synchronous; keep interactive runs short.
61
+ - Force-field choice is caller responsibility. The service executes explicit
62
+ LAMMPS input and does not infer potentials from formulas or structures.
63
+
64
+ In the final reply, include only `last_thermo`, the final step/temperature/total energy,
65
+ warnings, and a summary of output files requested by the user from the current business response.
66
+ Do not divide total energy by the atom count, substitute steps, convert units, or infer
67
+ convergence or stability. For the minimal example, call `lj-melt-example` first, then pass its
68
+ `request` from the current business response to `run` unchanged; do not pass the outer CLI envelope.
@@ -0,0 +1,132 @@
1
+ # LDM-BO reference
2
+
3
+ Make all calls with `delta-cli science invoke`; do not use the local PDF2Dock runner. This tool is
4
+ for small-molecule SMILES only. Use the AntBO capability boundary for antibody, CDRH3 or AntBO
5
+ tasks. The server injects the provider, model paths and Vina/ReaSyn/GPU/LLM settings; do not put
6
+ them in the request JSON.
7
+
8
+ ## Health
9
+
10
+ Operation: `health`; no request body.
11
+
12
+ The response reports whether the adapter can see the mounted PDF2Dock
13
+ interpreter, `bo_api.py`, Vina binary, ReaSyn repo/interpreter/checkpoints, NN
14
+ model files, cache directory, GPU settings, and LLM configuration. Missing LLM
15
+ settings degrade health because LDM methods need them.
16
+
17
+ ## One-Step Recommend
18
+
19
+ Operation: `recommend`.
20
+
21
+ Wraps `bo_api.recommend_next_smiles`.
22
+
23
+ Typical payload:
24
+
25
+ ```json
26
+ {
27
+ "method": "bo-tanimoto",
28
+ "pool": ["CCO", "CCN", "CCC"],
29
+ "history": [
30
+ {"smiles": "CCO", "scores": [-7.1]},
31
+ {"smiles": "CCN", "scores": [-6.8]}
32
+ ],
33
+ "batch_size": 1
34
+ }
35
+ ```
36
+
37
+ Typical business response inside the documented gateway `data`:
38
+
39
+ ```json
40
+ {
41
+ "recommendations": ["CCC"],
42
+ "acquisition_values": [0.12],
43
+ "n_objectives": 1
44
+ }
45
+ ```
46
+
47
+ LDM methods may include an `llm` diagnostics object.
48
+
49
+ Report `acquisition_values` exactly as returned in the business response. Unless the current
50
+ business response explicitly defines the field, do not describe it as predicted Vina, a predicted
51
+ objective, uncertainty, confidence or expected improvement, and do not infer whether higher or
52
+ lower is better. If the service provides no recommendation rationale, state “The service returned
53
+ no recommendation rationale”; do not add an explanation based on molecular scaffolds, heteroatoms
54
+ or model mechanisms.
55
+
56
+ ## Full Trajectory
57
+
58
+ Operation: `trajectory`.
59
+
60
+ Wraps `bo_api.run_search_trajectory`.
61
+
62
+ Small smoke payload:
63
+
64
+ ```json
65
+ {
66
+ "method": "bo-tanimoto",
67
+ "seed": 42,
68
+ "seed-smiles": "CCO,CCN,CCC",
69
+ "num-evaluations": 4,
70
+ "batch-size": 1,
71
+ "objective": "vina+nn"
72
+ }
73
+ ```
74
+
75
+ Typical business response inside the documented gateway `data`:
76
+
77
+ ```json
78
+ {
79
+ "config": {},
80
+ "history": [],
81
+ "summary": {}
82
+ }
83
+ ```
84
+
85
+ LDM methods may include `llm_trajectory`.
86
+
87
+ ## Error Handling
88
+
89
+ The service maps `bo_api` error JSON to an upstream failure. The gateway
90
+ returns a standard error envelope:
91
+
92
+ ```json
93
+ {
94
+ "code": 1,
95
+ "message": "AutoDock Vina executable not found...",
96
+ "data": {
97
+ "endpoint": "/v1/trajectory",
98
+ "ldm_bo_response": {
99
+ "error": "...",
100
+ "error_type": "ValueError",
101
+ "traceback": "Traceback ..."
102
+ }
103
+ }
104
+ }
105
+ ```
106
+
107
+ Common causes are missing Vina, missing ReaSyn, wrong Python interpreter, CUDA
108
+ device mismatch, missing LLM credentials for LDM methods, or an unwritable Vina
109
+ cache directory.
110
+
111
+ ## Provider Settings
112
+
113
+ Do not send provider settings in request JSON. The adapter reads these from
114
+ deployment config and passes them as Python kwargs to `bo_api`:
115
+
116
+ ```text
117
+ vina_bin
118
+ vina_cache_dir
119
+ vina_max_workers
120
+ gp_device
121
+ reasyn_repo
122
+ reasyn_python_bin
123
+ reasyn_model_path
124
+ reasyn_devices
125
+ nn_model_path
126
+ nn_metadata_path
127
+ llm_model
128
+ llm_base_url
129
+ llm_api_key
130
+ ```
131
+
132
+ The CLI forwards the user payload; `bo_api` owns business defaults and schema behavior.
@@ -0,0 +1,130 @@
1
+ # Materials Design reference
2
+
3
+ Materials Design builds surrogate models from experimental or computational materials tables,
4
+ validates models, defines feasible candidate spaces, and ranks candidates with uncertainty
5
+ estimates. Recommendations are hypotheses to validate, not confirmed materials, synthesis routes
6
+ or experimental results.
7
+
8
+ The routing label for this reference is `materials-design`. Use the current output of
9
+ `delta-cli science list` and `delta-cli science endpoints list <tool>` as the authority for
10
+ `tools.name` and `tool_endpoints.name`. The Gateway paths below describe the service contract;
11
+ they are not URLs to construct or access directly.
12
+
13
+ ## Service boundary
14
+
15
+ The service provides the following capabilities:
16
+
17
+ | Service path | Purpose | Result boundary |
18
+ | --- | --- | --- |
19
+ | `/chem/materials-design/health` | Gateway-to-service readiness check | `status`, dependency availability, limits |
20
+ | `/chem/materials-design/v1/capabilities` | Input formats, models, validation modes and limits | Capability catalogue |
21
+ | `/chem/materials-design/v1/jobs` | Upload training/candidate tables and create an asynchronous job | `202`, `job_id`, status and links |
22
+ | `/chem/materials-design/v1/jobs/{job_id}` | Read job status | `status`, `result_status`, result, warnings |
23
+ | `/chem/materials-design/v1/jobs/{job_id}/cancel` | Request cancellation | Cancellation request/final state |
24
+ | `/chem/materials-design/v1/jobs/{job_id}/artifacts` | List artifacts | name, size, media_type, SHA-256 |
25
+ | `/chem/materials-design/v1/jobs/{job_id}/artifacts/{path}` | Download one artifact | Raw report/JSON/CSV/figure bytes |
26
+
27
+ Route all JSON/query calls through:
28
+
29
+ ```text
30
+ delta-cli science invoke --tool TOOL --endpoint ENDPOINT --data JSON
31
+ ```
32
+
33
+ Submit training tables through the controlled file adapter:
34
+
35
+ ```text
36
+ delta-cli science file invoke --tool materials-design --endpoint job-submit \
37
+ --file train.xlsx --candidate-file candidates.xlsx --data CONFIG_JSON
38
+ delta-cli science task submit --tool materials-design --operation job-status \
39
+ --input '{"job_id":"mdjob_..."}' --wait
40
+ delta-cli science file download --tool materials-design --endpoint artifact-download \
41
+ --params '{"job_id":"mdjob_...","artifact_path":"report.html"}' --output report.html
42
+ ```
43
+
44
+ Use `--params JSON` only for read-only query operations. If a new tool is absent from the
45
+ catalogue, or the catalogue does not return enough request-schema detail, stop and report that it
46
+ is not exposed. Do not guess endpoint names, bodies or compatibility aliases.
47
+
48
+ ## CLI capability boundaries
49
+
50
+ The raw service request for `POST /v1/jobs` is `multipart/form-data` and contains at least:
51
+
52
+ ```text
53
+ file=<training table>
54
+ candidate_file=<optional candidate table>
55
+ config=<serialized JSON object>
56
+ ```
57
+
58
+ `science invoke` accepts only a JSON object body and JSON query parameters; it cannot express
59
+ multipart data. Do not disguise a local path or base64 as a file field. Artifact downloads are
60
+ also raw bytes: save and verify them with `science file download`, and do not treat them as
61
+ ordinary JSON results. Do not call `materials-design-service:8900` or connect directly to the
62
+ preflight Gateway.
63
+
64
+ ## Inputs and configuration
65
+
66
+ Before modelling, confirm:
67
+
68
+ - `feature_columns`, `controllable_columns`, `target_column` or `objectives`;
69
+ - identifier, metadata, leakage, post-measurement and group/time columns, and their units;
70
+ - objective direction, feasibility constraints, candidate table or candidate-generation rules;
71
+ - missing values, duplicate samples, measurement conditions, data sources and validation split strategy.
72
+
73
+ Core fields for a single-objective configuration:
74
+
75
+ ```json
76
+ {
77
+ "feature_columns": ["Bi", "In", "Ti"],
78
+ "controllable_columns": ["Bi", "In", "Ti"],
79
+ "identifier_columns": ["sample_id"],
80
+ "target_column": "T",
81
+ "target_direction": "maximize",
82
+ "validation": {"strategy": "kfold", "n_splits": 5},
83
+ "model_names": ["ExtraTrees", "GPR", "Ridge"],
84
+ "random_state": 42,
85
+ "recommendation_count": 10
86
+ }
87
+ ```
88
+
89
+ For multiple objectives, use `objectives: [{"target_column": "...", "direction": "maximize|minimize"}]`
90
+ and explicit Pareto/EHVI settings. Prefer the user's `candidate_file`. If the service generates
91
+ candidates from observed ranges, explicitly preserve steps, hard constraints, composition
92
+ closure, `max_candidates` and `allow_extrapolation`. Do not optimise identifier, post-measurement
93
+ or leakage columns, or out-of-domain points without authorisation. Do not extrapolate arbitrarily
94
+ to fill the candidate count.
95
+
96
+ ## Results handling
97
+
98
+ Assess job `status` and `result_status` separately:
99
+
100
+ - `status`: `pending`, `running`, `completed`, `failed` or `cancelled`;
101
+ - `result_status`: `complete`, `exploratory`, `readiness_only` or `failed`.
102
+
103
+ `202` means only that the service accepted or queued the job; it does not mean model training is
104
+ complete. `completed` does not mean the ranking is reliable. Say that the data and validation
105
+ support candidate ranking only when `result_status` is `complete`. Treat `exploratory` only as a
106
+ learning hypothesis; for `readiness_only`, read the readiness information and request missing
107
+ inputs; report `failed` as returned. Always preserve the returned validation, ranking, warnings
108
+ and error.
109
+
110
+ Keep predictions distinct from observations and cross-validation predictions. At minimum, report
111
+ data coverage, the split, model comparisons, uncertainty calibration, candidate feasibility,
112
+ in-domain/out-of-domain status, EI/PI/UCB or Pareto settings, and the plan for experimental
113
+ validation. Do not present model variance as experimental error or candidate predictions as
114
+ measured values.
115
+
116
+ ## Artifacts and errors
117
+
118
+ Read artifacts only when the user asks for them or the workflow requires them. Verify downloaded
119
+ content against the `size`, `media_type` and SHA-256 returned by the listing; do not infer formats
120
+ from filenames. The service may produce `report.html`, `result.json`,
121
+ `data_dictionary.json`, `model_comparison.csv`, OOF/residual/calibration files,
122
+ `search_space.json`, `candidate_predictions.csv`, `shortlist.csv`, `recommendation_views.csv`,
123
+ `pareto_front.csv` and `figures/*`.
124
+
125
+ Common terminal conditions include configuration/file-format errors, a missing target or
126
+ candidate space, upload/row/candidate-count limits being exceeded, an unready backend, or a
127
+ missing job or artifact. Do not retry blindly after a submission timeout or disconnection: a
128
+ multipart upload may already have created a job, so first check whether a `job_id` was returned.
129
+ Do not replace a failure or empty recommendation with local regression, GP, random numbers or a
130
+ manual ranking.
@@ -0,0 +1,128 @@
1
+ # PubChem reference
2
+
3
+ Call this tool only through `delta-cli science invoke`. Business responses are in the top-level
4
+ CLI `data`; read only the fields described here and do not search recursively. URLs in this file
5
+ explain the endpoint schema and do not authorise direct HTTP access. For a basic lookup by a
6
+ single common name, call `compound-summary` once. For multiple names, call
7
+ `compound-batch-summary` once with a default body containing only `identifiers` and
8
+ `namespace:"name"`; do not call health or schema first.
9
+
10
+ Project results directly from `data`. Batch records are in `data.results[*]`, the original label
11
+ is in `input`, and properties are nested under `properties`. Use this fixed SMILES fallback
12
+ order: `CanonicalSMILES -> ConnectivitySMILES -> SMILES -> IsomericSMILES`. Do not treat PubChem
13
+ `XLogP` and RDKit `MolLogP` as interchangeable; do not fill a `not_found` result with local
14
+ calculations.
15
+
16
+ Namespaces: `cid`, `name`, `smiles`, `inchi`, `inchikey`, `formula`.
17
+
18
+ ## Health
19
+
20
+ Operation: `health`; no request body.
21
+
22
+ ## Resolve CIDs
23
+
24
+ Operation: `compound-resolve-cids`.
25
+
26
+ ```json
27
+ {"identifier": "aspirin", "namespace": "name", "max_records": 20}
28
+ ```
29
+
30
+ `max_records`: 1-100.
31
+
32
+ ## Properties
33
+
34
+ Operation: `compound-properties`.
35
+
36
+ ```json
37
+ {
38
+ "identifier": "2244",
39
+ "namespace": "cid",
40
+ "properties": ["MolecularFormula", "MolecularWeight", "CanonicalSMILES", "IUPACName"]
41
+ }
42
+ ```
43
+
44
+ Allowed properties include `MolecularFormula`, `MolecularWeight`,
45
+ `CanonicalSMILES`, `IsomericSMILES`, `SMILES`, `ConnectivitySMILES`,
46
+ `IUPACName`, `InChI`, `InChIKey`, `XLogP`, `TPSA`, `HBondDonorCount`,
47
+ `HBondAcceptorCount`, `RotatableBondCount`, `ExactMass`, `MonoisotopicMass`,
48
+ `Charge`, `HeavyAtomCount`, `Complexity`, `CovalentUnitCount`,
49
+ `DefinedAtomStereoCount`, `UndefinedAtomStereoCount`, `DefinedBondStereoCount`,
50
+ `UndefinedBondStereoCount`, and `IsotopeAtomCount`.
51
+
52
+ ## Synonyms
53
+
54
+ Operation: `compound-synonyms`.
55
+
56
+ ```json
57
+ {"identifier": "2244", "namespace": "cid", "max_synonyms": 50}
58
+ ```
59
+
60
+ `max_synonyms`: 1-500.
61
+
62
+ ## Summary
63
+
64
+ Operation: `compound-summary`.
65
+
66
+ ```json
67
+ {
68
+ "identifier": "aspirin",
69
+ "namespace": "name",
70
+ "properties": ["MolecularFormula", "MolecularWeight", "CanonicalSMILES", "IUPACName"],
71
+ "synonym_limit": 20
72
+ }
73
+ ```
74
+
75
+ `synonym_limit`: 0-100. Use this endpoint for general compound lookup because
76
+ it resolves CID, selected properties, and synonyms in one call.
77
+
78
+ Response fields include `valid`, `cid`, `properties`, `properties_raw`,
79
+ `aliases`, `synonyms`, and `metadata`. Numeric properties are coerced to JSON
80
+ numbers when possible. Requested SMILES aliases are filled when PubChem returns
81
+ an equivalent key such as `ConnectivitySMILES`.
82
+
83
+ ## Batch Summary
84
+
85
+ Operation: `compound-batch-summary`.
86
+
87
+ ```json
88
+ {
89
+ "identifiers": ["aspirin", "ibuprofen", "caffeine"],
90
+ "namespace": "name",
91
+ "properties": ["MolecularFormula", "MolecularWeight", "CanonicalSMILES", "XLogP", "TPSA"],
92
+ "synonym_limit": 5
93
+ }
94
+ ```
95
+
96
+ Limits: 1-100 identifiers. The response preserves input order and includes
97
+ per-item errors:
98
+
99
+ ```json
100
+ {
101
+ "valid": false,
102
+ "namespace": "name",
103
+ "properties_requested": ["CanonicalSMILES"],
104
+ "results": [
105
+ {
106
+ "input": "aspirin",
107
+ "valid": true,
108
+ "cid": 2244,
109
+ "properties": {
110
+ "CanonicalSMILES": "CC(=O)Oc1ccccc1C(=O)O",
111
+ "ConnectivitySMILES": "CC(=O)Oc1ccccc1C(=O)O",
112
+ "_aliases": {"CanonicalSMILES": "ConnectivitySMILES"},
113
+ "properties_raw": {}
114
+ },
115
+ "properties_raw": {},
116
+ "aliases": {"CanonicalSMILES": "ConnectivitySMILES"},
117
+ "synonyms": []
118
+ },
119
+ {
120
+ "input": "bad-name",
121
+ "valid": false,
122
+ "error": "not found"
123
+ }
124
+ ],
125
+ "count": 2,
126
+ "failed_count": 1
127
+ }
128
+ ```