@delta-infra/cli 1.1.18 → 1.1.19

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

@@ -0,0 +1,90 @@
+# ProTrek API Search (`huada_protein_tools` / `protrek_search`)
+
+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
+
+Open-ended protein retrieval (text/sequence/structure) across multiple databases
+with the ProTrek protein search API.
+- Typical scenarios:
+- Search related proteins by functional/reaction/family descriptions in protein
+  databases (`input_type=text`).
+- Search similar proteins by sequence (`input_type=sequence`).
+- Search similar structures by structure (`input_type=structure`).
+- Not for: exact metadata queries of a known UniProt accession / UniParc ID / gene
+  name / protein name (use `uniprot_query` for those).
+- Optional parameters: `input_type` (text/sequence/structure), `query_type`
+  (sequence/structure), `topk` (10), `db` (Swiss-Prot), `protein_sequence`,
+  `sequence_file`, `structure_file`, `chain` (A), `text`
+- `query_type` defaults to `sequence`;
+- when the user mentions "structure search / structure / 3D structure", choose `structure`;
+- `input_type` is inferred from whether a sequence/structure file is provided; when
+  neither is provided, `input_type` is `text`;
+- the `text` parameter is specifically for functional/reaction/family
+  description-style text searches;
+- Supported databases: with `query_type=sequence`, Swiss-Prot/UniRef50/Uncharacterized/OMG_prot50/PDB/GOPC/NCBI/MGnify/OMG are supported; with `query_type=structure`, only PDB
+
+## Invocation
+
+```text
+delta-cli science invoke --tool huada_protein_tools --endpoint protrek_search --data JSON
+```
+
+Required input groups (at least one per group; all groups must be satisfied):
+
+- `protein_sequence` / `sequence_file` / `structure_file` / `text`
+
+Server-side default parameters:
+
+- `input_type` = `sequence`
+- `query_type` = `sequence`
+- `topk` = `10`
+- `db` = `Swiss-Prot`
+
+Request fields:
+
+| Field | Description | Default |
+|---|---|---|
+| `input_type` | Input type: text/sequence/structure; inferred from whether a sequence/structure file is provided, text when neither | sequence |
+| `query_type` | Query type: sequence/structure; default sequence; choose structure when "structure search" is mentioned | sequence |
+| `topk` | Number of results to return, default 10 | 10 |
+| `db` | Database name or list, default Swiss-Prot; with query_type=sequence supports ['Swiss-Prot', 'UniRef50', 'Uncharacterized', 'OMG_prot50', 'PDB', 'GOPC', 'NCBI', 'MGnify', 'OMG']; with query_type=structure only PDB | Swiss-Prot |
+| `protein_sequence` |  | - |
+| `sequence_file` | FASTA/FA | - |
+| `structure_file` | PDB/CIF | - |
+| `chain` | Protein chain identifier, default A | A |
+| `text` | Core search description when input_type=text, e.g. function/reaction/family; translate to English | - |
+
+## 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: Hit protein entries, similarity and functional information
+- Presentation form: Hit list text/table
+- Downstream reuse: for known targets with metadata use uniprot_query; this endpoint is for open-ended retrieval
+## Output Template
+
+- Title: **ProTrek database search result**
+- Lead with the conclusion: number of hit protein entries; list similarity per hit (score vs query) and functional information
+- For structure/sequence search, state the retrieval mode (query_type/input_type)
+
+## 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/pubchem_search.md

@@ -0,0 +1,68 @@
+# PubChem Compound Search (`huada_protein_tools` / `pubchem_search`)
+
+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
+
+Call PubChem (NCBI) to search basic chemical molecule information.
+- Supports querying compounds by name, SMILES, InChI, InChIKey, PubChem CID.
+- `input_type` options: name (default) | smiles | inchi | inchikey | cid.
+- `query` passes the corresponding identifier per input_type: name like "aspirin",
+  SMILES like "CC(=O)OC1=CC=CC=C1C(=O)O", CID like "2244".
+- Optional: `max_results` (default 10, max 100)
+- Output: compound results `resultjson`, containing
+  cid/name/molecular_formula/molecular_weight/canonical_smiles/inchi/inchikey/
+  iupac_name/synonyms/pubchem_url
+
+## Invocation
+
+```text
+delta-cli science invoke --tool huada_protein_tools --endpoint pubchem_search --data JSON
+```
+
+Required input groups (at least one per group; all groups must be satisfied):
+
+- `query`
+
+Request fields:
+
+| Field | Description | Default |
+|---|---|---|
+| `query` | Query string: name, SMILES, InChI, InChIKey, or CID | - |
+| `input_type` | Query type: name \| smiles \| inchi \| inchikey \| cid, default name | name |
+| `max_results` | Maximum number of compounds to return, default 10, max 100 | 10 |
+
+## 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: Compound entries: name, synonyms, molecular_formula, molecular_weight, canonical_smiles, inchi, inchikey, cid, pubchem_url
+- Presentation form: Text (formula/weight/name/SMILES) + entry URL
+- Downstream reuse: canonical_smiles -> smiles / primary_smiles for catpred_predict / catapro_predict
+## Output Template
+
+- Title: **PubChem compound search**
+- Lead with the conclusion: compound name, molecular formula, molecular weight
+- Also give: canonical_smiles / InChIKey, cid, `[PubChem entry](pubchem_url)` (URL in a safe form)
+- Avoid listing every JSON key
+
+## 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/pubmed_search.md

@@ -0,0 +1,79 @@
+# PubMed Literature Search (`huada_protein_tools` / `pubmed_search`)
+
+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
+
+Call PubMed (NCBI) to search academic literature, supporting cascaded retrieval of
+PMC/Europe PMC/OA PDF full texts. Various tasks may attempt to obtain relevant
+information through literature search.
+- `query` must be an English PubMed boolean search expression. If the user inputs
+  Chinese, first translate the core concepts into English academic terms, then
+  assemble them into a boolean expression. Recommended format:
+  ("concept A" OR "synonym A2") AND ("concept B" OR "synonym B2") AND ... Split
+  into 2-4 core concept groups, each with 2-4 English synonyms/related terms/MeSH
+  terms; phrases wrapped in double quotes.
+- Correct example: ("human enterokinase" OR "human enteropeptidase" OR
+  "enterokinase catalytic subunit") AND (solubility OR "soluble expression") AND
+  (mutation OR mutagenesis); when the user asks about "溶菌酶 活性位点" (lysozyme
+  active site), the query should be ("lysozyme" OR "muramidase") AND ("active site"
+  OR "catalytic site") AND (mutation OR mutagenesis).
+- Forbidden: UniProt IDs, full English questions, meaningless words (analysis of /
+  study of / improvement / optimization / design of / engineering of).
+- Optional: `max_results` (default 10, max 10), `min_year` (default 2000),
+  `max_year` (default 2026)
+- Output: literature results `resultjson`
+
+## Invocation
+
+```text
+delta-cli science invoke --tool huada_protein_tools --endpoint pubmed_search --data JSON
+```
+
+Required input groups (at least one per group; all groups must be satisfied):
+
+- `query`
+
+Request fields:
+
+| Field | Description | Default |
+|---|---|---|
+| `query` | PubMed English boolean search expression; when the user inputs Chinese, provide the translated & expanded English boolean expression here, never pass Chinese | - |
+| `max_results` | Maximum number of papers to return, default 10, max 10 | 10 |
+| `min_year` | Start year, default 2000 | 2000 |
+| `max_year` | End year, default 2026 | 2026 |
+
+## 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: extracted_papers and summary; table grouped by PMID (protein name, mutation (original notation), key finding, source reference)
+- Presentation form: Markdown table; keep original mutation notation (e.g. Y126A/Y206F); site-level comparison only when zero-shot mutant results exist and the literature contains those mutations
+- Downstream reuse: literature evidence can be cross-checked with zero_shot_mutant_candidates positions (note the PMID, distinguish reported hotspots/new targets)
+## Output Template
+
+- Title: **PubMed literature search result**
+- Lead with a review summary: 4-6 bullet points depending on focus (mutation/engineering vs application/mechanism)
+- Table grouped by PMID with the source reference in the last column (`PMID: XXXXXXXX`, fall back to the title when missing); keep original mutation notation
+- Papers with empty mutations do not show mutation-related columns; site-level comparison only when zero-shot mutant results exist and the literature contains those mutations
+
+## 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/reap_design_primer.md

@@ -0,0 +1,69 @@
+# Single-site Mutation Primer Design (`huada_protein_tools` / `reap_design_primer`)
+
+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
+
+REAP Step 7: design overlapping PCR site-directed mutagenesis primers for single-site
+mutations.
+- Required: `mutant_list_file` (Excel/CSV with a mutant column)
+- Required: `plasmid_fasta` (user-uploaded DNA FASTA template)
+- Required: `cds_start` (0-based CDS start in `plasmid_fasta`; needs to be extracted from the user's question)
+- Optional: `mutation_format` (protein default A123C / dna → G367A), `codon_pref_file`, `sheet`
+- Output: primer Excel `download_url`, ZIP `zip_download_url`, `resultjson` (primer preview and Tm)
+
+## Invocation
+
+```text
+delta-cli science invoke --tool huada_protein_tools --endpoint reap_design_primer --data JSON
+```
+
+Required input groups (at least one per group; all groups must be satisfied):
+
+- `mutant_list_file` **and** `template_file` / `plasmid_fasta`
+
+Request fields:
+
+| Field | Description | Default |
+|---|---|---|
+| `mutant_list_file` | Excel/CSV/TXT mutation list | - |
+| `template_file` | Segmented template TXT (upstream/gene/downstream) | - |
+| `plasmid_fasta` | Plasmid/template DNA FASTA | - |
+| `cds_start` | 0-based CDS start position in plasmid_fasta mode | - |
+| `mutation_format` | Mutation format: protein or dna, default protein | protein |
+| `codon_pref_file` | AA:CODON codon preference file | - |
+| `sheet` | Excel sheet index or name, default 0 | 0 |
+
+## 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: Primer design table (mutation id, forward/reverse primer sequences, Tm) + Excel download_url + ZIP zip_download_url
+- Presentation form: Markdown table + Excel/ZIP download links
+- Downstream reuse: -
+## Output Template
+
+- Title: **Single-site mutation primer design result (REAP Step 7)**
+- Markdown table: `| Mutation ID | Forward primer | Reverse primer | Tm |`
+- Add the Excel and ZIP 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/rfd3_design.md

@@ -0,0 +1,65 @@
+# Protein Scaffold Design (RFdiffusion3) (`huada_protein_tools` / `rfd3_design`)
+
+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 scaffold design with RFdiffusion3 (without MPNN sequence design).
+- Required: `structure_file` (cropped PDB/CIF structure URL or path, e.g. the `download_url` returned by pocket_prediction)
+- Optional: `chain_id` (design only this chain, default "A"; specifying a single chain on a multi-chain structure such as a tetramer avoids cross-chain cost-matrix conflicts), `length` (design length range, e.g. "100-200", default "100-200"), `rfd3_n` (RFdiffusion3 sample count, default 1)
+- The backend auto-infers `unindex` / `select_fixed_atoms` / `ori_token`
+- Output: generated PDB structure files and sequence FASTA files packaged as a ZIP `download_url`; `resultjson` contains `{structures: [...], structure_links: [...]}`, where each `structures` entry carries chain/length/sequence/sample_score/quality_metrics, and `quality_metrics` includes insertion RMSD, clashes, chain breaks, secondary structure, etc.; `structure_links` are the best ≤5 scaffold PDB links sorted by `sample_score` (highest score first)
+- Use case: scaffold design only, without MPNN sequence design
+
+## Invocation
+
+```text
+delta-cli science invoke --tool huada_protein_tools --endpoint rfd3_design --data JSON
+```
+
+Required input groups (at least one per group; all groups must be satisfied):
+
+- `structure_file`
+
+Request fields:
+
+| Field | Description | Default |
+|---|---|---|
+| `structure_file` | Cropped PDB/CIF | - |
+| `chain_id` | Design only this protein chain, default "A" | A |
+| `length` | Design length range, e.g. "100-200" | 100-200 |
+| `rfd3_n` | RFdiffusion3 sample count, default 1 | 1 |
+
+## 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: structure_links (best ≤5 scaffold PDBs sorted by sample_score) with structures overview (chain/length/sequence/sample_score/quality metrics)
+- Presentation form: Scaffold PDB link list; quality metrics include insertion RMSD, clashes, chain breaks, secondary structure
+- Downstream reuse: scaffolds can feed mpnn_design_sequence / protein_design for sequence design
+## Output Template
+
+- Title: **RFdiffusion3 protein scaffold design result**
+- Lead with the conclusion: number of scaffolds generated (best ≤5), sample_score range
+- Add scaffold PDB links to the "Result files & downloads" section; summarize quality metrics in text (insertion RMSD/clashes/chain breaks/secondary structure)
+
+## 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/structure_to_sequence.md

@@ -0,0 +1,61 @@
+# PDB Sequence Extraction (`huada_protein_tools` / `structure_to_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
+
+Extract the protein sequence from a PDB/CIF structure file.
+- Required: `structure_file`
+- Optional: `chain` (A)
+- Output: extracted protein sequence `resultjson`
+
+## Invocation
+
+```text
+delta-cli science invoke --tool huada_protein_tools --endpoint structure_to_sequence --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 |
+
+## 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: Protein sequence extracted from PDB/CIF
+- Presentation form: Sequence shown as inline code
+- Downstream reuse: sequence can be used as protein_sequence for downstream mutation/design/annotation endpoints (e.g. consensus_mutation, interpro_analyze)
+## Output Template
+
+- Title: **Structure-to-sequence extraction result**
+- Lead with the conclusion: extracted protein sequence for chain=<chain> (length N aa)
+- Show the sequence as inline code; no download needed
+
+## 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/summarize_result.md

@@ -0,0 +1,68 @@
+# Multi-model Result Summary (`huada_protein_tools` / `summarize_result`)
+
+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
+
+Summarize multi-model zero-shot prediction results as the final step of the
+mutation-prediction flow.
+- Required: `result_files` (list of paths to multiple prediction result files)
+- Optional: `protein_sequence`, `topk` (10)
+- Output: summarized ranking `download_url`
+
+## Invocation
+
+```text
+delta-cli science invoke --tool huada_protein_tools --endpoint summarize_result --data JSON
+```
+
+Required input groups (at least one per group; all groups must be satisfied):
+
+- `result_files`
+
+Server-side default parameters:
+
+- `topk` = `10`
+
+Request fields:
+
+| Field | Description | Default |
+|---|---|---|
+| `result_files` | URL list of result files from previous steps | [] |
+| `protein_sequence` |  | - |
+| `topk` | Return the top k results, default 10 | 10 |
+
+## 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: Multi-model summarized ranking (topk) with all rows retained; restated as a table with the tool's original fields, prompting download of the full file when too long
+- Presentation form: Full Markdown table (≤100 rows); better for filtering/sorting
+- Downstream reuse: final step of the mutation-prediction chain (terminal)
+## Output Template
+
+- Title: **Multi-model result summary**
+- Show the full summary table (≤100 rows, no truncation), column names restated in natural language
+- Lead with the conclusion: positions where models agree/disagree; base final recommendations on the summary rather than restating single-model raw tables
+- When more than 100 rows, prompt downloading the full file
+
+## 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/surface_charge.md

@@ -0,0 +1,84 @@
+# Surface Residue Charge Analysis (`huada_protein_tools` / `surface_charge`)
+
+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 surface residue charges with ProCaliper + APBS.
+- Required: `structure_file` (.pdb/.cif/.ent)
+- Optional: `pH` (default 7.4), `forcefield` (default PARSE), `chain_ids` (e.g. 'A,B'),
+  `sasa_threshold` (default 20.0 Ų), `potential_threshold` (default 1.0 kT/e), `precision` (standard/high)
+- ProCaliper computes SASA + PROPKA pKa to determine surface/buried status and charge type; pH affects PDB2PQR protonation (APBS) and charge-type determination
+- APBS solves the electrostatic potential .dx grid → maps it back to surface residues, identifying charge patches
+- Use case: analyze protein surface electrostatic properties, identify charge patches, assist binding-interface analysis
+
+This endpoint's `resultjson` is a flat structure (tested, not an analysis/visualization wrapper):
+
+- `negative_surface` / `positive_surface` / `net_surface_charge`: negative/positive/net charge residue counts
+- `patch_count` / `patches[]`: charge patches (non-empty only when APBS is available)
+- `residues[]`: per residue `chain` / `res3` / `seq` / `sasa` / `pka` / `charge_type` /
+  `is_surface` / `protonation_state` / `potential` / `potential_type` / `in_patch` / `patch_id`
+- `sasa_threshold` / `surface_residues`: surface-determination threshold and surface residue count
+- `pdb2pqr{pka_df[]}`: PROPKA pKa details; `procaliper{sasa, titration}`: SASA and titration state
+- `apbs{status, message}`: electrostatic-potential solving status. When APBS is unavailable the overall
+  `status` is `partial`, `message` notes the reason (e.g. `APBS executable 'apbs' not found. Set APBS_BIN.`),
+  `potential` is null and `patch_count=0`; in that case report only the ProCaliper charge results and do
+  not misreport it as a call failure
+- `download_url`: the electrostatic potential `.dx` grid download link when APBS is available
+
+## Invocation
+
+```text
+delta-cli science invoke --tool huada_protein_tools --endpoint surface_charge --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 | - |
+| `pH` | pH value; affects APBS protonation and residue charge-type determination | 7.4 |
+| `forcefield` | PDB2PQR forcefield | PARSE |
+| `chain_ids` | Select chains in multi-chain structures, e.g. A,B; default all chains | - |
+| `sasa_threshold` | Surface residue SASA threshold (Ų) | 20.0 |
+| `potential_threshold` | Potential polarity threshold (kT/e) | 1.0 |
+| `precision` | Grid precision: standard / high | standard |
+
+## 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: Charge summary: negative_surface / positive_surface / net_surface_charge / surface_residues / patch_count / patches; residues[] details (sasa/pka/charge_type/is_surface)
+- Presentation form: Text/table; when APBS is unavailable status=partial — report only ProCaliper results and explain why; download_url is the .dx grid (when APBS available)
+- Downstream reuse: -
+## Output Template
+
+- Title: **Surface residue charge analysis result (ProCaliper + APBS)**
+- Lead with the conclusion: net charge (positive/negative/net_surface_charge), surface residue count, charge patch count
+- List key surface positive/negative-charge residues (with pKa/sasa)
+- When APBS is unavailable (status=partial) state plainly that electrostatics were not solved and report only ProCaliper results; add the .dx grid (if any) 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).