@delta-infra/cli 1.1.18 → 1.1.21

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

@@ -0,0 +1,63 @@
+# UniProt Batch Query (`huada_protein_tools` / `uniprot_batch_query`)
+
+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
+
+Batch query UniProt. Supports UniProtKB accessions, UniParc IDs, or keyword
+searches. Does not support direct text retrieval.
+- Input: List[str]
+- Output:
+- source: uniprotkb | uniparc
+- resultjson: {query_str: {uniprotkb/uniparc: ..., structure_links: [...], ...}, ...}
+- Use case: query metadata for multiple proteins at once
+
+## Invocation
+
+```text
+delta-cli science invoke --tool huada_protein_tools --endpoint uniprot_batch_query --data JSON
+```
+
+Required input groups (at least one per group; all groups must be satisfied):
+
+- `query`
+
+Request fields:
+
+| Field | Description | Default |
+|---|---|---|
+| `query` | UniProt accession / UniParc ID list | - |
+
+## 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: Metadata per query id (uniprotkb/uniparc, name, species, sequence length, structure_links)
+- Presentation form: Entry list/table for easy selection
+- Downstream reuse: sequence of the selected entry can be used as downstream input
+## Output Template
+
+- Title: **UniProt candidate match result**
+- One row per candidate entry: Entry/protein name/species/sequence identity/sequence length (table or list)
+- Prompt the user to confirm the selection
+
+## 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/uniprot_query.md

@@ -0,0 +1,64 @@
+# UniProt Protein Query (`huada_protein_tools` / `uniprot_query`)
+
+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
+
+Query UniProt for metadata of known proteins.
+- Input: a single string — a UniProtKB accession, UniParc ID, gene name, or protein name.
+- Not for: open-ended functional/reaction description style database retrieval. Use `protrek_search` for such retrieval.
+- Output:
+- source: uniprotkb | uniparc
+- resultjson: {uniprotkb/uniparc: ..., structure_links: [...], sequence, sequence_length, protein_name, organism}
+- Use case: metadata queries for known protein entries — sequence, name, organism, structure links, etc.
+
+## Invocation
+
+```text
+delta-cli science invoke --tool huada_protein_tools --endpoint uniprot_query --data JSON
+```
+
+Required input groups (at least one per group; all groups must be satisfied):
+
+- `query`
+
+Request fields:
+
+| Field | Description | Default |
+|---|---|---|
+| `query` | UniProt accession / UniParc ID / gene name / protein name; for known-protein metadata queries, not open-ended functional/reaction retrieval | - |
+
+## 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_name, organism, sequence_length, sequence, structure_links, function-related fields
+- Presentation form: Metadata summary (name/species/length) + sequence inline code + structure links
+- Downstream reuse: sequence -> protein_sequence for interpro_analyze / consensus_mutation
+## Output Template
+
+- Title: **UniProt query result**
+- Lead with the conclusion: protein name, species, sequence length, function annotation and key regions (summarized, not raw JSON key names)
+- Show the full sequence as inline code; structure_links as `[name](full URL)`
+- Note the sequence can serve as downstream protein_sequence 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/zero_shot_mutant_candidates.md

@@ -0,0 +1,76 @@
+# Zero-shot Mutant Candidate Prediction (`huada_protein_tools` / `zero_shot_mutant_candidates`)
+
+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
+
+Zero-shot mutant candidate prediction: evaluate the benefit of single-site mutations
+with pretrained models when no experimental data is available.
+- Input: `protein_sequence` / `sequence_file` / `structure_file` (choose one)
+- Optional: `chain` (A), `msa_file`, `model_name` (default ["esmc"]; options: esmc/esm2/saprot/thermompnn/protein_mpnn/soluble_mpnn)
+- Output: mutation score results `download_url`, `resultjson`
+- Use case: predicting beneficial mutations, optimizing protein stability
+- Models that depend on a structure file: thermompnn/saprot/protein_mpnn/soluble_mpnn
+- Model selection advice: thermostability → thermompnn; solubility → soluble_mpnn; activity → esmc/esm2/saprot.
+- Input hints: "thermostability/stability" → `model_name` = `["thermompnn"]`; "solubility/soluble" → `["soluble_mpnn"]`; "activity" → `["esm2","esmc","saprot"]`.
+
+## Invocation
+
+```text
+delta-cli science invoke --tool huada_protein_tools --endpoint zero_shot_mutant_candidates --data JSON
+```
+
+Required input groups (at least one per group; all groups must be satisfied):
+
+- `protein_sequence` / `sequence_file` / `structure_file`
+
+Server-side default parameters:
+
+- `model_name` = `["esmc"]`
+
+Request fields:
+
+| Field | Description | Default |
+|---|---|---|
+| `protein_sequence` |  | - |
+| `sequence_file` | FASTA/FA | - |
+| `structure_file` | PDB/CIF | - |
+| `chain` | Protein chain identifier, default A | A |
+| `msa_file` | A3M MSA | - |
+| `model_name` | Model name list, default ["esmc"] | ["esmc"] |
+
+## 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: Mutant candidate summary: mutation (keep the tool's original notation), source model, score/confidence, recommendation/rationale; positions overlapping the active site are marked as not recommended
+- Presentation form: Markdown table; score column names restated in natural language, not raw JSON key names
+- Downstream reuse: result_files list -> summarize_result; ConSurf conservation / EasIFA active site / PubMed literature are annotations only, not recommendation criteria
+## Output Template
+
+- Title: **Zero-shot mutant candidate prediction result**
+- Markdown table: `| Mutation | Source model | Score/confidence | Recommendation/rationale |`, keeping the tool's original mutation/model notation; column names adjustable per resultjson
+- Positions overlapping the active site -> mark as "Overlaps active site, not recommended"; conservation is only a note in the rationale column
+- If PubMed reports the mutation: note the PMID and distinguish "reported hotspot" / "new target not yet reported"
+- Never invent evidence not present in the data; do not use raw JSON key names as body text
+
+## 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/scripts/gen_references.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+delta-protein reference generator / checker.
+
+Self-contained (stdlib only). Reads scripts/output_metadata.json and, for every
+endpoint, idempotently inserts/updates the `## Output Projection` and
+`## Output Template` sections in references/<endpoint>.md. Run it again after
+metadata changes to regenerate cleanly.
+
+Usage:
+  python scripts/gen_references.py                  # regenerate Output Projection/Template sections
+  python scripts/gen_references.py --check          # validate all references + SKILL links
+  python scripts/gen_references.py --sync <dir>     # copy references + SKILL.md to an install dir
+"""
+import json
+import os
+import re
+import sys
+
+BASE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))  # skills/delta-protein
+REFS = os.path.join(BASE, "references")
+SKILL = os.path.join(BASE, "SKILL.md")
+META = os.path.join(BASE, "scripts", "output_metadata.json")
+
+EXPECTED_SECTIONS = ["## Overview", "## Invocation", "## Response", "## Output Projection", "## Output Template", "## Boundaries & Failure Modes"]
+
+DEFAULT_TEMPLATE = (
+    "- Title: `**{tool_display_name} analysis result**`\n"
+    "- Lead with the conclusion: summarize key results from resultjson and what they mean for the user's question; present data in natural language or friendly table column names, not raw JSON key names.\n"
+    "- Downloads: when a `download_url` is present, give `[name](full URL)` in the \"Result files & downloads\" section."
+)
+
+
+def load_meta():
+    with open(META, encoding="utf-8") as f:
+        return json.load(f)
+
+
+def build_projection(meta):
+    prov = "verified by a real `delta-cli` invocation" if meta["provenance"] == "tested" else "derived from ToolSpec/agent templates; pending live calibration"
+    return "\n".join([
+        "## Output Projection",
+        "",
+        f"> Verification status: {prov}",
+        "",
+        f"- Projection content: {meta['project']}",
+        f"- Presentation form: {meta['form']}",
+        f"- Downstream reuse: {meta['downstream']}",
+        "",
+    ])
+
+
+def build_template(meta):
+    tpl = meta.get("output_template")
+    if not tpl:
+        tpl = DEFAULT_TEMPLATE.replace("{tool_display_name}", meta.get("display_name", "Endpoint"))
+    tpl = tpl.strip()
+    return "## Output Template\n\n" + tpl + "\n\n"
+
+
+def upsert_projection(lines, block):
+    idx = next((i for i, l in enumerate(lines) if l.strip() == "## Output Projection"), None)
+    if idx is None:
+        idx = next((i for i, l in enumerate(lines) if l.strip() == "## Output Template"), None)
+    if idx is not None:
+        # Walk from the generated-block heading and cut at the first heading that
+        # does NOT belong to the generated block (## Output Projection /
+        # ## Output Template). This keeps regeneration idempotent: the whole
+        # generated region is replaced instead of leaving a stale duplicate.
+        end = next(
+            (i for i in range(idx + 1, len(lines))
+             if lines[i].startswith("## ") and lines[i].strip() not in ("## Output Projection", "## Output Template")),
+            len(lines),
+        )
+        return lines[:idx] + block.splitlines(True) + lines[end:]
+    insert_at = next((i for i, l in enumerate(lines) if l.startswith("## Boundaries & Failure Modes")), len(lines))
+    return lines[:insert_at] + block.splitlines(True) + lines[insert_at:]
+
+
+def regen():
+    meta = load_meta()
+    n = 0
+    for ep, m in sorted(meta.items()):
+        path = os.path.join(REFS, ep + ".md")
+        if not os.path.exists(path):
+            print(f"MISSING reference: {ep}.md", file=sys.stderr)
+            continue
+        with open(path, encoding="utf-8") as f:
+            text = f.read()
+        lines = upsert_projection(text.splitlines(True), build_projection(m) + build_template(m))
+        if "".join(lines) != text:
+            with open(path, "w", encoding="utf-8", newline="\n") as f:
+                f.write("".join(lines))
+            n += 1
+    print(f"regenerated {n} of {len(meta)} references")
+
+
+def check():
+    meta = load_meta()
+    errors = []
+
+    for ep, m in sorted(meta.items()):
+        path = os.path.join(REFS, ep + ".md")
+        if not os.path.exists(path):
+            errors.append(f"missing reference {ep}.md")
+            continue
+        text = open(path, encoding="utf-8").read()
+        lines = [l.strip() for l in text.splitlines()]
+        for sec in EXPECTED_SECTIONS:
+            if sec not in lines:
+                errors.append(f"{ep}.md missing section {sec}")
+        for sec in ("## Output Projection", "## Output Template"):
+            if lines.count(sec) != 1:
+                errors.append(f"{ep}.md section {sec} appears {lines.count(sec)} times (expected exactly once)")
+        first = lines[0] if lines else ""
+        if ep not in first:
+            errors.append(f"{ep}.md title does not contain endpoint {ep}")
+        if "Verification status:" not in text:
+            errors.append(f"{ep}.md missing verification-status marker")
+        prov = "verified by a real `delta-cli` invocation" if m["provenance"] == "tested" else "derived from ToolSpec/agent templates; pending live calibration"
+        if prov not in text:
+            errors.append(f"{ep}.md provenance marker mismatch ({prov})")
+
+    extras = [f for f in os.listdir(REFS) if f.endswith(".md") and f[:-3] not in meta]
+    for e in extras:
+        errors.append(f"reference not in metadata: {e}")
+
+    if os.path.exists(SKILL):
+        skill = open(SKILL, encoding="utf-8").read()
+        for mref in re.findall(r"references/([a-z0-9_]+\.md)", skill):
+            if not os.path.exists(os.path.join(REFS, os.path.basename(mref))):
+                errors.append(f"SKILL.md broken link: {mref}")
+
+    if errors:
+        print("CHECK FAILED:")
+        for e in errors:
+            print("  - " + e)
+        return 1
+    print(f"CHECK OK: {len(meta)} references, sections + provenance + links valid")
+    return 0
+
+
+def sync(target):
+    for ep in load_meta():
+        src = os.path.join(REFS, ep + ".md")
+        if os.path.exists(src):
+            shutil_copy(src, os.path.join(target, "references", ep + ".md"))
+    if os.path.exists(SKILL):
+        shutil_copy(SKILL, os.path.join(target, "SKILL.md"))
+    print(f"synced references + SKILL.md -> {target}")
+
+
+def shutil_copy(src, dst):
+    import shutil
+    os.makedirs(os.path.dirname(dst), exist_ok=True)
+    shutil.copyfile(src, dst)
+
+
+if __name__ == "__main__":
+    args = sys.argv[1:]
+    if "--check" in args:
+        sys.exit(check())
+    if "--sync" in args:
+        sync(args[args.index("--sync") + 1])
+        sys.exit(0)
+    regen()