Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion plugins/helical-platform/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down
2 changes: 1 addition & 1 deletion plugins/helical-platform/plugin.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down
4 changes: 4 additions & 0 deletions plugins/helical-platform/skills/compute-embeddings/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
35 changes: 23 additions & 12 deletions plugins/helical-platform/skills/fine-tune-model/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand All @@ -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`.
Expand Down Expand Up @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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.
16 changes: 10 additions & 6 deletions plugins/helical-platform/skills/in-silico-perturbation/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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

Expand Down Expand Up @@ -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.
Loading