From d31b645074712b592d9b605527678a38dad8722f Mon Sep 17 00:00:00 2001 From: "Dmitry Ivanov @ helical-ai.com" Date: Tue, 27 Oct 2026 15:48:28 +0100 Subject: [PATCH] docs(skills): ask once for a paid run, after the quote (#56) Every run that spends credit already stops for the user's explicit yes at resolveConfirmation. So the skills no longer ask the user to approve the configuration before queuing. The agent makes its choices, queues the run, and asks once with the choices and the price together. The perturbation skill drops its yes on the local estimate. It stops early only when the estimate exceeds the balance. Bump to 1.0.5. Co-authored-by: Claude Opus 5.5 --- .../.claude-plugin/plugin.json | 2 +- plugins/helical-platform/plugin.json | 2 +- .../skills/compute-embeddings/SKILL.md | 4 +++ .../skills/fine-tune-model/SKILL.md | 35 ++++++++++++------- .../skills/in-silico-perturbation/SKILL.md | 16 +++++---- 5 files changed, 39 insertions(+), 20 deletions(-) diff --git a/plugins/helical-platform/.claude-plugin/plugin.json b/plugins/helical-platform/.claude-plugin/plugin.json index 55a1a71..f9b79ba 100644 --- a/plugins/helical-platform/.claude-plugin/plugin.json +++ b/plugins/helical-platform/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "helical-platform", "displayName": "Helical", - "version": "1.0.4", + "version": "1.0.5", "description": "Compute embeddings with Helical foundation models, hosted on Helical's GPUs or locally on your own GPU with the open-source package.", "author": { "name": "Helical", diff --git a/plugins/helical-platform/plugin.json b/plugins/helical-platform/plugin.json index 52ef1f6..430d212 100644 --- a/plugins/helical-platform/plugin.json +++ b/plugins/helical-platform/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "helical-platform", - "version": "1.0.4", + "version": "1.0.5", "description": "Compute embeddings with Helical foundation models, hosted on Helical's GPUs or locally on your own GPU with the open-source package.", "author": { "name": "Helical", diff --git a/plugins/helical-platform/skills/compute-embeddings/SKILL.md b/plugins/helical-platform/skills/compute-embeddings/SKILL.md index 9ed2e2e..467e232 100644 --- a/plugins/helical-platform/skills/compute-embeddings/SKILL.md +++ b/plugins/helical-platform/skills/compute-embeddings/SKILL.md @@ -17,6 +17,10 @@ run starts only when `resolveConfirmation` approves it, and **that call is the u approval**. State the dataset, the model and the price, and get an explicit yes before making it. +Every run that spends credit needs that explicit approval. So do not ask the user to approve +the dataset or model before queuing. Choose them, queue the run, then ask once, showing the +choices and the price together. Queuing is free. To change a choice, reject and queue again. + You also cannot choose a project: scope comes from the signed-in user, and no tool accepts a project or conversation identifier. diff --git a/plugins/helical-platform/skills/fine-tune-model/SKILL.md b/plugins/helical-platform/skills/fine-tune-model/SKILL.md index 49d926d..ad1ee18 100644 --- a/plugins/helical-platform/skills/fine-tune-model/SKILL.md +++ b/plugins/helical-platform/skills/fine-tune-model/SKILL.md @@ -18,7 +18,13 @@ model list. most expensive run on this surface, so the preparation below matters more than it does for embeddings. -## 1. Select the dataset and confirm the label column +**Every run that spends credit needs the user's explicit approval.** That approval comes at +`resolveConfirmation`, after the platform's quote. So do not ask the user to approve the +configuration before queuing. Make the choices below, queue the run, then ask once, showing +the choices and the price together. Queuing is free. To change a choice, reject the queued +run and queue again. + +## 1. Select the dataset and choose the label column `listDatasets(...)` → `getDataset({ id })`. The record names likely label columns: `celltypeColumn`, `celltypeColumnLv2`, `diseaseColumn`, `donorColumn`. Note `cellCount` @@ -29,10 +35,12 @@ a column the record does not name, ask them for its exact name, or read it from copy of the file (the record's `linkData`, when it has one; an uploaded dataset usually does not). -**Confirm the label column with the user before queuing.** Training on a plausible-looking -but wrong column wastes the whole run, and nothing downstream will catch it. Where you can -see the classes, check they look like what the user expects. A column with one dominant -class or hundreds of singletons will not train usefully. +**Choose the label column, and name it in the approval request.** Training on a +plausible-looking but wrong column wastes the whole run, and nothing downstream will catch +it. Where you can see the classes, check they look like what the user expects. A column +with one dominant class or hundreds of singletons will not train usefully. Ask before +queuing only when you cannot choose: several columns fit the request, none does, or the +classes look unusable. **Validation needs its own dataset.** This surface does not split the training data. To validate, the user registers a separate held-out dataset and you pass it as `valDatasetId`. @@ -91,8 +99,8 @@ one configuration). Reasonable starting values when the user has no preference: `learning_rate` 1e-4, `batch_size` 16, `epochs` 1, `logging_steps` 10, `lr_scheduler` `"constant"`, `min_lr` -1e-6, `seed` 42, `num_trainable_layers` 2. State the values you chose. They are your -decisions, not platform defaults, and the user may want different ones. +1e-6, `seed` 42, `num_trainable_layers` 2. Queue with them; do not stop to ask first. They +are your decisions, not platform defaults, so list them in the approval request. Start with a single epoch. It is cheaper to run again than to find out after a long run that the configuration was wrong. @@ -107,9 +115,11 @@ will cost. Relay that figure; do not recompute it. It is usually many times an e of the same dataset, because each epoch makes several passes over the training cells, and validation adds a pass over the validation cells each epoch. -**Get the user's explicit yes**, restating the dataset, the label column, the base model, -the epoch count and the quoted price. An approval for an embedding run is not an approval -for this one. Then call `resolveConfirmation({ id: confirmation_id, decision: "approve" })`. +**Ask for the user's explicit yes in one message.** Name the dataset, the label column, the +base model, the values you chose and the quoted price. Say the run is queued and waits for +their yes, and that any value can be changed before it starts, with a new quote. An +approval for an embedding run is not an approval for this one, and an earlier "sounds good" +about the plan is not approval for the run. Then call `resolveConfirmation({ id: confirmation_id, decision: "approve" })`. If they decline, resolve it with `"reject"`. To change anything, reject the queued confirmation, then queue again with @@ -147,8 +157,9 @@ claiming a quality verdict the tools cannot support. ## Conventions -`datasetId`, never a path · scope is derived from the signed-in user · verify the label +`datasetId`, never a path · scope is derived from the signed-in user · check the label column before queuing · validate with a separate dataset, never a split · send only the -schema's fields · queue → relay the quote → explicit yes → `resolveConfirmation` · poll the +schema's fields · no approval before queuing · queue → choices and quote in one message → +explicit yes → `resolveConfirmation` · poll the run · a new fine-tune can run here at once, promoted or not · never print credentials or raw upstream errors. diff --git a/plugins/helical-platform/skills/in-silico-perturbation/SKILL.md b/plugins/helical-platform/skills/in-silico-perturbation/SKILL.md index 29ff301..f155aa6 100644 --- a/plugins/helical-platform/skills/in-silico-perturbation/SKILL.md +++ b/plugins/helical-platform/skills/in-silico-perturbation/SKILL.md @@ -77,12 +77,16 @@ How to edit a gene, on raw counts: State the edit you chose; it is your decision, not a platform default. -## 3. Price it, then confirm +## 3. Estimate the price -Price before uploading anything: the cost depends on the combined file's cell count, so +Estimate before uploading anything: the cost depends on the combined file's cell count, so work it out with the rates from `listModels` as `check-credits` describes. Each model is **one job** over the whole combined file. Show the user the cell count, the per-model -estimate and the total, and get their yes before spending. +estimate and the total. + +Do not ask for a yes here. Every run that spends credit needs the user's explicit approval +of the platform's quote in step 5, and uploading spends no credit. Stop to ask now only when +the total exceeds the user's balance (read it fresh with `whoami()`, per `check-credits`). If the total is too much, cut cells or genes; do not split into per-gene runs, which pays the per-job amount once per gene. @@ -102,7 +106,7 @@ dataset, so the derivation is on record. Follow `compute-embeddings` for each model on the registered dataset: queue the run, show the platform's own quote, and approve only after the user says yes. That quote replaces -your estimate. +your estimate. Each model needs its own yes, against its own quote. ## 6. Download and score @@ -143,5 +147,5 @@ edited and how, how many cells, and any assumption about row order. Edit counts locally, never embeddings · the model sees every condition · one combined file, one run per model · always include an expression-matched null · score within cell type -against the reference centroid · check identity is preserved · estimate → show the price → -explicit yes → run · hypotheses, not hits · never print credentials or raw upstream errors. +against the reference centroid · check identity is preserved · estimate → upload → queue → +quote → explicit yes → run · hypotheses, not hits · never print credentials or raw upstream errors.