Update to Helical

{
  "description": "Compute cell embeddings for a single-cell dataset with a Helical foundation model, then download the outputs. Use when the user wants embeddings, representations, or features from a dataset already in the platform catalogue. For training a model on labelled data, use fine-tune-model instead.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 400
    }
  ],
  "name": "compute-embeddings",
  "skill_md_contents": "---\nname: compute-embeddings\ndescription: >-\n  Compute cell embeddings for a single-cell dataset with a Helical foundation model, then\n  download the outputs. Use when the user wants embeddings, representations, or features\n  from a dataset already in the platform catalogue. For training a model on labelled data,\n  use fine-tune-model instead.\n---\n\n# Compute embeddings\n\nTurns a catalogue dataset plus a foundation model into an embedding matrix.\n\n**The one thing to understand before starting:** `triggerEmbedding` does not start\nanything. It queues the run and returns a `confirmation_id` and the platform's price. The\nrun starts only when `resolveConfirmation` approves it, and **that call is the user's\napproval**. State the dataset, the model and the price, and get an explicit yes before\nmaking it.\n\nEvery run that spends credit needs that explicit approval. So do not ask the user to approve\nthe dataset or model before queuing. Choose them, queue the run, then ask once, showing the\nchoices and the price together. Queuing is free. To change a choice, reject and queue again.\n\nYou also cannot choose a project: scope comes from the signed-in user, and no tool accepts\na project or conversation identifier.\n\n## 1. Select the dataset\n\n`listDatasets` finds the dataset; its description covers the filters. `organism` matches\nthe full name exactly, so `\"Homo sapiens\"` matches but `\"human\"` does not.\n\n`getDataset({ id })` for the full record, including `cellCount` and `geneCount`. Report\nthem: run time and price scale with the cell count.\n\nA user's own `.h5ad` can be added with `initiateDatasetUpload` → `completeDatasetUpload`\n→ `registerDataset`; follow those tools' descriptions for splitting the file. Once\nregistered, it is embedded like any catalogue dataset.\n\n## 2. Choose a model\n\n`listModels()`. It returns two lists:\n\n- `base_models`: foundation models. Pass the `name` as `model` and omit `model_version`.\n- `models`: the user's own fine-tuned models, promoted or not. Pass the `name` as `model`\n  and the `version`, as a number, as `model_version`. Never pass `base_model`.\n\nAny of them can run here; promotion is only a label. Only single-cell models are listed,\nand only those can run here. Every entry carries its rates, `credits_per_job` and\n`credits_per_cell`; a fine-tuned model is priced at its `base_model`'s rates. Pick one whose\n`credits_per_cell` is not `null`; an unpriced model cannot run here.\n\n## 3. Queue it, show the price, then approve\n\n```\ntriggerEmbedding({ datasetId, model, model_version? })\n```\n\nSend only these fields (and `pretrained_embedding_species`, if the user asks for it). The\ntool refuses any other field with a 400.\n\nThe reply carries the platform's quote: the cells it counts and the most it\nwill cost. Relay that figure; do not recompute it. Get an explicit yes, then call\n`resolveConfirmation({ id: confirmation_id, decision: \"approve\" })`. If the user declines,\nresolve it with `\"reject\"`.\n\nDo not put several runs behind one approval, and do not treat an earlier \"sounds good\"\nabout the plan as approval for the run itself. Each model is its own run with its own\nquote.\n\nTo change anything, reject the queued confirmation, then queue again. A 409 means the same\nrun is already queued. `listPendingConfirmations()` finds it, but its entry carries no\nprice, so if you do not still have that quote from this conversation, reject it and queue\nagain. For a 402 or an unusable quote, see `check-credits`.\n\n## 4. Follow it through\n\nOn approval, `outcome.dag_run_id` names the run. Poll `getRunDetails({ runId })` until\n`state` is `succeeded`, `failed` or `cancelled`. Runs take minutes to hours; poll at a\nsensible interval and keep the user informed rather than going silent. On failure,\n`getDagErrors({ runId })` says what went wrong. A failed or cancelled run is refunded in\nfull. `listDagRuns({ dagIds: \"embedding\" })` lists recent embedding runs if you lose track\nof one.\n\n## 5. Download the outputs\n\n`getRunDetails({ runId })` returns `artifacts[]`, each with an `artifact_id`,\n`artifact_type`, `display_name` and `s3_key`. The embedding matrix has `artifact_type`\n`\"embedding\"`.\n\n`downloadArtifact({ artifactId })` returns a presigned URL. Fetch it with\n`curl -o '<fileName>' '<url>'`; it needs no auth header and expires within an hour. It\nserves one file of any size, binary included, but not a directory.\n\nIf the matrix carries cell ids, join on them. If it is a bare matrix, check its row count\nequals the dataset's `cellCount` before assuming its rows follow the dataset's order, and\nsay you assumed it.\n\n## Hand-off\n\n- Want the model trained on labels first? → `fine-tune-model`. Its result can be embedded\n  here as soon as the run succeeds.\n- Want to knock out, knock down or overexpress genes? → `in-silico-perturbation`: edit the\n  counts locally, upload, and embed the perturbed file here.\n- Cost and balance → `check-credits`.\n- Judging whether an embedding is good (separation of the conditions of interest against a\n  zero-shot baseline) is interpretation, not something these tools report.\n\n## Conventions\n\n`datasetId`, never a path · scope is derived from the signed-in user, you cannot pass a\nproject · send only the schema's fields · queue → relay the quote → explicit yes →\n`resolveConfirmation` · one model, one run, one approval · poll the run · download with\n`downloadArtifact` · never print credentials or raw upstream errors.\n"
}