@delta-infra/cli 1.1.17 → 1.1.19

package/skills/delta-protein/references/bfitter.md

@@ -0,0 +1,64 @@
+# Protein Flexibility Analysis (`huada_protein_tools` / `bfitter`)
+
+This endpoint is a real endpoint of the `huada_protein_tools` tool. It can only be
+called via `delta-cli science invoke`; the business response described below lives
+under the CLI top-level `data` — read fields as documented in this file, do not
+recursively search. This file only documents the endpoint schema; it does not
+authorize direct HTTP. Endpoint names are authoritative as returned by
+`delta-cli science endpoints list huada_protein_tools`; use them verbatim — never
+guess, truncate, or alias.
+
+## Overview
+
+Analyze flexible sites of a protein structure and identify candidate sites suitable
+for site-directed mutagenesis/directed evolution based on the B-factor.
+- Required: `structure_file` (PDB/CIF)
+- Optional: `chain` (default A), `b_parameter` (default B)
+- Output: flexibility results `resultjson`, `download_url`
+- Use case: identify flexible regions, select mutation sites
+
+## Invocation
+
+```text
+delta-cli science invoke --tool huada_protein_tools --endpoint bfitter --data JSON
+```
+
+Required input groups (at least one per group; all groups must be satisfied):
+
+- `structure_file`
+
+Request fields:
+
+| Field | Description | Default |
+|---|---|---|
+| `structure_file` | PDB/CIF | - |
+| `chain` | Protein chain identifier, default A | A |
+| `b_parameter` | B-factor parameter, B or B+, default B | B |
+
+## Response
+
+- CLI top-level envelope: a call succeeds only when the exit code is 0 AND `ok` is `true`; the service response lives under `data`.
+- Server-side contract: `status` (success/error/partial), `message`, `tool_type`, `resultjson`, `download_url`; some endpoints also return `total_count`. `resultjson` may be a single object or an array — read only the keys documented in this file, do not recursively search.
+- Binary/file artifacts (such as the PDB/XLSX/FASTA/ZIP files that `download_url` points to) are downloaded and verified with
+  `delta-cli science file download --tool huada_protein_tools --endpoint ... --output <path>`;
+  do not treat file contents as ordinary JSON results.
+
+## Output Projection
+
+> Verification status: derived from ToolSpec/agent templates; pending live calibration
+
+- Projection content: Distribution of high/low B-factor positions and engineering implications
+- Presentation form: Residue list + text
+- Downstream reuse: flexible positions can be annotated as site-directed mutagenesis/directed-evolution candidates
+## Output Template
+
+- Title: **Protein flexibility analysis result (B-FITTER)**
+- Lead with the conclusion: distribution of high (flexible) / low (rigid) B-factor positions
+- Explain what flexible regions imply for site-directed mutagenesis / directed evolution
+
+## Boundaries & Failure Modes
+
+- File-type parameters (`structure_file`/`sequence_file`/`msa_file` etc.) take server-accessible URL/path strings, not local upload paths; a `download_url` or `pdb_url` returned by an upstream endpoint can be backfilled directly as downstream input.
+- Make only the minimal calls needed to complete the task; `--data` carries only the fields declared by this endpoint. Do not invent enum values or branches beyond the required combinations.
+- Do not pass off local tool (RDKit/pymatgen/LAMMPS/self-attached MCP) results as this endpoint's results; do not connect directly to Huada or gateway URLs.
+- On failure, report a short summary of the CLI's raw error; do not blindly retry after remote computation timeouts (the outcome may be unknown because the task may already have happened).

package/skills/delta-protein/references/catapro_predict.md

@@ -0,0 +1,63 @@
+# Enzyme Kinetic Parameter Prediction (`huada_protein_tools` / `catapro_predict`)
+
+This endpoint is a real endpoint of the `huada_protein_tools` tool. It can only be
+called via `delta-cli science invoke`; the business response described below lives
+under the CLI top-level `data` — read fields as documented in this file, do not
+recursively search. This file only documents the endpoint schema; it does not
+authorize direct HTTP. Endpoint names are authoritative as returned by
+`delta-cli science endpoints list huada_protein_tools`; use them verbatim — never
+guess, truncate, or alias.
+
+## Overview
+
+Predict enzyme kinetic parameters (kcat, Km, kcat/Km) with CataPro.
+- Required: `smiles` (substrate SMILES)
+- Optional: `protein_sequence`/`sequence_file`/`structure_file`, `chain` (A)
+- Output: prediction results `resultjson`, `download_url`
+
+## Invocation
+
+```text
+delta-cli science invoke --tool huada_protein_tools --endpoint catapro_predict --data JSON
+```
+
+Required input groups (at least one per group; all groups must be satisfied):
+
+- `smiles`
+
+Request fields:
+
+| Field | Description | Default |
+|---|---|---|
+| `smiles` | Substrate SMILES string | - |
+| `protein_sequence` |  | - |
+| `sequence_file` | FASTA/FA | - |
+| `structure_file` | PDB/CIF | - |
+| `chain` | Protein chain identifier, default A | A |
+
+## Response
+
+- CLI top-level envelope: a call succeeds only when the exit code is 0 AND `ok` is `true`; the service response lives under `data`.
+- Server-side contract: `status` (success/error/partial), `message`, `tool_type`, `resultjson`, `download_url`; some endpoints also return `total_count`. `resultjson` may be a single object or an array — read only the keys documented in this file, do not recursively search.
+- Binary/file artifacts (such as the PDB/XLSX/FASTA/ZIP files that `download_url` points to) are downloaded and verified with
+  `delta-cli science file download --tool huada_protein_tools --endpoint ... --output <path>`;
+  do not treat file contents as ordinary JSON results.
+
+## Output Projection
+
+> Verification status: derived from ToolSpec/agent templates; pending live calibration
+
+- Projection content: Enzyme kinetic parameters kcat, Km, kcat/Km predictions
+- Presentation form: Text
+- Downstream reuse: -
+## Output Template
+
+- Title: **Enzyme kinetic parameter prediction result (CataPro)**
+- Lead with the conclusion: predicted kcat, Km, kcat/Km (may include trends)
+
+## Boundaries & Failure Modes
+
+- File-type parameters (`structure_file`/`sequence_file`/`msa_file` etc.) take server-accessible URL/path strings, not local upload paths; a `download_url` or `pdb_url` returned by an upstream endpoint can be backfilled directly as downstream input.
+- Make only the minimal calls needed to complete the task; `--data` carries only the fields declared by this endpoint. Do not invent enum values or branches beyond the required combinations.
+- Do not pass off local tool (RDKit/pymatgen/LAMMPS/self-attached MCP) results as this endpoint's results; do not connect directly to Huada or gateway URLs.
+- On failure, report a short summary of the CLI's raw error; do not blindly retry after remote computation timeouts (the outcome may be unknown because the task may already have happened).

package/skills/delta-protein/references/catpred_predict.md

@@ -0,0 +1,65 @@
+# Enzyme Kinetic Parameter Prediction (`huada_protein_tools` / `catpred_predict`)
+
+This endpoint is a real endpoint of the `huada_protein_tools` tool. It can only be
+called via `delta-cli science invoke`; the business response described below lives
+under the CLI top-level `data` — read fields as documented in this file, do not
+recursively search. This file only documents the endpoint schema; it does not
+authorize direct HTTP. Endpoint names are authoritative as returned by
+`delta-cli science endpoints list huada_protein_tools`; use them verbatim — never
+guess, truncate, or alias.
+
+## Overview
+
+Predict enzyme kinetic parameters (kcat, Km, kcat/Km).
+- Required: `primary_smiles` (substrate SMILES)
+- Optional: `protein_sequence`/`sequence_file`/`structure_file`, `chain` (A), `additional_smiles`
+- Output: kinetic parameter predictions `resultjson`, `download_url`
+
+## Invocation
+
+```text
+delta-cli science invoke --tool huada_protein_tools --endpoint catpred_predict --data JSON
+```
+
+Required input groups (at least one per group; all groups must be satisfied):
+
+- `primary_smiles`
+
+Request fields:
+
+| Field | Description | Default |
+|---|---|---|
+| `primary_smiles` | Substrate SMILES string | - |
+| `protein_sequence` |  | - |
+| `sequence_file` | FASTA/FA | - |
+| `structure_file` | PDB/CIF | - |
+| `chain` | Protein chain identifier, default A | A |
+| `additional_smiles` | List of additional substrate SMILES | [] |
+
+## Response
+
+- CLI top-level envelope: a call succeeds only when the exit code is 0 AND `ok` is `true`; the service response lives under `data`.
+- Server-side contract: `status` (success/error/partial), `message`, `tool_type`, `resultjson`, `download_url`; some endpoints also return `total_count`. `resultjson` may be a single object or an array — read only the keys documented in this file, do not recursively search.
+- Binary/file artifacts (such as the PDB/XLSX/FASTA/ZIP files that `download_url` points to) are downloaded and verified with
+  `delta-cli science file download --tool huada_protein_tools --endpoint ... --output <path>`;
+  do not treat file contents as ordinary JSON results.
+
+## Output Projection
+
+> Verification status: derived from ToolSpec/agent templates; pending live calibration
+
+- Projection content: kcat, Km, kcat/Km predictions (restate resultjson per the actual keys returned)
+- Presentation form: Text
+- Downstream reuse: -
+## Output Template
+
+- Title: **Enzyme kinetic parameter prediction result (CatPred)**
+- Lead with the conclusion: predicted kcat, Km, kcat/Km and trends
+- Restate key parameters in natural language or a small table
+
+## Boundaries & Failure Modes
+
+- File-type parameters (`structure_file`/`sequence_file`/`msa_file` etc.) take server-accessible URL/path strings, not local upload paths; a `download_url` or `pdb_url` returned by an upstream endpoint can be backfilled directly as downstream input.
+- Make only the minimal calls needed to complete the task; `--data` carries only the fields declared by this endpoint. Do not invent enum values or branches beyond the required combinations.
+- Do not pass off local tool (RDKit/pymatgen/LAMMPS/self-attached MCP) results as this endpoint's results; do not connect directly to Huada or gateway URLs.
+- On failure, report a short summary of the CLI's raw error; do not blindly retry after remote computation timeouts (the outcome may be unknown because the task may already have happened).

package/skills/delta-protein/references/caver_tunnel_analyze.md

@@ -0,0 +1,63 @@
+# Protein Tunnel/Channel Analysis (`huada_protein_tools` / `caver_tunnel_analyze`)
+
+This endpoint is a real endpoint of the `huada_protein_tools` tool. It can only be
+called via `delta-cli science invoke`; the business response described below lives
+under the CLI top-level `data` — read fields as documented in this file, do not
+recursively search. This file only documents the endpoint schema; it does not
+authorize direct HTTP. Endpoint names are authoritative as returned by
+`delta-cli science endpoints list huada_protein_tools`; use them verbatim — never
+guess, truncate, or alias.
+
+## Overview
+
+Analyze protein internal tunnels and channels with CAVER 3.x.
+- Required: `structure_file` (PDB/CIF URL, local path, or 4-character PDB ID; never pass FASTA/raw sequences)
+- Optional: `probe_radius` (probe radius Å; when omitted, the server-side default is used)
+- The tunnel start is auto-predicted by PrankWeb (center of the top-ranked pocket); no manual specification needed
+- Output: tunnel analysis results, visualization/download links
+- Use case: structural analysis such as enzyme active-site channels, ligand entry/exit pathways
+
+## Invocation
+
+```text
+delta-cli science invoke --tool huada_protein_tools --endpoint caver_tunnel_analyze --data JSON
+```
+
+Required input groups (at least one per group; all groups must be satisfied):
+
+- `structure_file`
+
+Request fields:
+
+| Field | Description | Default |
+|---|---|---|
+| `structure_file` | 3D protein structure: PDB/CIF URL, local path, or 4-character PDB ID; never pass FASTA/raw sequences | - |
+| `probe_radius` | Probe radius (Å); when omitted the server-side config.yaml default is used | - |
+
+## Response
+
+- CLI top-level envelope: a call succeeds only when the exit code is 0 AND `ok` is `true`; the service response lives under `data`.
+- Server-side contract: `status` (success/error/partial), `message`, `tool_type`, `resultjson`, `download_url`; some endpoints also return `total_count`. `resultjson` may be a single object or an array — read only the keys documented in this file, do not recursively search.
+- Binary/file artifacts (such as the PDB/XLSX/FASTA/ZIP files that `download_url` points to) are downloaded and verified with
+  `delta-cli science file download --tool huada_protein_tools --endpoint ... --output <path>`;
+  do not treat file contents as ordinary JSON results.
+
+## Output Projection
+
+> Verification status: derived from ToolSpec/agent templates; pending live calibration
+
+- Projection content: Tunnel/channel location, length, bottleneck residues + visualization/download links
+- Presentation form: Text/table + links
+- Downstream reuse: -
+## Output Template
+
+- Title: **Protein tunnel/channel analysis result (CAVER)**
+- Lead with the conclusion: tunnel/channel location, length, bottleneck residues
+- Add visualization outputs to the "Result files & downloads" section
+
+## Boundaries & Failure Modes
+
+- File-type parameters (`structure_file`/`sequence_file`/`msa_file` etc.) take server-accessible URL/path strings, not local upload paths; a `download_url` or `pdb_url` returned by an upstream endpoint can be backfilled directly as downstream input.
+- Make only the minimal calls needed to complete the task; `--data` carries only the fields declared by this endpoint. Do not invent enum values or branches beyond the required combinations.
+- Do not pass off local tool (RDKit/pymatgen/LAMMPS/self-attached MCP) results as this endpoint's results; do not connect directly to Huada or gateway URLs.
+- On failure, report a short summary of the CLI's raw error; do not blindly retry after remote computation timeouts (the outcome may be unknown because the task may already have happened).

package/skills/delta-protein/references/consensus_mutation.md

@@ -0,0 +1,61 @@
+# Consensus Mutation Analysis (`huada_protein_tools` / `consensus_mutation`)
+
+This endpoint is a real endpoint of the `huada_protein_tools` tool. It can only be
+called via `delta-cli science invoke`; the business response described below lives
+under the CLI top-level `data` — read fields as documented in this file, do not
+recursively search. This file only documents the endpoint schema; it does not
+authorize direct HTTP. Endpoint names are authoritative as returned by
+`delta-cli science endpoints list huada_protein_tools`; use them verbatim — never
+guess, truncate, or alias.
+
+## Overview
+
+Consensus mutation analysis based on an aligned MSA (A3M).
+- Required: `msa_file` (A3M, usually the `download_url` from generate_msa; aligned columns contain `-` placeholders)
+- Optional: `query_id` (target sequence ID in the MSA; defaults to the first/query sequence when unspecified)
+- Output: consensus mutation analysis results, `download_url`
+- Use case: design/filter mutation sites with consensus information across homolog sequences
+
+## Invocation
+
+```text
+delta-cli science invoke --tool huada_protein_tools --endpoint consensus_mutation --data JSON
+```
+
+Required input groups (at least one per group; all groups must be satisfied):
+
+- `msa_file`
+
+Request fields:
+
+| Field | Description | Default |
+|---|---|---|
+| `msa_file` | A3M MSA | - |
+| `query_id` | Target sequence ID in the MSA; defaults to the first (query) sequence when unspecified | - |
+
+## Response
+
+- CLI top-level envelope: a call succeeds only when the exit code is 0 AND `ok` is `true`; the service response lives under `data`.
+- Server-side contract: `status` (success/error/partial), `message`, `tool_type`, `resultjson`, `download_url`; some endpoints also return `total_count`. `resultjson` may be a single object or an array — read only the keys documented in this file, do not recursively search.
+- Binary/file artifacts (such as the PDB/XLSX/FASTA/ZIP files that `download_url` points to) are downloaded and verified with
+  `delta-cli science file download --tool huada_protein_tools --endpoint ... --output <path>`;
+  do not treat file contents as ordinary JSON results.
+
+## Output Projection
+
+> Verification status: derived from ToolSpec/agent templates; pending live calibration
+
+- Projection content: Consensus mutation residues, support level and recommendation grade
+- Presentation form: Text/table
+- Downstream reuse: -
+## Output Template
+
+- Title: **Consensus mutation analysis result**
+- Lead with the conclusion: positions jointly recommended by multiple models/homolog sequences, support level and overall recommendation grade
+
+## Boundaries & Failure Modes
+
+- File-type parameters (`structure_file`/`sequence_file`/`msa_file` etc.) take server-accessible URL/path strings, not local upload paths; a `download_url` or `pdb_url` returned by an upstream endpoint can be backfilled directly as downstream input.
+- Make only the minimal calls needed to complete the task; `--data` carries only the fields declared by this endpoint. Do not invent enum values or branches beyond the required combinations.
+- Do not pass off local tool (RDKit/pymatgen/LAMMPS/self-attached MCP) results as this endpoint's results; do not connect directly to Huada or gateway URLs.
+- On failure, report a short summary of the CLI's raw error; do not blindly retry after remote computation timeouts (the outcome may be unknown because the task may already have happened).

package/skills/delta-protein/references/consurf_predict.md

@@ -0,0 +1,67 @@
+# Residue Conservation Analysis (`huada_protein_tools` / `consurf_predict`)
+
+This endpoint is a real endpoint of the `huada_protein_tools` tool. It can only be
+called via `delta-cli science invoke`; the business response described below lives
+under the CLI top-level `data` — read fields as documented in this file, do not
+recursively search. This file only documents the endpoint schema; it does not
+authorize direct HTTP. Endpoint names are authoritative as returned by
+`delta-cli science endpoints list huada_protein_tools`; use them verbatim — never
+guess, truncate, or alias.
+
+## Overview
+
+Compute protein residue conservation with ConSurf.
+- Required: `structure_file` (.pdb/.cif)
+- Required: `DB` (server-validated required; SWISS-PROT/UNIREF100, default UNIREF100 — but **must be passed explicitly**; omitting it returns a validation error)
+- Optional: `chain` (A)
+- Output: conservation results `resultjson`, `download_url`
+- Use case: identify functionally important residues, conserved regions
+
+## Invocation
+
+```text
+delta-cli science invoke --tool huada_protein_tools --endpoint consurf_predict --data JSON
+```
+
+Required input groups (at least one per group; all groups must be satisfied):
+
+- `structure_file`
+
+Request fields:
+
+| Field | Description | Default |
+|---|---|---|
+| `structure_file` | PDB/CIF | - |
+| `chain` | Protein chain identifier, default A | A |
+| `DB` | Database: SWISS-PROT/UNIREF100. **Server-required** (defaults to UNIREF100 but errors when omitted — must be passed explicitly) | UNIREF100 |
+
+## Response
+
+- CLI top-level envelope: a call succeeds only when the exit code is 0 AND `ok` is `true`; the service response lives under `data`.
+- Server-side contract: `status` (success/error/partial), `message`, `tool_type`, `resultjson`, `download_url`; some endpoints also return `total_count`. `resultjson` may be a single object or an array — read only the keys documented in this file, do not recursively search.
+- Binary/file artifacts (such as the PDB/XLSX/FASTA/ZIP files that `download_url` points to) are downloaded and verified with
+  `delta-cli science file download --tool huada_protein_tools --endpoint ... --output <path>`;
+  do not treat file contents as ordinary JSON results.
+
+## Output Projection
+
+> Verification status: verified by a real `delta-cli` invocation
+
+- Projection content: Conserved residue count and list (pos/seq/conserved_rank/conserved_score); presented grouped by conservation level
+- Presentation form: Residue list; interpretation: lower conserved_score = more conserved, larger conserved_rank = more conserved
+- Downstream reuse: conservation is only a reference annotation for the zero_shot_mutant_candidates recommendation rationale, not a recommendation criterion
+## Output Template
+
+- Title: **Residue conservation analysis result (ConSurf)**
+- Interpretation: larger conserved_rank = more conserved (7/8/9 conserved, 1/2/3 variable); lower conserved_score = more conserved
+- List positions grouped as conserved/variable (pos/residue/rank/score), explaining the functional or engineering significance of conserved/variable regions
+- May provide conservation reference notes for the "Recommendation/rationale" column of zero_shot_mutant_candidates (annotation only, not a recommendation criterion)
+
+## Boundaries & Failure Modes
+
+- `DB` is a server-required field: omitting it returns a validation error (e.g. missing DB); always pass it explicitly, e.g. `--data '{"structure_file":...,"DB":"UNIREF100"}'`.
+- General principle: fields marked as "default" in this package's references and ToolSpecs are fill-in conveniences for the backend agent orchestration layer; they are **NOT omissible when calling the CLI directly**; whatever the server actually validates is authoritative — when validation reports a missing field, supply it per the error and write it back into the reference.
+- File-type parameters (`structure_file`/`sequence_file`/`msa_file` etc.) take server-accessible URL/path strings, not local upload paths; a `download_url` or `pdb_url` returned by an upstream endpoint can be backfilled directly as downstream input.
+- Make only the minimal calls needed to complete the task; `--data` carries only the fields declared by this endpoint. Do not invent enum values or branches beyond the required combinations.
+- Do not pass off local tool (RDKit/pymatgen/LAMMPS/self-attached MCP) results as this endpoint's results; do not connect directly to Huada or gateway URLs.
+- On failure, report a short summary of the CLI's raw error; do not blindly retry after remote computation timeouts (the outcome may be unknown because the task may already have happened).

package/skills/delta-protein/references/crop_sequence.md

@@ -0,0 +1,69 @@
+# Protein Sequence Cropping (`huada_protein_tools` / `crop_sequence`)
+
+This endpoint is a real endpoint of the `huada_protein_tools` tool. It can only be
+called via `delta-cli science invoke`; the business response described below lives
+under the CLI top-level `data` — read fields as documented in this file, do not
+recursively search. This file only documents the endpoint schema; it does not
+authorize direct HTTP. Endpoint names are authoritative as returned by
+`delta-cli science endpoints list huada_protein_tools`; use them verbatim — never
+guess, truncate, or alias.
+
+## Overview
+
+Crop subsequences from a protein sequence by given regions and return a merged FASTA
+file.
+- Input: `protein_sequence` / `sequence_file` / `structure_file` (choose one)
+- `protein_sequence`: a single one-letter amino-acid sequence
+- `sequence_file`: FASTA/FA file URL
+- `structure_file`: PDB/CIF file URL (the sequence is extracted from the specified chain)
+- Required: `regions`, a list of crop intervals, each `[start, end]` (1-based, inclusive). For example `[[100, 200], [250, 300]]` crops two independent sequences
+- Optional: `chain`, protein chain identifier, default A
+- Output: `resultjson` contains `cropped_results` (name/start/end/length/sequence per region); `download_url` is the merged FASTA download link
+
+## Invocation
+
+```text
+delta-cli science invoke --tool huada_protein_tools --endpoint crop_sequence --data JSON
+```
+
+Required input groups (at least one per group; all groups must be satisfied):
+
+- `protein_sequence` / `sequence_file` / `structure_file` **and** `regions`
+
+Request fields:
+
+| Field | Description | Default |
+|---|---|---|
+| `protein_sequence` |  | - |
+| `sequence_file` | FASTA/FA | - |
+| `structure_file` | PDB/CIF | - |
+| `chain` | Protein chain identifier, default A | A |
+| `regions` | List of crop intervals, each [start, end] (1-based, inclusive). E.g. [[100, 200], [250, 300]] crops 100-200 and 250-300, each output as an independent sequence | - |
+
+## Response
+
+- CLI top-level envelope: a call succeeds only when the exit code is 0 AND `ok` is `true`; the service response lives under `data`.
+- Server-side contract: `status` (success/error/partial), `message`, `tool_type`, `resultjson`, `download_url`; some endpoints also return `total_count`. `resultjson` may be a single object or an array — read only the keys documented in this file, do not recursively search.
+- Binary/file artifacts (such as the PDB/XLSX/FASTA/ZIP files that `download_url` points to) are downloaded and verified with
+  `delta-cli science file download --tool huada_protein_tools --endpoint ... --output <path>`;
+  do not treat file contents as ordinary JSON results.
+
+## Output Projection
+
+> Verification status: derived from ToolSpec/agent templates; pending live calibration
+
+- Projection content: cropped_results: name/start/end/length/sequence per region + merged FASTA download_url
+- Presentation form: Sequence inline code + FASTA link
+- Downstream reuse: -
+## Output Template
+
+- Title: **Protein sequence cropping result**
+- One entry per region: range (start-end) and cropped sequence (inline code)
+- Add the merged FASTA to the "Result files & downloads" section
+
+## Boundaries & Failure Modes
+
+- File-type parameters (`structure_file`/`sequence_file`/`msa_file` etc.) take server-accessible URL/path strings, not local upload paths; a `download_url` or `pdb_url` returned by an upstream endpoint can be backfilled directly as downstream input.
+- Make only the minimal calls needed to complete the task; `--data` carries only the fields declared by this endpoint. Do not invent enum values or branches beyond the required combinations.
+- Do not pass off local tool (RDKit/pymatgen/LAMMPS/self-attached MCP) results as this endpoint's results; do not connect directly to Huada or gateway URLs.
+- On failure, report a short summary of the CLI's raw error; do not blindly retry after remote computation timeouts (the outcome may be unknown because the task may already have happened).

package/skills/delta-protein/references/dock.md

@@ -0,0 +1,82 @@
+# Molecular Docking (`huada_protein_tools` / `dock`)
+
+This endpoint is a real endpoint of the `huada_protein_tools` tool. It can only be
+called via `delta-cli science invoke`; the business response described below lives
+under the CLI top-level `data` — read fields as documented in this file, do not
+recursively search. This file only documents the endpoint schema; it does not
+authorize direct HTTP. Endpoint names are authoritative as returned by
+`delta-cli science endpoints list huada_protein_tools`; use them verbatim — never
+guess, truncate, or alias.
+
+## Overview
+
+Protein-ligand molecular docking with AutoDock Vina.
+- Input: `structure_file` (PDB/CIF) or `protein_sequence` (structure must be predicted first) / `sequence_file` (FASTA) — choose one
+- `ligand_source`: ligand SMILES string or ligand file path (.sdf/.mol2/.txt). Optional; when missing, the backend returns a friendly hint and the request is still forwarded to the backend for handling
+- Optional:
+- `cofactor_mode` (str): "keep" or "remove", default "keep"
+- `cofactors` (list[str]): cofactor/ligand residue names, e.g. ["ATP","MG"], default auto-handled
+- `box_center` (str): manually specified docking box center, format "x,y,z"
+- `box_size` (str): manually specified docking box size, a single number or "w,h,d"
+- `ph` (float): protonation pH, default 7.4
+- `exhaustiveness` (int): Vina search exhaustiveness, default 16
+- `n_poses` (int): number of output poses, default 10
+- `cpu` (int): number of CPU cores, default 8
+- Box behavior: `box_center`/`box_size` can be given alone or together — when both are given they are used directly; when only `box_size` is given, the center is auto-detected by local p2rank (size uses this value, default 20Å); when neither is given, the backend tries the bounding box of the removed cofactor residues / p2rank auto-detected pockets in turn; with p2rank auto-detection each detected pocket is docked separately (one box per pocket, max 10 pockets by score); when p2rank finds no pocket it errors and box parameters must be provided manually
+- Output: `download_url` is the multi-conformer PDB (docked_poses.pdb, merged across pockets, containing all pose MODELs) for visualization; each `resultjson` entry contains {affinity, rmsd_lb, rmsd_ub, pocket, pdb_url}; `pocket` identifies the associated pocket (p2rank's rank/name/score/center; {"rank": N} for a single box); `pdb_url` is provided only on the rank-1 entry, pointing to a single clean best-complex PDB (full receptor + ligand, ligand in chain L), suitable for PLIP interaction analysis
+
+## Invocation
+
+```text
+delta-cli science invoke --tool huada_protein_tools --endpoint dock --data JSON
+```
+
+Required input groups (at least one per group; all groups must be satisfied):
+
+- `protein_sequence` / `sequence_file` / `structure_file` / `ligand_source`
+
+Request fields:
+
+| Field | Description | Default |
+|---|---|---|
+| `protein_sequence` |  | - |
+| `sequence_file` | FASTA/FA | - |
+| `structure_file` | PDB/CIF | - |
+| `ligand_source` | Ligand SMILES string or ligand file path (.sdf/.mol2/.txt); optional, backend returns a hint when missing | - |
+| `cofactor_mode` | Cofactor handling mode, default "keep" | keep |
+| `cofactors` | Cofactor/ligand residue name list, default None | - |
+| `box_center` | Manually specified docking box center, format x,y,z | - |
+| `box_size` | Manually specified docking box size, a single number or w,h,d | - |
+| `ph` | Protonation pH, default 7.4 | 7.4 |
+| `exhaustiveness` | Vina search exhaustiveness, default 16 | 16 |
+| `n_poses` | Number of output poses, default 10 | 10 |
+| `cpu` | Number of CPU cores, default 8 | 8 |
+
+## Response
+
+- CLI top-level envelope: a call succeeds only when the exit code is 0 AND `ok` is `true`; the service response lives under `data`.
+- Server-side contract: `status` (success/error/partial), `message`, `tool_type`, `resultjson`, `download_url`; some endpoints also return `total_count`. `resultjson` may be a single object or an array — read only the keys documented in this file, do not recursively search.
+- Binary/file artifacts (such as the PDB/XLSX/FASTA/ZIP files that `download_url` points to) are downloaded and verified with
+  `delta-cli science file download --tool huada_protein_tools --endpoint ... --output <path>`;
+  do not treat file contents as ordinary JSON results.
+
+## Output Projection
+
+> Verification status: verified by a real `delta-cli` invocation
+
+- Projection content: affinity per pose (binding energy, kcal/mol), rmsd_lb/rmsd_ub, associated pocket; rank-1 carries pdb_url (clean complex); best score read from message or the minimal affinity
+- Presentation form: Pose list text (affinity & RMSD) + multi-conformer PDB download link
+- Downstream reuse: rank-1 pdb_url -> plip_analyze structure_file
+## Output Template
+
+- Title: **Molecular docking result**
+- Lead with the conclusion: best score (best affinity, kcal/mol) and the associated pocket
+- List poses sorted by score (affinity/rmsd_lb/rmsd_ub, mark the pocket when multiple pockets)
+- Add the multi-conformer PDB to the "Result files & downloads" section; give rank-1 pdb_url separately (usable as PLIP input)
+
+## Boundaries & Failure Modes
+
+- File-type parameters (`structure_file`/`sequence_file`/`msa_file` etc.) take server-accessible URL/path strings, not local upload paths; a `download_url` or `pdb_url` returned by an upstream endpoint can be backfilled directly as downstream input.
+- Make only the minimal calls needed to complete the task; `--data` carries only the fields declared by this endpoint. Do not invent enum values or branches beyond the required combinations.
+- Do not pass off local tool (RDKit/pymatgen/LAMMPS/self-attached MCP) results as this endpoint's results; do not connect directly to Huada or gateway URLs.
+- On failure, report a short summary of the CLI's raw error; do not blindly retry after remote computation timeouts (the outcome may be unknown because the task may already have happened).

package/skills/delta-protein/references/dock_score.md

@@ -0,0 +1,70 @@
+# Vina Single-pose Scoring (`huada_protein_tools` / `dock_score`)
+
+This endpoint is a real endpoint of the `huada_protein_tools` tool. It can only be
+called via `delta-cli science invoke`; the business response described below lives
+under the CLI top-level `data` — read fields as documented in this file, do not
+recursively search. This file only documents the endpoint schema; it does not
+authorize direct HTTP. Endpoint names are authoritative as returned by
+`delta-cli science endpoints list huada_protein_tools`; use them verbatim — never
+guess, truncate, or alias.
+
+## Overview
+
+Single-pose scoring (score_only) of a protein-ligand complex with AutoDock Vina.
+- Input: `structure_file` (PDB/CIF complex file URL) + `dock_ligand` (ligand residue name in the complex, e.g. BTA)
+- Optional: `chain_id` (chain ID of the ligand, default A); `box_center`/`box_size` (manual box, format x,y,z or w,h,d) — when not provided, computed automatically from the ligand bounding box
+- Optional defaults: padding=8.0, min_box_size=20.0, ph=7.4, cpu=8, seed=42
+- Output: `resultjson` contains `best_score` (total binding energy, kcal/mol) and `scores` (energy breakdown dict)
+
+## Invocation
+
+```text
+delta-cli science invoke --tool huada_protein_tools --endpoint dock_score --data JSON
+```
+
+Required input groups (at least one per group; all groups must be satisfied):
+
+- `structure_file` **and** `dock_ligand`
+
+Request fields:
+
+| Field | Description | Default |
+|---|---|---|
+| `structure_file` | PDB/CIF complex | - |
+| `dock_ligand` | Ligand residue name in the complex to be scored, e.g. BTA | - |
+| `chain_id` | Chain ID of the ligand, default A | A |
+| `box_center` | Manually specified scoring box center, format x,y,z | - |
+| `box_size` | Manually specified scoring box size, a single number or w,h,d | - |
+| `padding` | Padding around the bounding box (Å) when the box is auto-computed | 8.0 |
+| `min_box_size` | Minimum length per side (Å) when the box is auto-computed | 20.0 |
+| `ph` | Protonation pH | 7.4 |
+| `cpu` | Number of CPU cores | 8 |
+| `seed` | Random seed | 42 |
+
+## Response
+
+- CLI top-level envelope: a call succeeds only when the exit code is 0 AND `ok` is `true`; the service response lives under `data`.
+- Server-side contract: `status` (success/error/partial), `message`, `tool_type`, `resultjson`, `download_url`; some endpoints also return `total_count`. `resultjson` may be a single object or an array — read only the keys documented in this file, do not recursively search.
+- Binary/file artifacts (such as the PDB/XLSX/FASTA/ZIP files that `download_url` points to) are downloaded and verified with
+  `delta-cli science file download --tool huada_protein_tools --endpoint ... --output <path>`;
+  do not treat file contents as ordinary JSON results.
+
+## Output Projection
+
+> Verification status: verified by a real `delta-cli` invocation
+
+- Projection content: best_score (total binding energy kcal/mol), per-term energy breakdown, box_size/center, mode=score_only
+- Presentation form: Text (total binding energy + energy breakdown)
+- Downstream reuse: -
+## Output Template
+
+- Title: **Vina single-pose scoring result**
+- Lead with the conclusion: best_score (kcal/mol) and the box used (center/box_size)
+- Give the energy breakdown (gauss/hydrophobic/hbond etc., restated per returned keys)
+
+## Boundaries & Failure Modes
+
+- File-type parameters (`structure_file`/`sequence_file`/`msa_file` etc.) take server-accessible URL/path strings, not local upload paths; a `download_url` or `pdb_url` returned by an upstream endpoint can be backfilled directly as downstream input.
+- Make only the minimal calls needed to complete the task; `--data` carries only the fields declared by this endpoint. Do not invent enum values or branches beyond the required combinations.
+- Do not pass off local tool (RDKit/pymatgen/LAMMPS/self-attached MCP) results as this endpoint's results; do not connect directly to Huada or gateway URLs.
+- On failure, report a short summary of the CLI's raw error; do not blindly retry after remote computation timeouts (the outcome may be unknown because the task may already have happened).